Negócios
contact_ids sempre vem em GET/api/deals/{id}. Na LISTAGEM (GET/api/deals) ele só aparece com ?include=contacts — buscar os contatos de cada negócio custa uma…
{
"id": "6d2c9f4e-1b7a-4e3d-8c5f-2a9b4d7e6f95",
"name": "Plano Pro — Acme LTDA",
"stage": "proposal_sent",
"value": 12000,
"company_id": "4e8b2f6d-7a1c-4d5e-9f4b-8a2c6e1d3b84",
"owner_id": "1b7c9d2e-5f3a-4e8b-9c1d-2a6f4b8e3d57",
"funnel_id": "c3d5e7f9-1a2b-4c6d-8e0f-3a5b7c9d1e2f",
"column_id": "e1f3a5b7-9c2d-4e6f-8a0b-1c3d5e7f9a2b",
"contact_ids": ["9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73"],
"source": "landing-page-plano-pro",
"tags": [],
"custom_fields": { "produto_de_interesse": "Plano PRO" },
"expected_close_date": "2026-08-15",
"actual_close_date": null,
"lost_reason": null,
"loss_reason_id": null,
"notes": null,
"external_id": null,
"created_at": "2026-05-02T12:00:00.000Z",
"updated_at": "2026-05-02T12:00:00.000Z"
}
contact_idssempre vem emGET/api/deals/{id}. Na LISTAGEM (GET/api/deals) ele só aparece com?include=contacts— buscar os contatos de cada negócio custa uma consulta extra (umJOINsó, nunca uma por linha), então sem o parâmetro o campo sai ausente, não[].custom_fieldsé diferente: vem sempre, no item e na lista, sem parâmetro nenhum.
| Campo | Tipo | Criar | Editar | Regras |
|---|---|---|---|---|
company_id |
uuid | obrigatório | — (imutável) | precisa existir na conta |
name |
texto | obrigatório | opcional | 1–200 |
stage |
enum | opcional (padrão new) |
opcional | new, qualified, proposal_sent, negotiation, won, lost |
value |
número | null | opcional | opcional | ≥ 0 |
source |
texto | null | opcional | opcional | até 120. Precisa casar (sem acento/caixa) com uma origem já cadastrada em Configurações → Negócios → Origens; se não casar, 400 — nunca grava texto livre |
expected_close_date |
texto | null | opcional | opcional | AAAA-MM-DD — a previsão |
actual_close_date |
texto | null | ⛔ só com import:write |
não aceito | AAAA-MM-DD — a data real de fechamento. Ver a armadilha logo abaixo |
lost_reason |
texto | null | opcional | opcional | até 1000. XOR com loss_reason_id — os dois no mesmo corpo é 400 |
loss_reason_id |
uuid | null | opcional | opcional | precisa existir no catálogo da conta (§9.3); escolher um zera lost_reason (e vice-versa) |
notes |
texto | null | — | opcional | até 5000. ⛔ Não é aceito na criação — no POST é 400 unknown_field. Pra registrar um texto junto do negócio novo, crie uma anotação (§9.1) |
owner_id |
uuid | null | opcional | opcional | precisa ser pessoa ativa da equipe. Omitido na criação, o negócio nasce sem responsável (uma automação da conta, como um rodízio de leads, pode atribuir depois). Quando o negócio ganha responsável, os contatos vinculados a ele que ainda não têm dono passam a ser dessa pessoa — contato que já tem dono nunca é trocado |
column_id |
uuid | — | opcional | a etapa real do funil (seção 12) |
funnel_id |
uuid | null | — | — | só leitura; acompanha a column_id |
contact_ids |
uuid[] | opcional | — (use §9.4) | ≤ 200; todos precisam existir na conta — um id de outra conta recusa a chamada INTEIRA (nada é gravado) |
tag_ids |
uuid[] | opcional | — (use §13) | ≤ 50; precisam existir na conta e se aplicar a negócio |
custom_fields |
objeto | opcional | opcional | {"<key ou uuid>": valor} — ver §28 |
external_id |
texto | null | opcional | opcional* | até 255 — ver §27 |
tags |
lista | — | — | só leitura, e só no GET |
⛔⛔ Importando histórico?
actual_close_dateé o campo que salva a data de fechamento. Negócio que já nascewonoulostganha a data automaticamente — e, sem este campo, a data carimbada é o dia da importação. ⛒ Numa migração isso apaga a data de fechamento da base inteira, com201em cada chamada e nada avisando.⛔ E não dá pra corrigir depois: o
PATCHnão aceita este campo. Ou vem na criação, ou a data original se perde. Ele exige o escopoimport:write(§24); sem ele, mandá-lo é400 forbidden_import_fieldnomeando o campo.
* só DEFINE quando o negócio ainda não tem external_id; trocar um já gravado é 409 — ver §27.
| Método | Escopo | Descrição |
|---|---|---|
GET/api/deals |
deals:read |
Lista. Filtros: ?stage=, ?company_id=, ?external_id=, ?created_after=, ?created_before=, ?updated_after=, ?updated_before=, ?include=contacts, ?format=csv |
GET/api/deals/{id} |
deals:read |
Um negócio |
POST/api/deals |
deals:write |
Cria (201) |
PATCH/api/deals/{id} |
deals:write |
Edição parcial, inclui mover de etapa. 409 se o negócio foi alterado por outra requisição no meio desta — releia e tente de novo |
DELETE/api/deals/{id} |
deals:write |
Exclui (204) |
9.4 Vincular contatos ao negócio
Além de contact_ids[] na criação (acima), dá pra vincular ou desvincular contato de um negócio
já existente, um de cada vez:
{ "contact_id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73" }| Método | Escopo | Descrição |
|---|---|---|
POST/api/deals/{id}/contacts |
deals:write |
Vincula (200). Repetir não duplica. ⛔ Teto de 200 contatos por negócio — o 201º devolve 400 |
DELETE/api/deals/{id}/contacts/{contactId} |
deals:write |
Desvincula (204). Contato que não existe nesta conta → 404 |
stage × column_id — leia antes de integrar
São duas coisas diferentes:
stagesão 6 situações fixas de fábrica, iguais em toda conta.column_idsão as etapas que o dono da conta configurou na tela ("Entrada", "Negociação", "Fechado Ganho"…).
Prefira column_id — é o funil de verdade. Mandando os dois no mesmo corpo, column_id
vence e o stage é recalculado a partir dela. Mover por coluna dispara deal.stage_changed
mesmo quando a situação não muda, igual a arrastar o card no quadro.
Importando histórico? POST/api/deals com stage: "won" (ou "lost", "negotiation")
coloca o negócio na coluna correspondente do funil padrão. Já qualified e proposal_sent não
têm coluna determinística — dependem de como cada conta nomeou as etapas abertas — e caem na
coluna de entrada; mande um PATCH com column_id depois se precisar de precisão.
9.1 Anotações do negócio
Mesmo formato e mesmas regras da seção 7.1.
{
"id": "…",
"title": "Proposta enviada",
"content": "Aguardando retorno.",
"author_name": null,
"attachments": [],
"created_at": "…",
"updated_at": "…"
}| Método | Escopo |
|---|---|
GET/api/deals/{id}/notes |
deals:read |
POST/api/deals/{id}/notes |
deals:write |
PATCH/api/deals/{id}/notes/{noteId} |
deals:write |
DELETE/api/deals/{id}/notes/{noteId} |
deals:write |
9.2 Catálogo de origens
O source de um negócio (seção 9) só aceita texto que já existe neste catálogo —
esta é a rota que cria e lista as opções, sem precisar abrir a tela.
{ "id": "…", "name": "Indicação", "system_key": null, "created_at": "…" }| Método | Escopo | Descrição |
|---|---|---|
GET/api/deal-sources |
deals:read |
Lista, com a mídia de sistema (Meta Ads, Google Ads…) primeiro, na mesma ordem da tela |
POST/api/deal-sources |
deals:write |
Cria uma origem do cliente (201). Corpo: { "name": "Indicação" } — 1–120 caracteres, nenhum outro campo |
system_key vem preenchido nas origens que o Salos já entrega prontas (meta_ads,
google_ads…) — essas são somente leitura: tentar recriar uma pelo nome devolve 409. Só
dono ou administrador da conta pode criar origem — a mesma regra de quem pode mexer nisso pela
tela. Chave cujo responsável é membro comum recebe 403 forbidden_module, mesmo com
deals:write.
Nome repetido não é erro silencioso. POST com um nome que já existe no catálogo (ignorando
acento e maiúscula/minúscula — "Indicação" e "INDICACAO" são o mesmo nome) devolve 409 com o
existing_id da origem que já existe, pra você reusar o id em vez de adivinhar:
{ "error": { "code": "conflict", "message": "Já existe uma origem com esse nome (\"Indicação\") nesta conta.", "existing_id": "9f1e4b7a-…" } }GET/api/deal-sources devolve tudo sem paginação (next_cursor: null) — não aceita
?limit=/?cursor= (a seção 6 descreve a paginação por cursor das listagens
principais; este catálogo não tem, e mandar ?limit= devolve 400 "parâmetro não reconhecido").
9.3 Catálogo de motivos de perda
O lost_reason de um negócio é texto livre; loss_reason_id (seção 9) é a versão
com FK pra este catálogo, pra padronizar sem obrigar — escolher um zera o outro. Mesmas regras de
escopo e papel da seção anterior.
{ "id": "…", "label": "Sem orçamento", "position": 3, "is_default": true }| Método | Escopo | Descrição |
|---|---|---|
GET/api/loss-reasons |
deals:read |
Lista, na ordem da tela |
POST/api/loss-reasons |
deals:write |
Cria um motivo (201). Corpo: { "label": "Sem orçamento" } — 1–120 caracteres, nenhum outro campo |
Mesmo casamento por acento/caixa do catálogo de origens: label repetido devolve 409 com
existing_id.
GET/api/loss-reasons devolve tudo sem paginação (next_cursor: null) — não aceita
?limit=/?cursor= (mesma ressalva do catálogo de origens, acima).