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

NFS-e API reference

Base URL: https://api.corvo.tech/v1. Authenticate with the X-API-Key header. Each section links to the docs page with parameters and examples.

Companies

Details and examples

Method	Endpoint	Success	Description
POST	/v1/companies	201 Created	Registers a company.
GET	/v1/companies	200 OK	Lists the companies in the account/environment.
GET	/v1/companies/:id	200 OK	Fetches a single company by id.
PATCH	/v1/companies/:id	200 OK	Updates a company. Accepts the creation fields, all optional. Send `simplesRate` (and `simplesIssRate`, or `null` to remove it) to update the Simples rate, for example every month.
DELETE	/v1/companies/:id	200 OK	Deletes a company (logical deletion).

Certificates

Details and examples

Method	Endpoint	Success	Description
POST	/v1/companies/:companyId/certificates	201 Created	Uploads an A1 certificate (`.p12`/`.pfx`) for a company. The certificate is parsed, its validity is checked, and its CNPJ must match the company's.
GET	/v1/companies/:companyId/certificates	200 OK	Lists the certificates of a company.
DELETE	/v1/companies/:companyId/certificates/:certId	204 No Content	Revokes a certificate and updates the company's readiness.

Invoices

Details and examples

Method	Endpoint	Success	Description
POST	/v1/invoices	202 Accepted	Requests NFS-e issuance. Issuance is asynchronous: HTTP success means the request was registered/queued — it does not mean fiscal authorization. These examples use the CNPJ (`companyTaxId`) of a company registered with `municipalityCode` and `defaultServiceCode`. The issuer municipality always comes from the company.
POST	/v1/invoices/batches	202 Accepted	Requests the issuance of 1 to 50 invoices in a single call, for one company or for several. Each item has the same fields as `POST /v1/invoices` plus an optional `idempotencyKey`. Items are checked one by one: valid items are saved together in a single transaction, invalid items come back as `rejected` with the reason and are not saved. Issuance stays asynchronous, as in `POST /v1/invoices`.
POST	/v1/invoices/calculate	200 OK	Calculates the taxes of an invoice without issuing it: it stores no invoice, uses no credit, reserves no DPS number, schedules nothing and does not call Sefin. Use it to check the fiscal setup and show the amount to the customer before `POST /v1/invoices`.
GET	/v1/invoices	200 OK	Lists invoices, newest first.
GET	/v1/invoices/:id	200 OK	Fetches a single invoice by id.
GET	/v1/invoices/:id/xml	200 OK	Downloads the XML of an authorized invoice.
GET	/v1/invoices/:id/pdf	200 OK	Downloads the PDF of an authorized invoice.
GET	/v1/invoices/:id/events	200 OK	Fetches the status history of an invoice, oldest first. Paginated like any list (`limit`, `cursor`).
POST	/v1/invoices/:id/download-url	200 OK	Generates a short-lived signed URL for the invoice documents.
POST	/v1/invoices/:id/email	202 Accepted	Requests email delivery of the invoice to the address stored in `customerSnapshot.email`; no alternative recipient is accepted. The invoice must be authorized with documents ready.
POST	/v1/invoices/:id/cancel	200 OK / 202 Accepted	Cancels an invoice. A `queued` invoice (scheduled or not yet processed) is cancelled immediately; an `authorized` NFS-e moves to `cancelling` while event 101101 is sent to the Sefin. A `processing` invoice (being issued) registers the request: `202`, still `processing`, with `cancellationRequestedAt` set.

Webhooks

Details and examples

Method	Endpoint	Success	Description
GET	/v1/webhooks	200 OK	Lists the webhook configurations of the account.
POST	/v1/webhooks	201 Created	Registers a webhook configuration.
DELETE	/v1/webhooks/:id	200 OK	Deletes a webhook configuration.
POST	/v1/webhooks/:id/test	200 OK	Sends a `webhook.test` event — always with environment `test` — to the registered URL.
GET	/v1/webhooks/deliveries	200 OK	Lists webhook deliveries, newest first.
GET	/v1/webhooks/deliveries/stats	200 OK	Fetches delivery statistics for the recent window.
POST	/v1/webhooks/deliveries/:id/retry	200 OK	Schedules a new delivery attempt for a failed delivery.

Billing & quotas

Details and examples

Method	Endpoint	Success	Description
GET	/v1/billing/plan	200 OK	Fetches the current plan and its consumption.
GET	/v1/billing/usage	200 OK	Fetches quota availability for issuance.
POST	/v1/billing/upgrade	200 OK	Schedules the switch to the target plan on the subscription.
POST	/v1/billing/downgrade	200 OK	Schedules a plan change for the end of the period.
GET	/v1/plans	200 OK	Lists the plans with their monthly price and allowance.
GET	/v1/plans/:slug	200 OK	Fetches the price of one plan.
GET	/v1/plans/quote	200 OK	Recommends the plan for a monthly volume of invoices and estimates the total cost.

Errors

Details and examples

HTTP	Usage
200 / 201 / 202	Action completed / resource created / asynchronous processing accepted.
204	Operation completed with no body.
400	Invalid DTO, parameter, JSON, UUID, `limit` or cursor.
401 / 403	Missing or invalid authentication / access denied (scope, endpoint not enabled for API keys, blocked company).
404	Resource not found, including resources of another tenant.
409 / 410	Conflict (duplicate CNPJ, idempotency conflict, documents not ready yet) / resource retired.
413 / 415	Payload too large / unsupported encoding.
422	Fiscal validation in the domain or a rejected business rule (readiness, certificate, quota).
429	Rate limit or cooldown; honor `Retry-After`.
500 / 502 / 503 / 504	Internal error / invalid dependency / unavailability / timeout.

code	When it happens
`ERROR_VALIDATION`	Invalid body or query; see `details[]`.
`ERROR_INVALID_LIMIT`	`limit` outside 1–1000 or not an integer (400).
`ERROR_INVALID_CURSOR`	Tampered cursor, or one from another collection, tenant or filter (400).
`ERROR_RATE_LIMIT_EXCEEDED`	Request limit exceeded (429).
`ERROR_INSUFFICIENT_CREDITS` / `ERROR_QUOTA_EXCEEDED`	Not enough credits or quota to issue.
`ERROR_COMPANY_NOT_READY` / `ERROR_COMPANY_BLOCKED`	Company without an active certificate in `live`, or blocked.
`ERROR_IDEMPOTENCY_CONFLICT`	Same `Idempotency-Key` with a different payload (409).
`ERROR_TAX_REGIME_NOT_SUPPORTED`	Only MEI and Simples Nacional companies are supported (422).
`ERROR_VALIDATION` with `details[].code` `ERROR_DEDUCTION_NOT_ALLOWED_FOR_REGIME` or `ERROR_SIMPLES_SUBLIMIT_NOT_SUPPORTED`	A deduction from the ISS base that a MEI or a Simples company cannot declare, or a Simples company above a sublimit (`regApTribSN` 2 or 3), which is not supported yet (422).
`ERROR_GONE`	Retired operation, such as one-off credit purchases (410).