Empresas

GET   {BASE_URL}/api-v1-companies        # lista
GET   {BASE_URL}/api-v1-companies/:id     # detalhe
POST  {BASE_URL}/api-v1-companies        # cria
PATCH {BASE_URL}/api-v1-companies/:id     # atualiza

Escopos: companies:read para os GET; companies:write para POST e PATCH.

O recurso Empresa

Campo	Tipo
`id`	uuid
`workspace_id`	uuid
`name`	string
`trade_name`	string \| null
`cnpj`	string \| null
`email`	string \| null
`phone`	string \| null
`phone2`	string \| null
`whatsapp`	string \| null
`website`	string \| null
`segment`	string \| null
`tax_regime`	enum \| null
`instagram`	string \| null
`linkedin`	string \| null
`owner_id`	uuid
`address_street`	string \| null
`address_number`	string \| null
`address_complement`	string \| null
`address_neighborhood`	string \| null
`address_city`	string \| null
`address_state`	string \| null
`address_zip`	string \| null
`notes`	string \| null
`custom_fields`	object \| null
`created_at`	datetime
`updated_at`	datetime

O campo tax_regime (regime tributário), quando presente, é um destes valores: mei, simples, presumido, real, imune.

Listar empresas

GET {BASE_URL}/api-v1-companies

Filtro (query)	Tipo	Notas
`cnpj`	string	Igualdade exata.
`segment`	string	Igualdade exata.
`since`	ISO 8601	`created_at >= since`.
`limit`	int	Padrão 50, máx 200.
`cursor`	uuid	Próxima página.

curl "{BASE_URL}/api-v1-companies?segment=Tecnologia&limit=50" \
  -H "X-API-Key: vnd_sua_chave_aqui"

{
  "data": [ { "id": "9d8e...", "name": "Empresa Exemplo", "cnpj": "00.000.000/0001-00", "...": "..." } ],
  "meta": { "next_cursor": "9d8e...", "has_more": false }
}

Consultar uma empresa

GET {BASE_URL}/api-v1-companies/:id → o recurso Empresa, ou 404 not_found.

Criar uma empresa

POST {BASE_URL}/api-v1-companies — escopo companies:write.

Campo	Tipo	Obrigatório
`name`	string	Sim (1–255).
`owner_id`	uuid	Não (resolução automática quando ausente).
`trade_name`	string	Não
`cnpj`	string	Não (até 20; aceito mesmo sem formatação).
`email`	string	Não (e-mail válido).
`phone`	string	Não
`whatsapp`	string	Não
`website`	string	Não
`segment`	string	Não
`tax_regime`	enum	Não (`mei`, `simples`, `presumido`, `real`, `imune`).
`address_street`	string	Não
`address_number`	string	Não
`address_complement`	string	Não
`address_neighborhood`	string	Não
`address_city`	string	Não
`address_state`	string	Não
`address_zip`	string	Não
`custom_fields`	object	Não (≤ 50 chaves, ≤ 10 KB).

curl -X POST "{BASE_URL}/api-v1-companies" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Empresa Exemplo", "cnpj": "00000000000100", "segment": "Tecnologia", "tax_regime": "simples" }'

Resposta 201 Created:

{ "id": "9d8e..." }

Atualizar uma empresa

PATCH {BASE_URL}/api-v1-companies/:id — escopo companies:write. Mesmos campos do POST, todos opcionais. Retorna a empresa completa atualizada (200 OK).

curl -X PATCH "{BASE_URL}/api-v1-companies/9d8e..." \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "website": "https://empresaexemplo.com.br", "address_city": "São Paulo" }'

Erros possíveis

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	Falta `companies:read` ou `companies:write`.
`404`	`not_found`	Empresa não existe nesse workspace.
`400`	`bad_request`	Corpo ausente/JSON inválido.
`422`	`validation_error`	Campo inválido.
`422`	`invalid_reference`	`owner_id` fora do workspace.
`422`	`no_owner_available`	Sem responsável ativo possível.
`405`	`method_not_allowed`	Método não suportado.
`500`	`internal_error`	Falha interna.