Autenticação
Chaves de API
Envie sua chave de API como token Bearer no cabeçalho Authorization de toda requisição:
curl https://energized-butterfly-12.convex.site/v1/jobs \
-H "Authorization: Bearer bsk_live_..."As chaves começam com bsk_live_. Uma chave ausente, inválida, revogada ou expirada retorna 401 INVALID_API_KEY.
O titular ou um administrador da conta gerencia as chaves na página de chaves de API. Lá você pode:
- Criar uma chave com nome, nível de acesso e validade (30, 90 ou 365 dias, ou sem validade). A chave aparece uma única vez.
- Revogar uma chave. As requisições com ela falham na hora.
Mantenha as chaves no seu servidor. Nunca as inclua em um navegador ou aplicativo móvel.
Permissões
Cada chave tem um nível de acesso a Jobs:
| Nível de acesso | Permissões | Permite |
|---|---|---|
| Somente leitura | jobs:read | Listar Jobs, obter Jobs e arquivos de extrato com resultados |
| Leitura e escrita | jobs:read, jobs:write | Tudo acima, mais enviar arquivos e excluir Jobs |
Cada endpoint exige uma permissão:
| Endpoint | Permissão |
|---|---|
POST /v1/jobs | jobs:write |
GET /v1/jobs | jobs:read |
GET /v1/jobs/{id} | jobs:read |
GET /v1/jobs/{id}/statement-files/{fileId} | jobs:read |
DELETE /v1/jobs/{id} | jobs:write |
Uma chave sem a permissão recebe 403 PERMISSION_DENIED.
Dê a cada integração o menor acesso de que ela precisa. Por exemplo, um painel que só mostra resultados precisa de uma chave somente leitura.
Planos e cotas
O plano do titular da conta decide o acesso à API. Os planos Starter e Professional incluem a API. Os demais planos recebem 402 PLAN_REQUIRED.
| Plano | Páginas por mês | Páginas por arquivo |
|---|---|---|
| Starter | 50 | 20 |
| Professional | 200 | 20 |
Os envios pela API e pelo aplicativo web dividem as mesmas páginas mensais. Um Job que não cabe nas páginas restantes retorna 402 QUOTA_EXCEEDED, e nenhuma página é gasta. A cota reinicia às 00:00 UTC do primeiro dia de cada mês.
Cada imagem conta como uma página.
Limites de requisições
Cada conta pode fazer 60 requisições por minuto, somando todas as suas chaves. Acima do limite, a API retorna 429 RATE_LIMITED com o cabeçalho Retry-After. O cabeçalho traz quantos segundos esperar antes de tentar de novo.