Como funciona

O módulo de Aceite é dividido em duas responsabilidades: receber a requisição e persistir o registro (rápido, síncrono) e validar o template, falar com o canal e entregar o recibo (assíncrono, resiliente a falhas transitórias e reentregas). Essa separação existe para que criar um aceite responda rápido, enquanto o trabalho pesado acontece em segundo plano.

flowchart LR
    T["Seu sistema"] -- "POST /acceptances\nPOST .../status\nPOST .../step\nGET /reports" --> API["API do módulo de Aceite"]
    API -- "envia mensagem" --> Canal["Canal (WhatsApp)"]
    Canal -- "entrega ao destinatário" --> User["Destinatário final"]
    Canal -- "callback de status\n(SENT, DELIVERED, READ...)" --> API
    User -- "clica no botão" --> Canal
    API -- "POST webhook_url\n(recibo final, retry exponencial)" --> T

💾 Modelo de dados

• Aceite (Acceptance) — um fluxo de confirmação/notificação enviado a um destinatário, identificado por acceptance_id, rastreado do PENDING até um status final.
• Template — definição reutilizável da mensagem (passos, variáveis, transições de botão), cadastrada e aprovada junto à Clicksign e ao canal. Referenciado pelo aceite via template_id — o texto do template não viaja na requisição de criação, apenas as variáveis de preenchimento.
• Trilha (Trail) — sequência de eventos de status que reconstrói o histórico completo de um aceite. É a base do recibo entregue por webhook e do que é retornado em GET /api/v1/reports/{id}.
• Recibo (Receipt) — o payload entregue ao seu webhook_url quando o aceite atinge um status final. Contém a trilha completa.

🔄 Ciclo de vida do status

PENDING   — aceite criado, aguardando envio ao canal
SENT      — mensagem enviada ao destinatário
DELIVERED — mensagem entregue ao dispositivo
READ      — mensagem lida pelo destinatário
ACCEPTED  — aceite confirmado (final)
DECLINED  — aceite recusado (final)
EXPIRED   — aceite expirado sem resposta (final)

Pontos importantes sobre a máquina de estados:

• A sequência não é validada. O canal pode entregar eventos fora de ordem (ex.: READ antes de DELIVERED) — todos são registrados na trilha, na ordem de chegada.
• Estados finais não admitem mais transição. Em fluxos com decisão (Módulo de Aceite), os finais são ACCEPTED, DECLINED e EXPIRED. Em fluxos apenas informativos (Módulo de Notificação, sem botões), os finais são SENT e DELIVERED — não existe ACCEPTED/DECLINED porque não há decisão a ser tomada.
• "Primeiro final vence." Se chegar um evento com status final diferente do já registrado como final, ele é descartado silenciosamente.
• Reentrega é idempotente. Se chegar o mesmo status final de novo (ex.: reentrega do canal), não é criado um novo item na trilha — mas o serviço ainda garante a tentativa de entrega do webhook, caso a anterior não tenha sido confirmada.
• Falha síncrona na criação encerra o fluxo. Um 400/401/403/422 em POST /api/v1/acceptances significa que nenhum aceite foi criado — não há reprocessamento a esperar.

📍 Endpoints

Referência completa, com Try It: Acceptances · Reports.

🔒 Autenticação

Header X-API-Key + X-API-Secret, fornecidos pela Clicksign no onboarding — não há autocadastro público de credencial. Veja Primeiros passos.

📨 POST /api/v1/acceptances/{id}/status e .../step: quem chama?

Essas duas rotas recebem eventos que se originam do canal de mensageria (ex.: confirmação de entrega, leitura, ou o clique de um botão pelo destinatário) — normalmente entregues por uma integração de canal já operada pela Clicksign, não pelo seu sistema. Documentamos o contrato aqui porque a mesma credencial pode ser usada para consultá-los ou simulá-los em ambiente de testes (ver recipe ponta a ponta).

⚙️ Módulo de Aceite vs. Módulo de Notificação — o que muda por trás

O motor é o mesmo; o que muda é o desenho do template:

• Módulo de Aceite — o passo final do template tem botões (transitions[].outcome: accepted / declined). O destinatário decide, e a decisão é o desfecho.
• Módulo de Notificação — o passo final do template não tem botões de decisão. O aceite se encerra sozinho quando a mensagem é enviada/entregue — não há ACCEPTED/DECLINED a aguardar.

Mais sobre a estrutura de passos e transições: Templates e canais.

Próximo passo ➡️

• Templates e canais — configure mensagens, variáveis e decisões.
• Webhooks e relatórios — receba o recibo final e consulte o histórico.