Autenticação
Todas as rotas desta API exigem uma chave de API no header `X-API-Key`.
Formato das chaves: corvo_test_ ou corvo_live_ seguido de 40 caracteres hexadecimais minúsculos.
Headers
| Header | Uso |
|---|---|
X-API-Key | Obrigatório para autenticação por chave. |
Content-Type: application/json | Corpos JSON. |
Idempotency-Key | Opcional na emissão e na solicitação de email; recomendado para repetição segura dessas operações. |
Upload de certificado usa multipart/form-data. Com curl -F, deixe o curl gerar o Content-Type com boundary. Downloads retornam PDF ou XML, sem envelope JSON.
Ambientes
- Empresas, certificados e notas são acessados no ambiente persistido da chave:
testoulive. - Em
live, a emissão verifica a empresa, bloqueio e certificado ativo; também se aplicam créditos e limites de emissão. - Em
test, a emissão exige empresa existente, mas dispensa as verificações de prontidão e certificado do fluxolive. - Entregas de webhook usam o filtro explícito
?environment=test|live; sem ele, podem retornar ambos os ambientes da conta, independentemente do ambiente da chave.
Escopos
| Código | Escopo | O que permite |
|---|---|---|
| F | full_access | Todas as operações listadas nesta documentação. |
| I | invoices_issue | Emitir notas e solicitar email. |
| V | invoices_view | Consultar notas, documentos, eventos e URL de download. |
| RW | invoices_read_write | Emissão e consulta de notas, consulta de empresas, listagem de certificados e consulta de webhooks/entregas/estatísticas. |
invoices_read_write não permite alterar empresas, certificados, webhooks, créditos ou planos. Mesmo full_access só acessa rotas habilitadas para API key; permissões do escopo não abrem outras rotas.
Exemplo
bash
export BASE_URL='https://api.corvo.tech/v1'
export CORVO_API_KEY='SUA_CHAVE'
curl "$BASE_URL/companies" -H "X-API-Key: $CORVO_API_KEY"