API Pública do ChatForce 2.0

v1 · https://2.0.chatforce.com.br/api/v1 · JSON · Bearer + HMAC

Autenticação e assinatura

Cabeçalhos de toda requisição autenticada:

Em GET/HEAD o corpo é vazio: assine "{timestamp}.".

Falha de autenticação → 401 (token, timestamp ou assinatura inválidos).

Idempotência

Envie Idempotency-Key (ex.: UUID) nas escritas. Repetir a mesma chave com o mesmo corpo devolve a resposta original (Idempotency-Replayed: true); com corpo diferente devolve 409.

Escopo e limites

• Token de usuário: limitado às contas acessíveis. Token de agente (cfa_): sem acesso a recursos de conta (403).
• 120 requisições/min por ator; per_page máximo 100.
• Recurso fora do escopo → 404.

Erros

Saúde

GET /health

Público. Retorna { "status": "ok", "checks": { "database": true, "cache": true } }.

Identidade

GET /me

Retorna o ator e o escopo de contas (account_scope; null = sem restrição).

Mensagens

POST /messages/{inbox_path}

Recebe mensagem de um sistema externo na Caixa de API. Requer Idempotency-Key.

201 novo · 200 replay (replayed=true) · 409 event_id/conversa em conflito.

POST /webhooks/inbox/{token}

Recepção universal da Caixa de API para o gateway de WhatsApp (Evolution API). Diferente do endpoint acima, não usa Bearer/HMAC: a autenticação é o token da própria caixa na URL. Aceita o payload nativo da Evolution e monta contato, conversa e mensagem (texto e mídia).

Como usar: na aba Canal da caixa de API, informe URL do servidor, Instância e API Key do Evolution e salve como Conectado — o ChatForce cadastra este webhook na instância automaticamente. 200 recebido (eventos irrelevantes são ignorados).

Contatos

GET /contacts

Filtros: search, email, phone, updated_since, page, per_page.

GET /contacts/{contact}

Detalhe do contato.

POST /contacts

Obrigatórios: name, phone. Opcionais: email, document, client_code, company, country, state, city, address, description, avatar_url.

PATCH /contacts/{contact}

Atualiza os mesmos campos + is_blocked.

Conversas

GET /conversations

Filtros: status, inbox_id, contact_id, team_id, assigned_user_id, updated_since, page, per_page.

GET /conversations/{conversation}

Detalhe da conversa.

GET /conversations/{conversation}/messages

Mensagens visíveis (ordem cronológica).

POST /conversations/{conversation}/messages

Envia mensagem. Corpo: body (obrigatório), destination (customer/team, padrão customer), reply_to_id.

PATCH /conversations/{conversation}

Atualiza assigned_user_id, team_id, status (in_progress/closed), resolution_reason_id (obrigatório ao fechar), resolution_notes.

Caixas

GET /inboxes

Filtros: channel, is_active.

GET /inboxes/{inbox}

Detalhe da caixa.

Tags

GET /tags

Filtro: search.

Pipelines

GET /pipelines

Filtro: is_active. Inclui etapas.

GET /pipelines/{pipeline}

Detalhe do funil.

Pedidos

GET /orders

Filtros: contact_id, external_number, status, approval_status, from, to.

GET /orders/{order}

Detalhe do pedido (com itens).

POST /orders

Obrigatórios: contact_id, number. Opcionais: conversation_id, opportunity_id, proposal_id, external_number, currency, status, notes e items[] (description, quantity, unit_price, discount). total e approval_status são calculados.

POST /orders/sync

Sincronização idempotente por external_number, indicada para ERPs e outros sistemas que mantêm o pedido do lado externo.

• Se não existir pedido com o external_number informado (dentro do escopo do token), cria e retorna 201.
• Se existir, atualiza o pedido, substitui os itens e recalcula o total, retornando 200.

Obrigatórios: external_number, contact_id. Opcionais: number (se omitido na criação, é gerado), conversation_id, opportunity_id, proposal_id, currency, status, notes e items[]. Envie sempre o mesmo external_number do sistema de origem para evitar duplicidade.

PATCH /orders/{order}

Atualiza o pedido; se items for enviado, substitui os itens e recalcula o total.

Oportunidades

GET /opportunities

Filtros: status, contact_id, pipeline_id, external_id, updated_since.

GET /opportunities/{opportunity}

Detalhe da oportunidade.

POST /opportunities

Cria ou atualiza por external_id. Obrigatórios: title, pipeline_id, stage_id. Contato por contact_id ou contact_email/contact_phone. Opcionais: assigned_user_id, value, currency, expected_close_at, notes. status é derivado da etapa.

PATCH /opportunities/{opportunity}

Atualiza campos; ao mudar stage_id, status é recalculado.

Tickets

GET /tickets

Filtros: status, priority, contact_id, assigned_user_id, updated_since.

GET /tickets/{ticket}

Detalhe do ticket (com respostas).

POST /tickets

Obrigatórios: subject, priority. Opcionais: description, due_at, contact_id, conversation_id, order_id, team_id, assigned_user_id. protocol é gerado.

POST /tickets/{ticket}/replies

Responde o ticket. Corpo: body.

Campanhas

GET /campaigns

Filtros: status, type.

GET /campaigns/{campaign}

Detalhe da campanha com estatística.

POST /campaigns/{campaign}/events

Registra evento. Corpo: type (sent, delivered, read, replied, click, conversion, opt_out, error), campaign_recipient_id, contact_id, payload.

Webhooks

Links

GET /l/{code} — redireciona (302) e registra o clique com UTMs.