A Core API do WACRM para desenvolvedores e agentes

Autenticação, escopos e idempotência

Toda rota v1 confere os escopos da credencial antes de qualquer outra coisa: uma chave criada sem contacts:write, por exemplo, recebe 403 insufficient_scope em POST /v1/contacts não importa o plano do projeto. A maioria dos escopos é opcional na criação — só alguns padrões (como templates:read para uma chave de loja) são concedidos automaticamente, então uma chave só tem o acesso que de fato recebeu.

Uma escrita que nunca deveria rodar duas vezes — enviar uma mensagem, propor uma ação de agente, criar uma tarefa a partir de uma conversa — exige um cabeçalho Idempotency-Key fornecido por quem chama. Repetir a mesma requisição com a mesma chave reproduz a primeira resposta ao pé da letra, em vez de enviar ou criar algo uma segunda vez, o que é o que permite repetir com segurança depois de uma falha de rede. Para POST /v1/messages essa janela de repetição é de 24 horas; para propor uma ação de agente ou criar uma tarefa, a chave é única por projeto e não expira.

Referência de endpoints

Gerada a cada build a partir do mesmo arquivo openapi-v1.yaml contra o qual a própria Core API é testada por contrato — cada caminho, método e escopo exigido abaixo vem direto desse arquivo, agrupado pela sua tag do OpenAPI.

Formato de erro

Toda resposta que não é 2xx é um objeto JSON com o mesmo formato:

{ "error": { "code": "insufficient_scope", "message": "motivo legível" } }