We use cookies to improve your experience and analyze site traffic. By clicking “Accept”, you agree to our use of cookies.

Learn more about our privacy practices
Corvo
Português

Introduction

Issue Brazilian NFS-e for MEI and Simples Nacional companies with a REST API or an AI agent (MCP): tax calculation, multiple companies and webhooks.

The Corvo API lets you register companies (MEI, Simples Nacional and other regimes), upload A1 certificates, calculate taxes before issuing, issue service invoices (NFS-e) and track their full lifecycle via webhooks. AI agents such as Claude Code, Cursor and Codex can do the same through the MCP server (see AI agents).

Quickstart

bash

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

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

All paths in this documentation are relative to BASE_URL (https://api.corvo.tech/v1).

Response formats

REST successes use { "data": ... } and listings add pagination. JSON dates are ISO 8601 strings; optional fields may be absent and nullable fields may be null.

OperationJSON format
Create, fetch or update a company{ "data": Company }
List companies{ "data": Company[], "pagination": {...} }
Delete a company{ "data": null }
Certificate upload / listing{ "data": Certificate } / paginated listing
Issue / fetch an invoice{ "data": Invoice }
List invoices and events{ "data": [ ... ], "pagination": {...} }
Download URL / email{ "data": ... }
Webhooks and deliveries{ "data": ... } or paginated listing
Plan & quotas{ "data": ... }

Resources come directly inside data: an invoice is data, a list is data[]. Read data exactly once. PDF/XML, redirects, OAuth, MCP/JSON-RPC, health checks and 204 responses keep their own formats.

All operations

All paths below include the default prefix. Status codes represent success according to the HTTP contract matrix; errors follow the ERROR_* format described under Errors.

MethodPathFunctionSuccess
POST/v1/companiesRegister a company201
GET/v1/companiesList companies200
GET/v1/companies/:idFetch a company200
PATCH/v1/companies/:idUpdate a company200
DELETE/v1/companies/:idDelete a company200
POST/v1/companies/:companyId/certificatesUpload a certificate201
GET/v1/companies/:companyId/certificatesList certificates200
DELETE/v1/companies/:companyId/certificates/:certIdRevoke a certificate204
POST/v1/invoicesRequest issuance202
POST/v1/invoices/batchesRequest issuance of up to 50 invoices202
POST/v1/invoices/calculateCalculate taxes without issuing200
GET/v1/invoicesList invoices200
GET/v1/invoices/:idFetch an invoice200
GET/v1/invoices/:id/xmlDownload XML200
GET/v1/invoices/:id/pdfDownload PDF200
GET/v1/invoices/:id/eventsFetch event history200
POST/v1/invoices/:id/download-urlGenerate a signed URL200
POST/v1/invoices/:id/emailRequest email delivery202
POST/v1/invoices/:id/cancelCancel an invoice200/202
GET/v1/webhooksList webhook configurations200
POST/v1/webhooksRegister a webhook201
DELETE/v1/webhooks/:idDelete a webhook200
POST/v1/webhooks/:id/testSend a test event200
GET/v1/webhooks/deliveriesList deliveries200
GET/v1/webhooks/deliveries/statsFetch delivery statistics200
POST/v1/webhooks/deliveries/:id/retrySchedule a retry200
GET/v1/billing/planFetch plan and consumption200
GET/v1/billing/usageFetch availability and quotas200
POST/v1/billing/upgradeSchedule a plan change200
POST/v1/billing/downgradeSchedule a plan change200
GET/v1/plansList plan prices (public)200
GET/v1/plans/:slugFetch one plan price (public)200
GET/v1/plans/quoteRecommend a plan for a volume (public)200

IDs in paths represent identifiers of resources returned by the API. Store them as strings; do not use a CNPJ in place of a :id.

Integration sequence

  • POST /v1/companies — register the company with its CNPJ, tax regime and fiscal municipality (municipalityCode); set defaultServiceCode to simplify invoices.
  • In live, upload a valid A1 certificate (.p12) matching the CNPJ, with its password (POST /v1/companies/:companyId/certificates). The municipal registration is optional: provide it only if the city registered the company in the national registry.
  • POST /v1/invoices — use companyTaxId (company CNPJ) to request issuance (the live environment requires the company to be ready).
  • Track the lifecycle with GET /v1/invoices/:id and webhooks — issuance is asynchronous.