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 |
409de nome repetido.POSTePATCHde empresa devolvem409 conflict"Já existe uma empresa com esse nome nesta organização." O nome é único por conta. NoPOST, o erro traz oexisting_idda empresa que já tem esse nome.O
409doDELETEnão é só de negócio ABERTO. Esta tabela dizia "409se 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 continua409). 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 |