Primeiros passos
Faça login, escolha o workspace e faça a primeira chamada à API.
Este guia leva você do login à primeira lista de leads, com exemplos em curl. Você precisa de um usuário com acesso a um workspace e da permissão de ler leads (leads:read) nesse workspace.
1. Faça login
Envie o e-mail e a senha do usuário para POST /auth/login:
curl -X POST "https://api.vozkoia.com/auth/login" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "SUA_SENHA"
}'A resposta traz o token de acesso e o token de renovação:
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "9f2c4e7a1b3d5f6e8a0c2b4d6f8e0a1c3b5d7f9e1a3c5b7d9f1e3a5c7b9d1f3e",
"tokenType": "Bearer",
"userId": "5b1f9c2e-3a4d-4e6f-8a7b-9c0d1e2f3a4b",
"email": "[email protected]",
"name": "Ana Souza",
"picture": "",
"role": "user",
"customerType": "company"
}Guarde os dois tokens. O accessToken vai em todas as chamadas e expira em pouco tempo (15 minutos, na configuração padrão); o refreshToken serve para obter um novo par sem pedir a senha de novo. Veja Autenticação.
2. Escolha o workspace
Liste os workspaces de que o usuário faz parte:
curl "https://api.vozkoia.com/workspaces" \
-H "Authorization: Bearer SEU_ACCESS_TOKEN"A resposta é uma lista de workspaces. Use o id do workspace desejado no cabeçalho X-Workspace-ID das próximas chamadas:
[
{
"id": "0e7d3c1a-9b2f-4c5d-8e6f-1a2b3c4d5e6f",
"name": "Clínica Sorriso"
}
]A lista real traz mais campos de cada workspace. Sem X-Workspace-ID, a API usa o workspace padrão do usuário. Veja Workspaces e departamentos.
3. Faça a primeira chamada
Liste os leads do workspace, 20 por página:
curl "https://api.vozkoia.com/leads?page=1&pageSize=20" \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "X-Workspace-ID: SEU_WORKSPACE_ID"4. Leia a resposta
{
"data": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"workspaceId": "0e7d3c1a-9b2f-4c5d-8e6f-1a2b3c4d5e6f",
"number": "5511987654321",
"name": "Maria",
"blocked": false
}
],
"meta": {
"page": 1,
"pageSize": 20,
"totalPages": 4,
"totalItems": 72
}
}datatraz os leads da página. Cada item tem mais campos do que o exemplo; a Referência da API mostra todos.metadiz em que página você está e quantas existem. Para a próxima, repita a chamada compage=2. Veja Paginação.
Se algo der errado, a resposta tem um status de erro e um corpo como este, de um usuário sem a permissão de ler leads:
{
"error": true,
"code": "read_permission_required",
"message": "Insufficient permissions: requires leads:read in this workspace",
"expected": {
"required_permission": "leads:read"
}
}Veja Erros para tratar cada caso.
5. Renove o token
Quando o accessToken expirar, as chamadas passam a responder 401. Troque o refreshToken por um novo par:
curl -X POST "https://api.vozkoia.com/auth/refresh" \
-H "Content-Type: application/json" \
-d '{"refreshToken": "SEU_REFRESH_TOKEN"}'A resposta tem o mesmo formato do login. Passe a usar os dois tokens novos: o refreshToken anterior deixa de valer.
Próximos passos
- Autenticação: sessões, logout e boas práticas.
- Erros: o formato das recusas e como tratar cada status.
- Referência da API: todas as rotas.
Updated 17 days ago