A API de cadências permite consultar rotinas e controlar a matrícula de um deal.
Todas as rotas exigem os recursos ADVANCED_API e CADENCE. Sem qualquer um deles, a API responde 403.
| Ação | Método e rota | Uso |
|---|---|---|
| Listar cadências | GET /api/v1/cadences |
Retorna o catálogo de cadências do workspace. |
| Listar matrículas | GET /api/v1/cadences/{cadenceId}/enrollments |
Retorna os deals matriculados em uma cadência. |
| Consultar a cadência do deal | GET /api/v1/deals/{seq}/cadence |
Retorna a instância e as tarefas do deal. |
Na listagem de matrículas, use status para filtrar a situação. Use day, step e at para restringir a posição da régua. at=reached inclui quem passou pela posição. at=ended inclui quem terminou nela.
| Ação | Método e rota | Efeito |
|---|---|---|
| Matricular um deal | POST /api/v1/deals/{seq}/cadence/enroll |
Substitui a cadência atual e pode começar em um dia específico. |
| Iniciar | POST /api/v1/deals/{seq}/cadence/start |
Inicia a instância do deal. |
| Pausar | POST /api/v1/deals/{seq}/cadence/pause |
Pausa a instância, com um motivo opcional. |
| Retomar | POST /api/v1/deals/{seq}/cadence/resume |
Retoma a instância pausada. |
| Remover | POST /api/v1/deals/{seq}/cadence/unenroll |
Para a instância e cancela tarefas abertas. |
POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/execute envia a tarefa ao provedor do canal. A operação envia de verdade por WhatsApp, e-mail ou chamada externa e pode gerar cobrança no workspace.
Envie uma idempotencyKey obrigatória. Uma repetição da mesma chave retorna duplicated: true sem enviar novamente.
Para alterar somente o estado da tarefa, use POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/skip ou POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/complete-manual. Essas rotas não enviam nada ao canal.
As tarefas da instância incluem o histórico attempts, com canal, sucesso, data e identificadores de envio quando disponíveis. Use esse histórico para diagnosticar uma falha antes de repetir a operação.
Guarde a idempotencyKey antes de executar. Se a resposta se perder, repita com a mesma chave; uma nova chave representa uma nova tentativa. Não trate skip ou complete-manual como confirmação de entrega ao cliente.