VendeeDocs
Referência

Empresas

Contabilidades e empresas atendidas.

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

Use os endereços acima — são os que respondem hoje. A API está migrando para um endereço único ({BASE_URL}/api-v1/companies), que ainda não foi publicado: enquanto isso, qualquer chamada para ele devolve 404 not_found. Quando entrar no ar, esta página muda junto, e os endereços acima continuam valendo.

Escopos: companies:read para os GET; companies:write para a escrita.

Campos

CampoTipoEscritaNotas
iduuidsomente leitura
workspace_iduuidsomente leituraSempre o workspace da chave de API usada na chamada.
namestringcriar: obrigatório, editar: simDe 1 a 255 caracteres.
trade_namestringcriar: opcional, editar: simMáximo 255 caracteres.
cnpjstringcriar: opcional, editar: simAceito como veio, sem validar dígito — não bloquear inbound. máximo 20 caracteres.
emailstringcriar: opcional, editar: simFormato email; máximo 255 caracteres; normalizado para minúsculas.
phonestringcriar: opcional, editar: simMáximo 40 caracteres.
phone2stringcriar: opcional, editar: simMáximo 40 caracteres.
whatsappstringcriar: opcional, editar: simMáximo 40 caracteres.
websitestringcriar: opcional, editar: simMáximo 255 caracteres.
segmentstringcriar: opcional, editar: simMáximo 255 caracteres.
tax_regimestringcriar: opcional, editar: simValores: mei, simples, presumido, real, imune.
instagramstringcriar: opcional, editar: simMáximo 255 caracteres.
linkedinstringcriar: opcional, editar: simMáximo 255 caracteres.
owner_iduuidcriar: opcional, editar: simFormato uuid; deve existir na ficha owners.
address_streetstringcriar: opcional, editar: simMáximo 255 caracteres.
address_numberstringcriar: opcional, editar: simMáximo 40 caracteres.
address_complementstringcriar: opcional, editar: simMáximo 255 caracteres.
address_neighborhoodstringcriar: opcional, editar: simMáximo 255 caracteres.
address_citystringcriar: opcional, editar: simMáximo 255 caracteres.
address_statestringcriar: opcional, editar: simMáximo 120 caracteres.
address_zipstringcriar: opcional, editar: simMáximo 20 caracteres.
notesstringcriar: opcional, editar: simMáximo 10000 caracteres.
custom_fieldsobjetocriar: opcional, editar: simObjeto chave→valor. As chaves são as definidas na ficha custom-fields. até 50 chaves; até 10 KB; omitido → {}.
created_atdatetimesomente leitura
updated_atdatetimesomente leitura

Listar empresas

GET {BASE_URL}/api-v1-companies

Parâmetro (query)TipoNotas
cnpjstring
segmentstring
sincedatetimeSó registros criados a partir desta data (ISO 8601). Compara: maior ou igual a.
limitnumberTamanho da página. Padrão 50, máximo 200.
cursoruuidPróxima página — use o meta.next_cursor da resposta anterior.

Ordenação: id crescente. Paginação por cursor.

curl "{BASE_URL}/api-v1-companies?cnpj=..." \
  -H "X-API-Key: vnd_sua_chave_aqui"
{
  "data": [ /* registros */ ],
  "meta": { "next_cursor": "8f3c...", "has_more": true }
}

Consultar um registro

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

curl "{BASE_URL}/api-v1-companies/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui"

Criar

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

CampoTipoObrigatórioNotas
namestringSimDe 1 a 255 caracteres.
trade_namestringNãoMáximo 255 caracteres.
cnpjstringNãoAceito como veio, sem validar dígito — não bloquear inbound. máximo 20 caracteres.
emailstringNãoFormato email; máximo 255 caracteres; normalizado para minúsculas.
phonestringNãoMáximo 40 caracteres.
phone2stringNãoMáximo 40 caracteres.
whatsappstringNãoMáximo 40 caracteres.
websitestringNãoMáximo 255 caracteres.
segmentstringNãoMáximo 255 caracteres.
tax_regimestringNãoValores: mei, simples, presumido, real, imune.
instagramstringNãoMáximo 255 caracteres.
linkedinstringNãoMáximo 255 caracteres.
owner_iduuidNãoFormato uuid; deve existir na ficha owners.
address_streetstringNãoMáximo 255 caracteres.
address_numberstringNãoMáximo 40 caracteres.
address_complementstringNãoMáximo 255 caracteres.
address_neighborhoodstringNãoMáximo 255 caracteres.
address_citystringNãoMáximo 255 caracteres.
address_statestringNãoMáximo 120 caracteres.
address_zipstringNãoMáximo 20 caracteres.
notesstringNãoMáximo 10000 caracteres.
custom_fieldsobjetoNãoObjeto chave→valor. As chaves são as definidas na ficha custom-fields. até 50 chaves; até 10 KB; omitido → {}.
curl -X POST "{BASE_URL}/api-v1-companies" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "..." }'

