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
  }
}
  • data traz os leads da página. Cada item tem mais campos do que o exemplo; a Referência da API mostra todos.
  • meta diz em que página você está e quantas existem. Para a próxima, repita a chamada com page=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


Did this page help you?