Mova deals e crie tarefas no Orbit

Hoje a única forma de falar com a API do Orbit é logando como gente — não serve para uma integração servidor-a-servidor. A API de eventos resolve isso: uma chave por organização, gerada uma vez, usada em toda chamada.

Dois tipos de evento hoje: mover_estagio (a ação principal — move um deal pra etapa certa do funil) e criar_tarefa.

1. No painel do Orbit, abra /dashboard/api-publica (link "Gerar chave" no topo desta página).
2. Clique em Gerar nova chave.
3. O valor completo (orbit_live_<prefixo>.<segredo>) aparece uma única vez, na hora da criação — copie e guarde num cofre de segredo do seu lado (variável de ambiente, secret manager). Depois disso o Orbit só guarda o hash, não é recuperável — mesma regra de senha.
4. Dá pra revogar e gerar outra a qualquer momento, sem downtime — gere a nova antes de revogar a antiga.

Toda chamada é um POST em /api/public/v1/events, com a chave no cabeçalho Authorization.

dados: {"estagio": "Nome do estágio"} — o nome é resolvido contra os estágios do funil da sua organização.

curl -X POST https://orbit.solanis.ai/api/public/v1/events \
  -H "Authorization: Bearer orbit_live_SEU_PREFIXO.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{
    "tipo": "mover_estagio",
    "cnpj": "01.234.567/0001-89",
    "dados": { "estagio": "Qualificado" }
  }'

Resposta

{
  "ok": true,
  "contato_criado": false,
  "deal_criado": false,
  "resultado": {
    "id": 812,
    "contact_id": 4417,
    "stage_id": 3,
    "title": "Empresa Exemplo Ltda",
    "value": 0,
    "won": null,
    "updated_at": "2026-10-14T16:19:14Z"
  }
}

• CNPJ novo → cria contato + deal, direto na etapa pedida.
• CNPJ já conhecido, sem deal → cria o deal nessa etapa.
• CNPJ com deal existente → move esse deal pra etapa pedida.
• Estágio mudou de verdade → dispara o webhook lead.stage_changed (ver última seção).

dados: {"titulo", "descricao", "vencimento"} (vencimento em YYYY-MM-DD, opcional).

curl -X POST https://orbit.solanis.ai/api/public/v1/events \
  -H "Authorization: Bearer orbit_live_SEU_PREFIXO.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "criar_tarefa",
    "cnpj": "01.234.567/0001-89",
    "dados": {
      "titulo": "Ligar pra confirmar reunião",
      "descricao": "Cliente pediu retorno até sexta",
      "vencimento": "2026-10-20"
    }
  }'

Mesma resolução de CNPJ do mover_estagio — cria o contato se precisar, sem criar deal.

O CNPJ é normalizado pra dígitos antes de qualquer comparação — pontuação, espaços, não importa. Os três formatos abaixo resolvem pro MESMO contato:

"01.234.567/0001-89"   // com pontuação — funciona
"01234567000189"       // só dígitos — funciona, mesmo contato
"  01234567000189  "   // com espaços — funciona, mesmo contato

O dígito verificador é validado de verdade — um CNPJ com dígito errado devolve cnpj_invalido, não cria nada.

Sistema que não recebe resposta a tempo vai reenviar. Para não duplicar deal ou tarefa nesse reenvio, mande um cabeçalho opcional Idempotency-Key (string livre, escolhida por você) — a mesma chave nas últimas 24h devolve a resposta salva da primeira vez, sem reprocessar.

• Sem o cabeçalho, cada chamada processa normal (sem proteção).
• Chave diferente = evento novo, processa normal.
• Duas requisições com a MESMA chave ao mesmo tempo: uma processa, a outra espera — nunca duplica.

60 eventos por minuto, por organização (não por chave — duas chaves da mesma org compartilham o teto). Passar do limite devolve limite_de_taxa_excedido.

Toda falha tem o mesmo formato:

{
  "ok": false,
  "erro": "estagio_desconhecido",
  "mensagem": "Estágio 'Fechado' não existe. Estágios válidos: Novo, Qualificado, Proposta, Negociação, Ganho, Perdido"
}

Depois que um evento move um deal de estágio de verdade, o Orbit dispara o webhook lead.stage_changed pelo canal que sua organização já configurou — mesmo mecanismo de saída usado pelo resto do Orbit, nada novo aqui.