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 (nunca 201) com o corpo que seria devolvido, sem o campo id (não existe registro, então não existe id).
  • Na exclusão, o ensaio devolve 200 { "ok": true } — a exclusão real responde 204 sem corpo, então não há "o corpo que seria devolvido" pra imitar. ⛒ Leia o 200 como "passou nas checagens", não como um espelho da resposta real.
  • O cabeçalho x-salos-dry-run: true marca a resposta como ensaio.
  • Só aceita true ou false. Qualquer outro valor (1, sim, string vazia) é recusado com 400 — 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/erro exatamente como a gravação devolveria — inclusive os erros que só o banco revela (origem inexistente, owner_id inativo, external_id duplicado) — 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/calculate não grava nada (é uma calculadora pura, não há o que ensaiar), e POST/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 com 400 qualquer parâmetro na URL, dry_run incluso — 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)