Atualizar

PATCH {BASE_URL}/api-v1-companies/:id — escopo companies:write. Todos os campos são opcionais; só o que vier no corpo muda.

CampoTipoObrigatórioNotas
namestringNãoDe 1 a 255 caracteres.
trade_namestringNãoMáximo 255 caracteres.
cnpjstringNãoAceito como veio, sem validar dígito — não bloquear inbound. máximo 20 caracteres.
emailstringNãoFormato email; máximo 255 caracteres; normalizado para minúsculas.
phonestringNãoMáximo 40 caracteres.
phone2stringNãoMáximo 40 caracteres.
whatsappstringNãoMáximo 40 caracteres.
websitestringNãoMáximo 255 caracteres.
segmentstringNãoMáximo 255 caracteres.
tax_regimestringNãoValores: mei, simples, presumido, real, imune.
instagramstringNãoMáximo 255 caracteres.
linkedinstringNãoMáximo 255 caracteres.
owner_iduuidNãoFormato uuid; deve existir na ficha owners.
address_streetstringNãoMáximo 255 caracteres.
address_numberstringNãoMáximo 40 caracteres.
address_complementstringNãoMáximo 255 caracteres.
address_neighborhoodstringNãoMáximo 255 caracteres.
address_citystringNãoMáximo 255 caracteres.
address_statestringNãoMáximo 120 caracteres.
address_zipstringNãoMáximo 20 caracteres.
notesstringNãoMáximo 10000 caracteres.
custom_fieldsobjetoNãoObjeto chave→valor. As chaves são as definidas na ficha custom-fields. até 50 chaves; até 10 KB; omitido → {}.
curl -X PATCH "{BASE_URL}/api-v1-companies/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "trade_name": "...", "cnpj": "..." }'

Erros

HTTPcodeQuando
401missing_api_key / invalid_api_key / revoked_api_keyAutenticação.
403insufficient_scopeA chave não tem companies:read / companies:write.
404not_foundO registro não existe neste cliente.
422validation_errorCampo fora das regras da tabela acima.
422invalid_referenceowner_id aponta para fora deste cliente.
422invalid_cursorO cursor enviado não é válido.
405method_not_allowedMétodo não suportado neste endereço.
500internal_errorFalha interna.

Catálogo completo em Erros.

Idempotência

Envie um header Idempotency-Key (1–255 caracteres, qualquer string única sua) para tornar o POST acima seguro de reenviar em caso de timeout de rede ou retry automático:

curl -X POST "{BASE_URL}/api-v1-companies" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-9f21" \
  -d '{ "name": "Empresa Exemplo", "cnpj": "00000000000100" }'
  • Mesma chave, mesmo corpo: a segunda chamada não cria outra empresa — responde 200 OK com o corpo da resposta original (não 201).
  • Mesma chave, corpo diferente (ou reusada em outro recurso): 422 idempotency_conflict.
  • Mesma chave, requisição original ainda processando: 409 idempotency_in_progress — duas chamadas concorrentes com a mesma chave; espere e tente de novo.
  • Janela: a chave fica registrada por 24 horas; depois disso pode ser reusada como se fosse nova.
  • Sem o header: comportamento idêntico ao de hoje — cada POST cria uma empresa nova.

Erros específicos desta ficha

HTTPcodeQuando
400bad_requestCorpo ausente/JSON inválido.
422no_owner_availableSem responsável ativo possível.
400invalid_idempotency_keyIdempotency-Key fora de 1–255 caracteres.
422idempotency_conflictMesma Idempotency-Key com corpo ou recurso diferente.
409idempotency_in_progressMesma Idempotency-Key já em processamento (corrida).

Contatos

Pessoas com quem o time de vendas fala.

Atividades

Tarefas, ligações e reuniões da agenda comercial.

Nesta página

CamposListar empresasConsultar um registroCriarAtualizarErrosIdempotênciaErros específicos desta ficha