Ensaio (dry_run)
Toda chamada de criação e a maior parte das de atualização aceitam ?dry_run=true: a chamada roda todas as validações que a gravação de verdade rodaria — form…
Toda chamada de criação e a maior parte das de atualização aceitam ?dry_run=true: a chamada
roda todas as validações que a gravação de verdade rodaria — formato do corpo, escopo,
existência e pertencimento de company_id/owner_id, unicidade — mas não grava nada.
- Na criação, a resposta é
200(nunca201) com o corpo que seria devolvido, sem o campoid(não existe registro, então não existe id). - Na exclusão, o ensaio devolve
200 { "ok": true }— a exclusão real responde204sem corpo, então não há "o corpo que seria devolvido" pra imitar. ⛒ Leia o200como "passou nas checagens", não como um espelho da resposta real. - O cabeçalho
x-salos-dry-run: truemarca a resposta como ensaio. - Só aceita
trueoufalse. Qualquer outro valor (1,sim, string vazia) é recusado com400— nunca tratado como "não étrue, então grava". Um ensaio que grava por acidente é o pior desfecho possível desta funcionalidade. - Não consome
Idempotency-Key. A sequência abaixo é segura — a chamada real GRAVA e não recebe de volta o ensaio:
# 1) ensaia — não grava nada
curl -X POST "https://app.salos.com.br/api/contacts?dry_run=true" \
-H "Authorization: Bearer $SALOS_API_KEY" \
-H "Idempotency-Key: import-contato-4821" \
-H "Content-Type: application/json" \
-d '{"name": "Maria Souza", "phone": "5511999998888"}'
# → 200, sem id, x-salos-dry-run: true
# 2) chamada real, MESMA Idempotency-Key — grava de verdade
curl -X POST https://app.salos.com.br/api/contacts \
-H "Authorization: Bearer $SALOS_API_KEY" \
-H "Idempotency-Key: import-contato-4821" \
-H "Content-Type: application/json" \
-d '{"name": "Maria Souza", "phone": "5511999998888"}'
# → 201, com id- Em lote, cada item devolve
ok/erroexatamente como a gravação devolveria — inclusive os erros que só o banco revela (origem inexistente,owner_idinativo,external_idduplicado) — e nenhuma linha é gravada.
⛔ Um punhado de rotas não aceita
dry_run— cada uma diz o porquê no comentário da própria rota:POST/api/commissions/calculatenão grava nada (é uma calculadora pura, não há o que ensaiar), ePOST/api/webhooks/{id}/testé o próprio botão "Testar" — disparar UMA entrega de teste É o produto, não um passo de importação em massa. Por isso ela recusa com400qualquer parâmetro na URL,dry_runincluso — nunca o ignora e dispara.
26.1 O que o ensaio NÃO confere, rota a rota
O ensaio roda o máximo de validação que dá pra rodar sem gravar — mas em algumas rotas isso
não é 100% do que a gravação real confere. Quem monta um pipeline de importação em cima de
dry_run=true não pode assumir que "ensaio verde" implica "gravação vai dar certo" nas rotas
abaixo — só que passou pelas checagens listadas.
| Rota | O que o ensaio confere | O que o ensaio NÃO confere |
|---|---|---|
POST/api/leads |
Forma do corpo, escopo de negócio (crm/create quando o corpo pede deal) |
Existência de owner_id/funnel_id/column_id, existência das tags, e a deduplicação por telefone/e-mail. O lead pode devolver ensaio "ok" e a chamada real reusar um contato existente em vez de criar um novo — o que é o comportamento correto; o ensaio só não antecipa qual dos dois vai acontecer |
POST/api/leads/batch |
O mesmo que POST/api/leads, item a item |
O mesmo que POST/api/leads, mais a deduplicação de external_ref repetido dentro do próprio lote |
POST/api/conversations/{id}/messages |
Forma do corpo e visibilidade da conversa (a chave enxerga essa conversa) | A janela de 24 h do WhatsApp e o estado do canal (conectado, token válido). Essas checagens moram dentro do próprio envio, e o ensaio não o chama — de propósito, pra nunca mandar mensagem de verdade num ensaio. Ensaio verde não garante que a mensagem real vai sair |
POST/api/conversations/{id}/agent |
Conversa existe e é visível pela chave, e há agente ativo com "Acionado por Requisição API" ligado (senão 409). A resposta do ensaio é { "data": { "conversation_id": "...", "agent_would_start": true } } |
Se a conversa já tem um agente atendendo, ou o agente está pausado nela — nesse caso a chamada real responde 200 com agent_started: false e um reason, sem mudar nada. Ensaio verde não garante que o agente vai assumir |
POST/api/contacts |
Formato, campo desconhecido, pertencimento de company_id, unicidade de telefone e de external_id, contra o banco |
Telefone gravado fora do padrão internacional (+55…). A comparação de duplicidade usa o texto da coluna como está, então um número gravado sem o +55 não é reconhecido como igual ao mesmo número normalizado. ⛔ Normalize o telefone antes de importar — vale pro ensaio e pra gravação real |
POST/api/contacts/batch |
O mesmo que POST/api/contacts, item a item — e external_id repetido dentro do próprio lote: o 1º item vence, os seguintes recusam, igual no ensaio e na gravação real |
Telefone repetido dentro do próprio lote — a checagem é só contra o banco. Dois itens do mesmo envio com o mesmo telefone podem aparecer os dois "ok" no ensaio, e um deles perder a corrida na gravação |
POST/api/companies |
Formato, campo desconhecido, unicidade de external_id, CNPJ e nome, contra registro já existente na conta |
— (cobre tudo que a gravação unitária confere) |
POST/api/companies/batch |
O mesmo que POST/api/companies, item a item, contra o banco, mais external_id repetido dentro do lote |
Nome ou CNPJ repetidos dentro do próprio lote, quando as duas linhas são novas. A gravação real ainda recusa a 2ª com 409 — é o índice único do banco que resolve; o ensaio é que não prevê |
POST/api/deals |
Forma do corpo, company_id/owner_id, source, contact_ids/tag_ids (todos precisam existir na conta), custom_fields (chave e tipo), loss_reason_id/lost_reason (XOR e existência) |
— (cobre tudo que a gravação confere) |
POST/api/tags |
Formato e unicidade do nome, com o mesmo desfecho da gravação real: reuso silencioso quando o escopo applies_to já cobre, ou 409 nomeando o que falta |
— (cobre tudo que a gravação confere) |
POST/api/funnels |
Forma do corpo e o teto de funis por conta | As 4 colunas universais que todo funil novo ganha — elas nascem dentro da própria escrita, e o corpo do ensaio não as lista |
POST/api/funnels/{id}/columns |
Forma do corpo e o teto de etapas por funil | — (cobre tudo que a gravação confere) |
POST/api/webhooks |
Forma do corpo, URL em https://, e o teto de webhooks por conta |
O secret — ele nasce (e aparece em texto puro uma única vez) só quando o webhook é criado de verdade. Um segredo de ensaio, que ninguém chegaria a usar, seria pior que nenhum |
PATCH/api/{contacts,companies,deals,tasks}/batch |
O mesmo que o PATCH unitário daquele recurso — o item chama o handler unitário de verdade, com ?dry_run=true |
O mesmo que o PATCH unitário não confere |
PATCH/DELETE/api/{contacts,companies,deals}/{id}/notes/{noteId} |
Existência da anotação e do registro-pai | — |
DELETE/api/{contacts,companies,deals,tasks}/{id} |
Existência do registro, isolamento por conta e — em empresa — qualquer negócio vinculado, aberto ou fechado (o mesmo 409 da gravação real) |
— |
POST/api/{contacts,companies,deals,tasks}/batch-delete |
Existência do registro, isolamento por conta, e — em empresa — qualquer negócio vinculado, aberto ou fechado | — (cobre tudo que a exclusão confere) |