Referência
Comece por aqui
Crie uma integração só de leitura para explorar a API, envie a chave e teste as rotas /v1 no navegador.
Esta referência lista todas as rotas da API da Vozkoia, agrupadas por recurso, com os parâmetros, os corpos, as respostas e os códigos de erro de cada uma. Para entender os conceitos antes, leia os guias.
O jeito mais seguro de explorar é com uma integração só de leitura: uma conta de sistema que só consegue ler, criada por você para testar as rotas /v1 sem risco de mudar nada.
URL base
https://api.vozkoia.comTodas as rotas desta referência partem desse endereço, com HTTPS. As conexões WebSocket usam wss://api.vozkoia.com. Não há ambiente de testes; veja URL base e ambientes.
1. Escolha um workspace de testes
As chamadas agem sobre dados reais, como qualquer outra: não existe uma cópia de testes da API. Se puder, crie um workspace só para explorar, com alguns leads e conversas de exemplo, e faça os passos abaixo nele.
2. Crie uma integração só de leitura
Uma integração é uma conta de sistema do workspace. Ela não faz login, não aparece entre os membros e age só com as permissões e os departamentos que você escolher. Quem cria precisa poder gerenciar as chaves de API do workspace.
- No aplicativo, abra Menu lateral › Integrações e clique em Nova integração.
- Dê um nome que diga o propósito, por exemplo
Exploração da API. - Em Permissões, marque só ações de leitura (
read) dos recursos que quer explorar, comoleads:read,conversations:readeopportunities:read. Não marque nenhuma ação de criar, editar, enviar ou apagar. - Em Departamentos da integração, escolha os departamentos cujos dados ela pode ver.
- Crie a integração.
Membros, cargos, chaves de API, planos e recursos pessoais nunca são dados a uma integração, então nem aparecem na lista.
3. Crie uma chave
Na integração, clique em Chaves, depois em Nova chave. Escolha uma validade curta, como 30 dias, e copie a chave: ela começa com wsk_ e aparece uma única vez. Guarde-a como uma senha.
4. Envie a chave
Envie a chave no cabeçalho Authorization, com o esquema Bearer e um espaço:
Authorization: Bearer wsk_SUA_CHAVEA chave já traz o workspace, então X-Workspace-ID não é preciso; um workspace diferente do da chave responde 403 com o código workspace_mismatch. Para restringir a um dos departamentos da integração, envie X-Department-ID.
curl "https://api.vozkoia.com/v1/leads?page=1&pageSize=20" \
-H "Authorization: Bearer wsk_SUA_CHAVE"5. Teste no navegador
Cada rota /v1 desta referência tem um painel para enviar a chamada de verdade:
- Abra a rota que quer testar.
- No campo de autenticação
WorkspaceKey, preencha a palavraBearer, um espaço e a chave:Bearer wsk_.... - Preencha os parâmetros da rota e envie.
Com uma integração só de leitura, uma rota que cria, edita, envia ou apaga responde 403 com um código como create_permission_required. Essa é a resposta esperada: ela mostra a permissão que faltaria, sem mudar nada no workspace.
O que a chave não abre
- Rotas fora de
/v1: respondem401com o códigoapi_key_not_accepted. Elas servem o painel e mudam sem aviso. As únicas exceções são as três rotas antigas da API de e-mail transacional. - Gestão de integrações e chaves (
/v1/integrationse as chaves de cada integração): declaram sóBearerAuthe aceitam apenas o token de login de uma pessoa, obtido comPOST /auth/login. Veja Autenticação.
Especificação e SDKs
A especificação OpenAPI das rotas /v1, a mesma que gera os SDKs, sai em GET /v1/openapi.json, com a mesma chave. Use-a para gerar um cliente na sua linguagem ou importar a API numa ferramenta de testes.
Quando terminar
Revogue a chave em Integrações › Chaves, ou desative a integração, que revoga todas as chaves dela na hora. Para integrar um sistema de verdade, crie outra integração só com as permissões de que ele precisa e uma chave por sistema.