Endpoint
write:companies
Corpo da requisição
Exemplo de requisição
Encontrar antes de criar
Comexternal_id no corpo, a criação é idempotente. Antes de gravar, a API procura uma empresa da organização com as mesmas chaves, nesta ordem: external_id, CNPJ (document) e identidade comercial (nome, cidade e telefone — a mesma regra da importação; só vale para empresa sem CNPJ). Se encontrar, a resposta é HTTP 200 com o registro existente e meta.matched_by (external_id, document ou identity). A empresa existente não é alterada.
Sem external_id, o comportamento é o de sempre: cria, e CNPJ já cadastrado devolve HTTP 409 com existing_company no corpo.
Para procurar sem tentar criar, use GET /v1/companies?document=... ou ?external_id=... — veja Listar empresas.
Resposta
HTTP 201 com o objeto empresa criado e meta.created: true. HTTP 200, com o mesmo corpo e meta.created: false, quando já existia e o corpo trazia external_id. O objeto é o mesmo de Listar empresas, com document (CNPJ só dígitos) e external_id.
Erros
Criar, atualizar e excluir empresa disparam
company.created, company.updated e company.deleted. Quando a resposta é 200 (empresa já existia), nenhum evento é disparado.Não há endpoint de notas de empresa na v1 — só em contatos e negócios. O evento
company.note.added só dispara por ação no painel.