> ## 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.

# Visão geral da Orders API

> Base URL, endpoints, autenticação, idempotência, requestId, dinheiro em centavos e datas.

A Orders API é a interface pública estável para seu backend enviar pedidos para a Atriby.

## Base URLs

Produção:

```text theme={null}
https://app.atriby.com
```

Local:

```text theme={null}
http://localhost:3000
```

## Endpoints

| Método  | Endpoint                      | Uso                                   |
| ------- | ----------------------------- | ------------------------------------- |
| `POST`  | `/api/v1/orders`              | Criar pedido.                         |
| `GET`   | `/api/v1/orders`              | Listar pedidos com filtros.           |
| `GET`   | `/api/v1/orders/{externalId}` | Consultar um pedido.                  |
| `PATCH` | `/api/v1/orders/{externalId}` | Atualizar status e campos permitidos. |

## Referências rápidas

* Consulte [Atualizar pedido](/orders/update-order) para payloads de `PATCH` e transições de status.
* Consulte [Erros](/orders/errors) para códigos de erro, `requestId` e exemplos de resposta.

## Autenticação

Todas as chamadas usam:

```http theme={null}
Authorization: Bearer <api_token>
```

## Idempotência

Use `Idempotency-Key` em `POST` e `PATCH`:

```http theme={null}
Idempotency-Key: order_001_create
```

Replays com a mesma chave e o mesmo endpoint retornam a resposta cacheada por até 24 horas.

## Request ID

Você pode enviar:

```http theme={null}
X-Request-Id: req_checkout_123
```

Se não enviar, a Atriby gera um identificador. Erros retornam `requestId` no corpo e `X-Request-Id` no header.

## Dinheiro em centavos

Valores monetários são inteiros em centavos:

```json theme={null}
{
  "grossCents": 20000,
  "netToSellerCents": 17000
}
```

Não envie floats como `199.90`.

## Datas com timezone

Datas precisam ser ISO 8601 com timezone:

```text theme={null}
2026-05-10T15:34:14Z
2026-05-10T12:34:14-03:00
```

Datas sem timezone retornam `400 VALIDATION_FAILED`.