Empresas

* só DEFINE quando o registro ainda não tem; trocar um já gravado é 409 — ver §27.

{
  "id": "4e8b2f6d-7a1c-4d5e-9f4b-8a2c6e1d3b84",
  "name": "Acme LTDA",
  "notes": "Cliente desde 2025.",
  "cnpj": null,
  "legal_name": null,
  "segment": null,
  "size": null,
  "phone": null,
  "email": null,
  "website": null,
  "zip_code": null,
  "street": null,
  "street_number": null,
  "complement": null,
  "neighborhood": null,
  "city": null,
  "state": null,
  "external_id": null,
  "custom_fields": {},
  "tags": [{ "id": "…", "name": "Lead quente", "color": "#EE710E" }],
  "created_at": "2026-05-02T12:00:00.000Z",
  "updated_at": "2026-05-02T12:00:00.000Z"
}
Campo Tipo Criar Editar Regras
name texto obrigatório opcional 1–200 caracteres
notes texto | null opcional opcional até 5000
cnpj texto | null opcional opcional validado por dígito verificador (aceita com ou sem máscara); 409 cnpj_conflict se já existir na conta
legal_name texto | null opcional opcional razão social, até 200
segment texto | null opcional opcional até 120
size enum | null opcional opcional ⛔ lista fixa, não configurável: MEI, Micro, Pequena, Média, Grande. Comparação exata, com acento e com a caixa exata — media e MEDIA são 400. Não há endpoint que liste esses valores; são estes
phone texto | null opcional opcional até 40
email texto | null opcional opcional até 200
website texto | null opcional opcional até 200
zip_code texto | null opcional opcional até 9
street texto | null opcional opcional até 200
street_number texto | null opcional opcional até 20
complement texto | null opcional opcional até 100
neighborhood texto | null opcional opcional até 120
city texto | null opcional opcional até 120
state texto | null opcional opcional UF, 2 letras
tag_ids uuid[] opcional — (use §13) ≤ 50; precisam existir na conta e se aplicar a empresa — um id inválido recusa a chamada INTEIRA (nada é gravado)
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

* só DEFINE quando o registro ainda não tem; trocar um já gravado é 409 — ver §27.

Os 14 campos cadastrais (cnpj até state) são os mesmos da tela "Dados da empresa" — a API só os expõe, não muda a regra de nenhum.

Método Escopo Descrição
GET/api/companies companies:read Lista. Filtros: ?search=, ?external_id=, ?created_after=, ?created_before=, ?updated_after=, ?updated_before=, ?format=csv
GET/api/companies/{id} companies:read Uma empresa
POST/api/companies companies:write Cria (201)
PATCH/api/companies/{id} companies:write Edição parcial
DELETE/api/companies/{id} companies:write Exclui (204). 409 se houver negócios vinculados — veja abaixo

409 de nome repetido. POST e PATCH de empresa devolvem 409 conflict "Já existe uma empresa com esse nome nesta organização." O nome é único por conta. No POST, o erro traz o existing_id da empresa que já tem esse nome.

O 409 do DELETE não é só de negócio ABERTO. Esta tabela dizia "409 se houver negócios abertos vinculados", e quem lesse concluiria que empresa cujos negócios já foram todos ganhos/perdidos pode ser excluída. Não pode: qualquer negócio vinculado, aberto ou fechado, barra a exclusão (a resposta muda de mensagem, mas continua 409). Mova ou exclua os negócios antes.

8.1 Anotações da empresa

Mesmo formato e mesmas regras da seção 7.1.

{ "id": "…", "title": "Renovação em outubro", "content": "Já sinalizou interesse.", "author_name": null, "attachments": [], "created_at": "…", "updated_at": "…" }
Método Escopo
GET/api/companies/{id}/notes companies:read
POST/api/companies/{id}/notes companies:write
PATCH/api/companies/{id}/notes/{noteId} companies:write
DELETE/api/companies/{id}/notes/{noteId} companies:write