Introdução

Emita NFS-e de empresas MEI e do Simples Nacional por uma API REST ou por um agente de IA (MCP): cálculo de tributos, várias empresas e webhooks.

A API da Corvo permite cadastrar empresas (MEI, Simples Nacional e outros regimes), enviar certificados A1, calcular tributos antes de emitir, emitir notas fiscais de serviço (NFS-e) e acompanhar o ciclo de vida completo por webhooks. Agentes de IA como Claude Code, Cursor e Codex fazem o mesmo pelo servidor MCP (veja Agentes de IA).

Quickstart

bash

export BASE_URL='https://api.corvo.tech/v1'
export CORVO_API_KEY='corvo_test_sua_chave'

curl "$BASE_URL/companies" -H "X-API-Key: $CORVO_API_KEY"

Todos os caminhos desta documentação são relativos a BASE_URL (https://api.corvo.tech/v1).

Formatos de resposta

Sucessos REST usam { "data": ... } e listagens acrescentam pagination. Datas JSON são strings ISO 8601; campos opcionais podem estar ausentes e campos anuláveis podem ser null.

Operação	Formato JSON
Criar, consultar ou atualizar empresa	`{ "data": Company }`
Listar empresas	`{ "data": Company[], "pagination": {...} }`
Excluir empresa	`{ "data": null }`
Upload / listagem de certificados	`{ "data": Certificate } / listagem paginada`
Emitir / consultar nota	`{ "data": Invoice }`
Listar notas e eventos	`{ "data": [ ... ], "pagination": {...} }`
URL de download / email	`{ "data": ... }`
Webhooks e entregas	`{ "data": ... } ou listagem paginada`
Plano e cotas	`{ "data": ... }`

Os recursos vêm direto em data: uma nota é data, uma lista é data[]. Leia data uma única vez. PDF/XML, redirects, OAuth, MCP/JSON-RPC, health checks e respostas 204 mantêm seus formatos próprios.

Todas as operações

Todos os caminhos abaixo incluem o prefixo padrão. Os status representam o sucesso conforme a matriz de contratos HTTP; erros seguem o formato ERROR_* descrito em Erros.

Método	Caminho	Função	Sucesso
POST	`/v1/companies`	Cadastrar empresa	201
GET	`/v1/companies`	Listar empresas	200
GET	`/v1/companies/:id`	Consultar empresa	200
PATCH	`/v1/companies/:id`	Atualizar empresa	200
DELETE	`/v1/companies/:id`	Excluir empresa	200
POST	`/v1/companies/:companyId/certificates`	Enviar certificado	201
GET	`/v1/companies/:companyId/certificates`	Listar certificados	200
DELETE	`/v1/companies/:companyId/certificates/:certId`	Revogar certificado	204
POST	`/v1/invoices`	Solicitar emissão	202
POST	`/v1/invoices/batches`	Solicitar a emissão de até 50 notas	202
POST	`/v1/invoices/calculate`	Calcular tributos sem emitir	200
GET	`/v1/invoices`	Listar notas	200
GET	`/v1/invoices/:id`	Consultar nota	200
GET	`/v1/invoices/:id/xml`	Baixar XML	200
GET	`/v1/invoices/:id/pdf`	Baixar PDF	200
GET	`/v1/invoices/:id/events`	Consultar histórico	200
POST	`/v1/invoices/:id/download-url`	Gerar URL assinada	200
POST	`/v1/invoices/:id/email`	Solicitar envio de email	202
POST	`/v1/invoices/:id/cancel`	Cancelar nota	200/202
GET	`/v1/webhooks`	Listar configurações	200
POST	`/v1/webhooks`	Cadastrar webhook	201
DELETE	`/v1/webhooks/:id`	Excluir webhook	200
POST	`/v1/webhooks/:id/test`	Enviar evento de teste	200
GET	`/v1/webhooks/deliveries`	Listar entregas	200
GET	`/v1/webhooks/deliveries/stats`	Consultar estatísticas	200
POST	`/v1/webhooks/deliveries/:id/retry`	Agendar nova tentativa	200
GET	`/v1/billing/plan`	Consultar plano e consumo	200
GET	`/v1/billing/usage`	Consultar disponibilidade e cotas	200
POST	`/v1/billing/upgrade`	Agendar troca de plano	200
POST	`/v1/billing/downgrade`	Agendar mudança de plano	200
GET	`/v1/plans`	Listar preços dos planos (público)	200
GET	`/v1/plans/:slug`	Consultar o preço de um plano (público)	200
GET	`/v1/plans/quote`	Recomendar um plano para um volume (público)	200

IDs nos caminhos representam identificadores dos recursos retornados pela API. Guarde-os como strings; não use CNPJ no lugar de um :id.

Sequência de integração

Obtenha uma chave test com escopo adequado — cadastro de empresa/certificado exige full_access; uma chave invoices_read_write pode emitir com cadastro prévio.
POST /v1/companies — cadastre a empresa com CNPJ, regime e município fiscal (municipalityCode); configure defaultServiceCode para simplificar as notas.
Em live, envie o certificado válido correspondente ao CNPJ (POST /v1/companies/:companyId/certificates). A inscrição municipal é opcional: informe só se o município a registrou no cadastro nacional.
POST /v1/invoices — use companyTaxId (CNPJ da empresa) e solicite a emissão com Idempotency-Key estável por operação de negócio e guarde data.id (ambiente live exige prontidão da empresa).
Acompanhe o ciclo por GET /v1/invoices/:id e webhooks assinados — a emissão é assíncrona.
Aguarde os documentos ficarem prontos para gerar a URL e solicitar o email; confira o estado do email separadamente.