Criar negócio

Cria um negócio e devolve 201 com o registro criado.

POST https://app.salos.com.br/api/deals deals:write

Corpo de exemplo

{
  "company_id": "4e8b2f6d-7a1c-4d5e-9f4b-8a2c6e1d3b84",
  "name": "Reforma da fachada",
  "value": 18500.00,
  "stage": "negotiation",
  "source": "Indicação"
}

Campos

Campo Tipo Criar Regras
company_id uuid obrigatório no Salos, negócio sempre pertence a uma empresa
name texto obrigatório 1–200
value número | null opcional ≥ 0, no máximo 9.999.999.999,99, no máximo 2 casas decimais. Uma terceira casa é 400 — o banco a arredondaria em silêncio
stage enum opcional (padrão new) new, qualified, proposal_sent, negotiation, won, lost. O negócio entra no funil padrão, na etapa que corresponde ao estágio; qualified e proposal_sent caem na Entrada
owner_id uuid | null opcional responsável — pessoa ativa da equipe. Omitido, o negócio nasce sem responsável
source texto | null opcional até 120. Precisa casar (ignorando acento e caixa) com uma origem do catálogo da conta; a grafia canônica é gravada
expected_close_date AAAA-MM-DD | null opcional previsão de fechamento
actual_close_date AAAA-MM-DD | null ⛔ só com import:write data real de fechamento. Ver a armadilha abaixo
external_id texto | null opcional até 255 — o id no seu sistema. Já usado: 409 com o existing_id
contact_ids lista de uuid opcional vincula até 200 contatos já na criação. Um id de outra conta recusa a chamada inteira
tag_ids lista de uuid opcional até 50. Etiqueta de outra conta, ou que não se aplica a negócio, recusa a chamada inteira
custom_fields objeto opcional {"<key ou uuid>": valor}. Chave inexistente ou tipo errado é 400 nomeando a chave
lost_reason / loss_reason_id texto | uuid opcional motivo da perda: texto livre ou id do catálogo. ⛔ XOR — os dois juntos é 400

column_id, funnel_id e notes não entram na criação

Os três são 400 unknown_field no POST. Pra colocar o negócio numa etapa específica, crie e depois mande um PATCH com column_id. Pra deixar um texto junto do negócio novo, crie uma anotação em POST/api/deals/{id}/notes.

⛔ Importando histórico: actual_close_date

Negócio que já nasce won ou lost ganha automaticamente a data de fechamento — e, sem este campo, a data carimbada é o dia da importação. ⛒ Numa migração isso apaga a data de fechamento de toda a base, com 201 em cada chamada e nada na tela avisando.

⛔ E não dá pra corrigir depois: o PATCH não aceita actual_close_date. Ou vem na criação, ou a data original se perde.

O campo exige o escopo import:write na chave. Sem ele, mandá-lo devolve 400 forbidden_import_field nomeando o campo — nunca descarte silencioso.