# Gerenciar cadências pela API

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`.

## Consultar cadências e matrículas

| 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.

## Alterar a matrícula

| 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.                     |

## Operar tarefas

`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.

## Tentativas e repetição segura

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.

## Próximos passos

- [Autenticar na API pública](/developers/authentication/)
- [Referência completa da API](/api/)