Central de Ajuda Conversa Labs
pt_BR
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

Endpoint de ingestão de pedidos

Abrir em
Ver como Markdown Abrir no ChatGPT Abrir no Claude
Conversa Labs

Conversa Labs

Última atualização em Aug 12, 2026

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