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_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 consulta extra (um JOIN só, 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á nasce won ou lost ganha 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, com 201 em cada chamada e nada avisando.

⛔ E não dá pra corrigir depois: o PATCH não aceita este campo. Ou vem na criação, ou a data original se perde. Ele exige o escopo import:write (§24); sem ele, mandá-lo é 400 forbidden_import_field nomeando 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:

  • stage são 6 situações fixas de fábrica, iguais em toda conta.
  • column_id sã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).