# Criar pedido (https://docs.rivoo.gg/api/referencia/pedidos/criar-pedido)

`POST https://api.rivoo.gg/v1/orders`

Cria um pedido com produtos do catálogo. Mande o comprador para o `checkoutUrl` da resposta para pagar. Use `Idempotency-Key` para não duplicar.

**Permissão da chave:** Pedidos › escrever.

Autenticação: `Authorization: Bearer <chave de API>`.

## Parâmetros

| Nome | Onde | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | sim | Chave única por operação (ex.: o id do pedido no seu sistema). Repetir a chamada com a mesma chave devolve a mesma resposta, sem duplicar. |

## Corpo (JSON)

```json
{
  "type": "object",
  "properties": {
    "items": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string",
            "example": "prod_mhexample0000vip00001"
          },
          "quantity": {
            "type": "number",
            "minimum": 1,
            "maximum": 100,
            "example": 1
          }
        },
        "required": [
          "productId",
          "quantity"
        ]
      }
    },
    "customer": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "example": "steve@exemplo.com"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "example": "Steve"
        }
      },
      "required": [
        "email"
      ]
    },
    "recipient": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "example": "Steve"
        }
      },
      "required": [
        "name"
      ]
    },
    "externalId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "example": "pedido_123"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    },
    "successUrl": {
      "type": "string",
      "format": "uri",
      "example": "https://seusite.com/obrigado"
    },
    "cancelUrl": {
      "type": "string",
      "format": "uri",
      "example": "https://seusite.com/carrinho"
    },
    "expiresInMinutes": {
      "type": "number",
      "minimum": 5,
      "maximum": 10080
    },
    "allowedMethods": {
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "PIX",
          "PIX_AUTOMATIC",
          "CARD",
          "BOLETO"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}
```

## Exemplo

```bash
curl -X POST "https://api.rivoo.gg/v1/orders" \
  -H "Authorization: Bearer $RIVOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"productId":"prod_mhexample0000vip00001","quantity":1}]}'
```

## Resposta 201



```json
{
  "id": "ord_mhexample0000vip0000001",
  "source": "API",
  "status": "OPEN",
  "customerId": "cus_mhexample0000steve00001",
  "externalId": "pedido_123",
  "recipient": {
    "kind": "MINECRAFT",
    "ref": "Steve",
    "name": "Steve"
  },
  "items": [
    {
      "id": "oitem_mhexample0000vip00001",
      "productId": "prod_mhexample0000vip00001",
      "priceId": "price_mhexample0000vip0001",
      "name": "VIP+ 30 dias",
      "quantity": 1,
      "unitAmount": {
        "amount": 2990,
        "currency": "BRL"
      },
      "total": {
        "amount": 2990,
        "currency": "BRL"
      },
      "adjustments": [],
      "recipient": null,
      "gift": null
    }
  ],
  "totals": {
    "subtotal": {
      "amount": 2990,
      "currency": "BRL"
    },
    "discount": {
      "amount": 0,
      "currency": "BRL"
    },
    "giftCard": {
      "amount": 0,
      "currency": "BRL"
    },
    "total": {
      "amount": 2990,
      "currency": "BRL"
    },
    "refunded": {
      "amount": 0,
      "currency": "BRL"
    }
  },
  "allowedMethods": [
    "PIX",
    "CARD",
    "BOLETO"
  ],
  "paidByPaymentId": null,
  "note": null,
  "metadata": {
    "pedido": "123"
  },
  "customer": {
    "id": "cus_mhexample0000steve00001",
    "name": "Steve",
    "email": "steve@exemplo.com"
  },
  "expiresAt": "2026-11-01T21:04:13.000Z",
  "paidAt": null,
  "expiredAt": null,
  "canceledAt": null,
  "createdAt": "2026-10-31T21:04:13.000Z",
  "checkoutUrl": "https://rivoo.gg/pay/c/ord_mhexample0000vip0000001?k=exemplo"
}
```

## Resposta 400

`idempotency_key_required`

## Resposta 401

`unauthenticated`, `invalid_api_key`

## Resposta 403

`permission_denied`

## Resposta 409

`idempotency_in_progress`, `external_id_taken`, `recipient_not_supported`

## Resposta 422

`validation_failed`, `idempotency_key_reused`, `product_unavailable`, `total_below_minimum`, `no_payment_method`, `project_unavailable`

## Resposta 429

`rate_limited`