## Visão geral

O registro de Pedidos aceita vendas vindas de fora da plataforma. Você recebe uma URL de ingestão
própria da conta e envia cada pedido por `POST` — de um checkout próprio, de um ERP, de uma
automação ou de um gateway que a Conversa Labs ainda não integre nativamente.

A URL carrega um token opaco que identifica a conta. Não existe outro cabeçalho de autenticação:
quem tem a URL consegue registrar pedidos na sua conta, então trate-a como senha.

## Pré-requisitos

- O módulo **Pedidos** precisa estar habilitado na conta. Com ele desligado, a URL responde `404`.
- Perfil de administrador (ou permissão de gestão do CRM) para abrir e girar o token.

## Passo a passo

1. Abra **Pedidos** e clique em **Endpoint de ingestão**.
2. Copie a **URL de ingestão**. O campo **Token** aparece mascarado — use o olho para revelar e o
   botão ao lado para copiar apenas o token.
3. Cole a URL no seu sistema de origem e envie o pedido conforme o exemplo abaixo.
4. Confirme que o pedido apareceu na lista. Reenviar o mesmo `external_id` atualiza o pedido, não
   cria outro.

```
curl -X POST 'https://SUA-INSTALACAO/public/api/v1/orders/ingest/SEU-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "gateway": "meu_checkout",
    "external_id": "PED-10231",
    "email": "cliente@example.com",
    "title": "Plano Pro anual",
    "amount": 149.9,
    "currency": "BRL",
    "status": "paid",
    "ordered_at": "2026-08-11T10:00:00-03:00",
    "line_items": [
      { "name": "Plano Pro anual", "quantity": 1, "unit_price": 149.9 }
    ]
  }'
```

## Campos do corpo

| Campo | Obrigatório | O que é |
|---|---|---|
| `gateway` | Sim | Identifica a origem do pedido (ex.: `meu_checkout`, `hotmart`). |
| `contact_id` / `email` / `phone_number` | Sim (um deles) | Referência para encontrar ou criar o contato. Envie também `name` para nomear um contato novo. |
| `external_id` | Não, mas recomendado | O identificador do pedido no seu sistema. É o que torna o reenvio idempotente. |
| `status` | Não | Um entre `pending`, `partially_paid`, `paid`, `overdue`, `failed`, `canceled`, `refunded`. |
| `amount` e `currency` | Não | Valor total em unidades maiores (`149.9` = R$ 149,90) e a moeda em ISO-4217. |
| `ordered_at` e `paid_at` | Não | Datas ISO-8601 com fuso. Sem elas, vale o momento do recebimento. |
| `line_items` | Não | Itens com `name`, `quantity`, `unit_price` e, quando houver, `catalog_product_id`, `catalog_variant_id`, `discount` e `metadata`. |
| `title`, `crm_item_id`, `affiliate_id`, `metadata`, `raw` | Não | Complementos. O afiliado só é creditado se pertencer a esta conta e estiver ativo. |

## Respostas

- `201` — `{"status": "ok"}`. Pedido registrado ou atualizado.
- `422` — `invalid_payload` (falta `gateway`), `contact_reference_required` (falta a referência de
  contato), `invalid_order_status` (status fora da lista) ou `contact_unresolvable` (não foi possível
  encontrar nem criar o contato).
- `404` — token ausente, já girado, ou módulo de Pedidos desligado na conta.

## Dicas, limites e boas práticas

- **Sempre envie `external_id`.** Sem ele, uma reentrega do seu gateway vira um pedido duplicado.
- O endpoint é limitado por taxa por token. Em cargas grandes, envie em série e trate `429` com
  espera progressiva.
- Girar o token invalida a URL antiga **na hora**. Faça isso apenas com a integração pronta para
  receber a nova URL — e atualize-a imediatamente.
- Valores vão em unidades maiores, com ponto decimal. Não envie centavos como inteiro.

## Solução de problemas

- **Recebo `404` em tudo:** a URL foi girada ou o módulo Pedidos está desligado na conta.
- **Recebo `422 contact_reference_required`:** o corpo não trouxe `contact_id`, `email` nem
  `phone_number`.
- **O mesmo pedido aparece duas vezes:** o envio saiu sem `external_id`, ou com um valor diferente a
  cada tentativa.
- **O afiliado não recebeu comissão:** o `affiliate_id` não pertence a esta conta ou está inativo.

## Veja também

- [Central de reconciliação de vendas](/hc/ajuda/articles/catalog-commerce-reconciliacao-de-vendas-pt-br)
- [Ciclo de vida do comércio](/hc/ajuda/articles/catalog-commerce-commerce-lifecycle-pt-br)