Criar negócio
Cria um negócio e devolve 201 com o registro criado.
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.