Pedidos
O objeto Order representa uma transação comercial. Ele rastreia tudo, desde a colocação inicial até o atendimento final e a liquidação financeira.
O Objeto Pedido
Um detalhamento de todos os campos disponíveis no recurso Pedido.
Identidade e Metadados
| Field | Type | Description |
|---|---|---|
idRequired | string | Identificador único do pedido. Prefixado com 'ord_'. Example: ord_01JGK9 |
numberRequired | string | O número do pedido legível mostrado aos clientes. Example: BS-10024 |
external_id | string | O ID do seu sistema de origem (ERP, Shopify, etc). Example: 9928120 |
created_at | datetime | Timestamp ISO 8601 de quando o pedido foi criado. |
Financeiro
| Field | Type | Description |
|---|---|---|
currencyRequired | string | Código de moeda ISO de três letras. Example: BRL |
total_amountRequired | decimal | Valor total do pedido, incluindo impostos e frete. Example: 245.00 |
tax_amount | decimal | Total de impostos aplicados. |
payment_status | enum | Estado financeiro atual: 'authorized', 'captured', 'refunded', 'voided'. Example: captured |
Atendimento
| Field | Type | Description |
|---|---|---|
statusRequired | enum | Estado atual do fluxo de trabalho: 'pending', 'processing', 'shipped', 'delivered', 'cancelled'. Example: processing |
shipping_method | string | O serviço de transportadora selecionado. Example: fedex_ground |
tracking_number | string | Identificador de rastreamento ao vivo da transportadora. |
Listar Pedidos
GET /v1/ordersRecupere uma lista de pedidos. Use parâmetros de consulta para filtrar por status ou intervalo de datas. Os resultados são paginados por padrão.
Parâmetros de Filtro
| Field | Type | Description |
|---|---|---|
status | string | Filtrar por código de status (ex: 'processing') |
customer_id | string | Filtrar pedidos de um cliente específico. |
limit | integer | Resultados por página. Máximo 100. Example: 50 |
offset | integer | Número de registros a pular. |
Criar Pedido
POST /v1/ordersCrie um novo pedido. Isso acionará o fluxo de trabalho padrão, incluindo a alocação de estoque e a sincronização com o ERP.
Efeitos Colaterais
A criação de um pedido via API reserva automaticamente o estoque na Nuvem de Estoque. Se o estoque não estiver disponível, a solicitação retornará um erro 422 Unprocessable Entity.
Erros Comuns
422: FORA_DE_ESTOQUEUm ou mais SKUs na solicitação não estão mais disponíveis na quantidade necessária.
401: AUTH_INVALIDAA chave da API fornecida expirou ou não possui as permissões 'order:write'.