Saltar para o conteúdo principal
Antes de fazer sua primeira chamada à API, dedique alguns minutos para entender estes conceitos. Eles vão economizar tempo durante o desenvolvimento e ajudar a projetar uma integração mais sólida.

​
Workspaces

O Vendaze é uma plataforma multi-workspace. Uma única conta pode pertencer a vários workspaces, como um consultor que atende vários clientes ou uma empresa com múltiplas unidades de negócio. Quando um usuário autoriza seu aplicativo via OAuth, ele escolhe um workspace específico para conectar. Todas as operações feitas com aquele token pertencem exclusivamente a esse workspace.
Você nunca envia nenhum identificador de workspace nas requisições. O contexto do workspace é embutido no access_token no momento da autorização e resolvido automaticamente pela API em cada chamada.
Para acessar um workspace diferente, o usuário precisa passar pelo fluxo OAuth novamente.

​
Modelo de autenticação

A Vendaze API usa OAuth 2.1 Authorization Code flow com client_secret. Seu aplicativo:
  1. Registra-se na Vendaze para receber client_id e client_secret
  2. Redireciona usuários para autorizar acesso ao workspace deles
  3. Recebe um access_token (válido por 1 hora) e um refresh_token (válido por 60 dias)
  4. Inclui o access_token como Bearer token em toda requisição
O token é workspace-scoped. Um token emitido para o Workspace A não consegue ler dados do Workspace B.

​
Escopos

Escopos definem o que seu aplicativo pode fazer. Você declara os escopos necessários ao registrar o aplicativo. Na tela de consentimento, o usuário vê a lista completa de escopos solicitados e pode apenas aprovar ou negar o acesso. Não é possível selecionar escopos individualmente.
EscopoAcesso
people:readLer contatos (pessoas)
people:writeCriar, atualizar, deletar pessoas
companies:readLer empresas
companies:writeCriar, atualizar, deletar empresas
deals:readLer negócios
deals:writeCriar, atualizar, deletar negócios
tasks:readLer tarefas
tasks:writeCriar, atualizar, deletar tarefas
activities:readLer atividades
activities:writeCriar, deletar atividades
products:readLer produtos
products:writeCriar, atualizar, deletar produtos
tags:readLer tags
tags:writeCriar, atualizar, deletar tags
lists:readLer listas
lists:writeCriar, atualizar, deletar listas
custom_fields:readLer definições de campos adicionais
custom_fields:writeCriar, atualizar, deletar campos adicionais
webhooks:manageCriar, ler, atualizar e deletar webhooks
Solicite apenas os escopos que seu aplicativo genuinamente precisa. Usuários tendem a desconfiar de apps que pedem permissões amplas sem justificativa.

​
IDs de recursos

Todos os IDs na Vendaze API são UUIDs em formato string: 
"id": "550e8400-e29b-41d4-a716-446655440000"
Nunca use IDs numéricos sequenciais para referenciar recursos.

​
Datas e horários

Todos os timestamps são strings ISO 8601 UTC: 
"created_at": "2026-05-26T14:00:00Z"
Ao enviar datas em filtros ou bodies de requisição, sempre use ISO 8601 UTC. Outros formatos são rejeitados com erro 422.

​
Valores monetários

Campos de preço como price_cts são inteiros representando o valor em centavos: 
"price_cts": 19900
O valor 19900 representa R$ 199,00. Seu aplicativo é responsável pela conversão e formatação para exibição. Essa abordagem evita problemas de arredondamento de ponto flutuante e é consistente entre todas as moedas.

​
Soft delete

Recursos como pessoas, empresas e negócios suportam soft delete. Ao deletar via API, o registro é marcado internamente como deletado, mas não é removido permanentemente do banco. Da perspectiva da sua integração, o comportamento é transparente:
  • DELETE /v1/people/:id retorna 204 e o registro deixa de ser acessível
  • GET /v1/people/:id para um registro deletado retorna 404

​
Envelope de resposta

Toda resposta da Vendaze API segue o mesmo formato: 
// Objeto único
{ "data": { ... } }

// Erro
{
  "error": {
    "code": "not_found",
    "message": "Person not found.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
Uma resposta com status 2xx nunca contém error. Uma resposta com status não-2xx sempre contém error. Nunca verifique erros dentro de uma resposta bem-sucedida.

​
Nomes de campos

Todos os campos usam snake_case: 
{
  "full_name": "Ana Costa",
  "owner_user_id": "b3a8c1d2-f3e4-4a5b-9c6d-7e8f9a0b1c2d",
  "created_at": "2026-05-26T14:00:00Z"
}