Pedidos
Do pedido criado pela API até a entrega, com padrões, erros e o ciclo de vida.
O fluxo de uma venda pela API tem quatro passos:
- Criar o pedido com os produtos e, se quiser, o comprador e o jogador.
- Mandar o comprador para o
checkoutUrlda resposta. - Receber o webhook
order.paide conferir a assinatura. - Buscar o pedido completo com Ver pedido e liberar a compra.
Criar
curl -X POST "https://api.rivoo.gg/v1/orders" \
-H "Authorization: Bearer $RIVOO_API_KEY" \
-H "Idempotency-Key: pedido_123" \
-H "Content-Type: application/json" \
-d '{
"items": [{ "productId": "prod_mhexample0000vip00001", "quantity": 1 }],
"customer": { "email": "[email protected]", "name": "Steve" },
"recipient": { "name": "Steve" },
"externalId": "pedido_123",
"metadata": { "pedido": "123" },
"successUrl": "https://seusite.com/obrigado"
}'| Campo | Obrigatório | Padrão | O que é |
|---|---|---|---|
items[] | sim | De 1 a 50 itens. Cada um tem productId e quantity (1 a 100). | |
customer | Comprador: email (obrigatório) e name (até 120 caracteres). Se o e-mail já existir na loja, o pedido vai para esse cliente. | ||
recipient | Quem recebe no jogo: name é o nick do jogador. Só em lojas que entregam para jogadores. | ||
externalId | O id do pedido no seu sistema, até 100 caracteres. Único por loja. | ||
metadata | Objeto livre. Volta igual no pedido. | ||
successUrl / cancelUrl | Para onde o comprador volta depois de pagar ou desistir. | ||
expiresInMinutes | 1440 (24 h) | Prazo para pagar, de 5 a 10080 (7 dias). | |
allowedMethods | os da loja | Meios aceitos: PIX, PIX_AUTOMATIC, CARD, BOLETO. Sem o campo, valem os meios ligados nas configurações da loja. |
Pedidos criados pela API usam o preço padrão de cada produto. Eles não aplicam cupons, promoções, limites de estoque nem requisitos de outros produtos: essas regras são da vitrine.
Erros ao criar
Além dos erros comuns:
| Status | code | Quando |
|---|---|---|
| 400 | idempotency_key_required | Faltou o header Idempotency-Key. |
| 409 | external_id_taken | Já existe um pedido com esse externalId na loja. |
| 409 | recipient_not_supported | Mandou recipient, mas a loja não entrega para jogadores. |
| 422 | validation_failed | Campo inválido (quantidade fora da faixa, e-mail inválido…). Veja errors[]. |
| 422 | product_unavailable | O produto não existe nesta loja, está arquivado ou não tem preço de compra única ativo. errors[].field traz o productId. |
| 422 | total_below_minimum | O total ficou acima de zero e abaixo de R$ 1,00. Pedido de R$ 0,00 passa. |
| 422 | no_payment_method | Nenhum dos allowedMethods está disponível para esse valor. |
| 422 | project_unavailable | A loja ou a conta está suspensa ou arquivada. |
Ciclo de vida
┌──▶ PAID ──┬──▶ PARTIALLY_REFUNDED ──▶ REFUNDED
│ └──────────────────────────▶ REFUNDED
OPEN ───────────┼──▶ EXPIRED
└──▶ CANCELED| De | Para | Quando | Webhook |
|---|---|---|---|
OPEN | Pedido criado. | order.created | |
OPEN | OPEN | Itens ou cupom mudaram antes do pagamento. | order.updated |
OPEN | PAID | Pagamento confirmado. | order.paid |
OPEN | EXPIRED | O prazo (expiresAt) passou sem pagamento. | order.expired |
OPEN | CANCELED | Cancelar pedido, ou cancelado no painel. | order.canceled |
PAID | PARTIALLY_REFUNDED | Parte do valor devolvida. | order.partially_refunded |
PAID / PARTIALLY_REFUNDED | REFUNDED | Todo o valor devolvido. | order.refunded |
PAID, EXPIRED, CANCELED e REFUNDED não voltam para OPEN. Veja o que cada status quer dizer em Status de pedido.
Depois do order.paid
O webhook traz só o essencial (id, source, total, paymentId). Para liberar a compra, busque o pedido completo, com itens, comprador, jogador e metadata:
curl "https://api.rivoo.gg/v1/orders/ord_mhexample0000vip0000001" \
-H "Authorization: Bearer $RIVOO_API_KEY"Se a loja entrega no jogo (plugin, agente RCON ou Discord), a Rivoo já roda as entregas sozinha. Se uma delas falhar, chega delivery.failed.
Valores
Dinheiro vem sempre como objeto, na API e nos webhooks: { "amount": 2990, "currency": "BRL" }, com amount em centavos. Os webhooks ainda mandam, ao lado, o campo antigo terminado em Cents (totalCents: 2990), depreciado: ele sai em 01/05/2027.