CRM e Radar pela API

Use a base https://botozap.com.br/api/v1 com Authorization: Bearer $BOTOZAP_KEY ou X-API-Key. A Conta é derivada da chave; não envie account_id. Os exemplos mostram o caminho depois desse prefixo.

Um contato pode ter várias oportunidades e demandas independentes do Funil de contatos, que continua funcionando como antes. Encerrar uma conversa não encerra registros de CRM. Retornos e notas das conversas estão em Atendimento pela API; compromissos, em Agenda e Google Calendar.

Permissões, plano e ambiente

As rotas seguem a disponibilidade do Funil no plano da Conta: sem ele, retornam 403 feature_unavailable. Chaves live e sandbox são aceitas, e cada uma só enxerga contatos e conversas de Contas de canal do próprio ambiente. Um registro de contato do outro ambiente responde 404 not_found. A única exceção é a gravação de critérios do Radar, que exige chave live.

Rotas

{recurso} é opportunities ou demands. IDs são UUID; um valor malformado retorna 422 invalid_id.

Oportunidades

Demandas

O desfecho acompanha o estado. Em resolved ou closed, outcome é obrigatório, e resolved só aceita outcome: "resolved". Nos demais estados, outcome precisa ser null: para reabrir uma demanda, envie o novo estado e outcome: null no mesmo PATCH. Combinações inválidas retornam 422 invalid_request.

closed_at é preenchido automaticamente quando a oportunidade sai de open ou a demanda chega a resolved ou closed, e volta a null ao reabrir.

Campos personalizados

metadata segue o formato dos campos de contato: objeto plano, até 32 chaves com letras minúsculas, dígitos e sublinhado (1 a 40 caracteres), valores de texto (até 256 caracteres), número ou booleano, e até 8192 bytes no total. null não é aceito como valor. No PATCH, o objeto enviado substitui o anterior por inteiro: leia o registro, altere as chaves e envie o objeto completo.

Criar

POST /opportunities
{
  "customer_id": "UUID-DO-CLIENTE",
  "contact_id": "UUID-DO-CONTATO",
  "title": "Plano anual",
  "value_cents": 129900,
  "currency": "BRL",
  "next_step": "Enviar proposta",
  "next_step_at": "2026-10-01T14:00:00-03:00"
}

O contato precisa pertencer ao Cliente informado e ao ambiente da chave. Etapa, responsável ou oportunidade relacionada de outro Cliente, contato ou Conta retornam 422 invalid_request. Campos fora das tabelas acima também são recusados com 422 invalid_request.

A resposta traz o registro completo, incluindo id, status, closed_at, version, created_at, updated_at e last_activity_at. Oportunidades também trazem stage_entered_at.

Editar sem sobrescrever outra alteração

Envie em PATCH apenas os campos que mudam, junto de expected_version com a version lida. Cada alteração incrementa a versão e atualiza last_activity_at.

PATCH /opportunities/{id}
{
  "expected_version": 3,
  "status": "lost",
  "outcome_reason": "Escolheu outro fornecedor"
}

• Versão diferente da atual retorna 409 conflict sem aplicar a alteração. Releia e concilie.
• Sem expected_version (inteiro positivo), o corpo é recusado com 422 invalid_request.
• O corpo é estrito: campo desconhecido, customer_id ou contact_id retornam 422 invalid_request.
• Um PATCH só com expected_version retorna 422 invalid_request.

Listar

GET /opportunities e GET /demands exigem customer_id e aceitam:

A ordem é do mais recente para o mais antigo. A resposta traz data e meta (page, per_page, total_pages, total_count), além dos headers de paginação. Página além do último resultado retorna lista vazia.

Histórico

GET /{recurso}/{id}/activities?page=N retorna 20 eventos por página, do mais recente para o mais antigo; per_page é ignorado. Cada item contém:

Conversas vinculadas

GET /{recurso}/{id}/conversations lista { conversation_id, created_at }, 20 por página. POST vincula e DELETE desvincula; os dois recebem o mesmo corpo e respondem 200:

POST /demands/{id}/conversations
{ "conversation_id": "UUID-DA-CONVERSA" }

200
{ "data": { "conversation_id": "UUID-DA-CONVERSA", "linked": true } }

No DELETE, a resposta traz linked: false. Repetir um vínculo existente ou remover um vínculo ausente não gera erro. A conversa precisa ser do mesmo contato e Cliente do registro (senão, 422 invalid_request) e do ambiente da chave (senão, 404 not_found). Mensagens nas conversas vinculadas contam como atividade para o Radar.

Erros

Radar de acompanhamento

GET /radar?customer_id=UUID exige crm:read e reúne, para um Cliente, o que precisa de ação: oportunidades, demandas, retornos pendentes e compromissos. A leitura não altera registros nem envia mensagens.

Filtro com valor desconhecido retorna 422 invalid_filters. Críticos vêm primeiro, depois atenção e programados; dentro de cada grupo, os itens sem data e os de data mais próxima vêm antes. meta.counts traz os totais critical, at_risk e scheduled com os filtros de tipo, responsável e motivo, sem o filtro bucket; meta.total_count considera também o bucket. Páginas além do último resultado retornam lista vazia e preservam os totais.

Tipos de item

Um item só aparece quando tem ao menos um motivo ou algo programado; oportunidades e demandas em dia ficam fora da lista.

Motivos

Prioridade

Cada item traz id, entity_type, customer_id, contact_id, conversation_id (retornos e compromissos), title, owner_user_id, stage_id, next_step, next_step_at, bucket, reasons (lista), last_activity_at, automation_status, automation_due_at, automation_run_id, automation_error e bucket_priority. Quando uma oportunidade ou demanda sem próximo passo tem um compromisso futuro vinculado, o próximo passo exibido é esse compromisso.

Critérios por etapa

GET /radar/stage-rules?customer_id=UUID lista as etapas configuradas. Etapa sem configuração usa atenção após 24 horas e criticidade após 72 horas, exigindo responsável e próximo passo. O critério vale para as oportunidades da etapa: tempo na etapa e última atividade são avaliados separadamente.

PUT /radar/stage-rules/{stage_id}
{
  "customer_id": "UUID-DO-CLIENTE",
  "expected_version": 0,
  "cold_hours": 48,
  "critical_hours": 120,
  "require_owner": true,
  "require_next_step": false
}

• cold_hours (atenção): inteiro de 1 a 8760.
• critical_hours: inteiro de 1 a 26280, maior ou igual a cold_hours.
• Todos os campos são obrigatórios e o corpo é estrito. Erros de validação retornam 422 invalid_request.
• Na primeira configuração, envie expected_version: 0; depois, a versão consultada. Versão obsoleta retorna 409 conflict.
• Etapa de outro Cliente retorna 404 not_found.

A gravação exige crm:write e chave live, porque o critério vale para os dois ambientes do Cliente; chave sandbox recebe 403 sandbox_forbidden. A listagem do Radar respeita o ambiente da chave. No painel, qualquer membro da conta altera critérios.

Eventos

Criar ou alterar registros publica crm.opportunity.created, crm.opportunity.updated, crm.demand.created e crm.demand.updated, com before_data e after_data. Consulte o formato em Eventos de webhook.

Os erros comuns de chave, escopo e limite estão em Autenticação. A referência /v1 lista todas as rotas.