> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atriby.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar pedido

> Como usar POST /api/v1/orders com headers, payload mínimo, resposta e erros comuns.

Use `POST /api/v1/orders` quando seu checkout ou backend criar um pedido.

## Headers

```http theme={null}
Authorization: Bearer <api_token>
Content-Type: application/json
Idempotency-Key: order_001_create
```

## Payload mínimo

```json theme={null}
{
  "externalId": "order_001",
  "platform": "checkout",
  "paymentMethod": "credit_card",
  "status": "pending",
  "createdAt": "2026-05-10T15:34:14Z",
  "isTest": false,
  "amounts": {
    "currency": "BRL",
    "grossCents": 20000,
    "netToSellerCents": 17000
  },
  "products": [
    {
      "externalId": "prod_001",
      "sku": "SKU-001",
      "name": "Produto exemplo",
      "quantity": 1,
      "unitPriceCents": 20000
    }
  ],
  "tracking": {
    "utmSource": "facebook",
    "utmMedium": "cpc",
    "utmCampaign": "lancamento"
  }
}
```

## Campos opcionais úteis

* `customer`: dados do cliente.
* `fees`: taxas do gateway.
* `metadata`: objeto livre para dados operacionais não sensíveis.
* `trackingExtras`: parâmetros adicionais de tracking.
* `paidAt`, `refundedAt`, `chargedbackAt`: datas do ciclo de pagamento.
* `amounts.discountCents`, `shippingCents`, `taxesCents`, `totalFeesCents`: assumem `0` quando omitidos.

## Exemplo curl

```bash theme={null}
curl -X POST "https://app.atriby.com/api/v1/orders" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_001_create" \
  -d '{
    "externalId": "order_001",
    "platform": "checkout",
    "paymentMethod": "credit_card",
    "status": "pending",
    "createdAt": "2026-05-10T15:34:14Z",
    "isTest": false,
    "amounts": {
      "currency": "BRL",
      "grossCents": 20000,
      "netToSellerCents": 17000
    },
    "products": [
      { "name": "Produto exemplo", "quantity": 1, "unitPriceCents": 20000 }
    ],
    "tracking": {
      "utmSource": "facebook",
      "utmMedium": "cpc",
      "utmCampaign": "lancamento"
    }
  }'
```

## Resposta

```json theme={null}
{
  "order": {
    "id": "clx_internal_id",
    "externalId": "order_001",
    "status": "pending",
    "isTest": false
  }
}
```

## Erros comuns

| Código                  | Quando acontece                                                |
| ----------------------- | -------------------------------------------------------------- |
| `MALFORMED_JSON`        | JSON inválido.                                                 |
| `VALIDATION_FAILED`     | Campo obrigatório ausente, tipo inválido ou data sem timezone. |
| `UNAUTHORIZED`          | Token ausente ou inválido.                                     |
| `TOKEN_REVOKED`         | Token revogado.                                                |
| `DUPLICATE_EXTERNAL_ID` | Já existe pedido com o mesmo `externalId`.                     |
| `RATE_LIMIT_EXCEEDED`   | Limite por token atingido.                                     |