Companies

Permissions: fetches use nfse.companies.view; writes use nfse.companies.manage.

From signup to issuing

POST /v1/companies with taxRegime and municipalityCode. municipalReg is optional.
POST /v1/companies/:id/certificates with the A1 certificate.
POST /v1/invoices.

The regime sent when creating the company creates its fiscal profile, valid from today and already approved by the caller (user or API key). Without a customer or with a CPF customer there is no approval step or service setup: classification comes from the official catalog by service.code. With a CNPJ customer the federal withholding depends on the service policy: create the service profile with withholdingPolicy NONE_CONFIRMED or CONFIGURED and approve it, otherwise the calculation returns blocked with TAX_APPLICABILITY_UNKNOWN. GET /v1/companies/:id shows status and setupGaps (municipality_code, certificate). Use POST /v1/invoices/calculate to check before issuing.

Changing taxRegime, simpleNational or specialRegime with PATCH on the same day the company was created returns 409 (ERROR_CONFLICT, message profile_validity_conflict), because an approved profile is not rewritten. For a dated change use PUT /v1/companies/:id/fiscal-profile with validFrom. Service profiles (/v1/companies/:id/service-tax-profiles) are optional and become required when the regime needs IBS/CBS or configured ISS: the calculation returns FISCAL_CLASSIFICATION_REQUIRED with the missing fields.

POST/v1/companies201 Created

full_access

Registers a company.

Field	Type	Required	Description
legalName	string	✓	Legal name, up to 200 characters, not empty after trim.
taxId	string	✓	Valid CNPJ; normalized before the duplicate check.
taxRegime	string	✓	`MEI` or `Simples Nacional`. Corvo serves only these two regimes: any other value returns `422` `ERROR_TAX_REGIME_NOT_SUPPORTED`.
tradeName	string		Up to 200 characters.
municipalReg	string or null		Optional, and nonblank when sent. It is stored but not sent on the invoice unless `sendMunicipalReg` is `true`. `null` clears it (and turns `sendMunicipalReg` off).
sendMunicipalReg	boolean		Default `false`. Send the municipal registration in the DPS only if the city registered this company in the national registry and the tax authority requires it; otherwise the invoice is rejected (E0120).
municipalityCode	string	✓	Exactly 7 digits (IBGE), required in test and live mode. Used as the issuer municipality and default service location.
defaultServiceCode	string		Exactly 6 digits (cTribNac); default for new invoices. Without it, provide `service.code` when issuing.
simpleNational	boolean		If omitted, follows the regime (`true` for MEI and Simples Nacional).
specialRegime	string		One of `"0"`–`"6"` (regEspTrib, RTC v1.01): 0 None, 1 Cooperative Act, 2 Estimate, 3 Municipal Microenterprise, 4 Notary or Registrar, 5 Self-employed Professional, 6 Professional Partnership.
simplesRate	string		Required for `Simples Nacional`, ignored for `MEI`. Effective total rate (%) of your DAS, the one shown in the PGDAS-D, e.g. `"6.54"` (0 to 100, at most 2 decimals). It goes on every invoice (`pTotTribSN`). Corvo does not compute the DAS.
simplesIssRate	string		Optional, `Simples Nacional` only. Effective ISS rate (%) of your bracket (1.80 to 5.00), needed only when a customer withholds ISS. Ignored for `MEI`.
address	object		`street` (200), `number` (20), `complement` (100), `district` (100), `city` (100), `state` (2) and `zip` (10), all optional strings. A filled-in state must be a valid UF and is normalized to uppercase. A filled-in zip must be 8 digits and is stored without punctuation.

curl -X POST "$BASE_URL/companies" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Empresa Exemplo Ltda",
    "taxId": "11222333000181",
    "taxRegime": "Simples Nacional",
    "simplesRate": "6.54",
    "simpleNational": true,
    "municipalReg": "123456",
    "municipalityCode": "3550308",
    "defaultServiceCode": "010101",
    "address": {
      "street": "Rua Exemplo",
      "number": "100",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01001000"
    }
  }'

Response — 201 Created

{
  "data": {
    "id": "3f1c8a90-6b2e-4d5a-9c11-8e2f0a7b4d11",
    "legalName": "Empresa Exemplo Ltda",
    "taxId": "11222333000181",
    "taxRegime": "Simples Nacional",
    "municipalityCode": "3550308",
    "defaultServiceCode": "010101",
    "status": "pending_setup",
    "environment": "test",
    "createdAt": "2026-10-10T12:00:00.000Z"
  }
}

A duplicate CNPJ in the same account/environment returns 409. The CNPJ cannot be changed afterwards. In live, creation can fail on company limit or blocked plan (422).

The input body uses address, but the response exposes flat fields: addressStreet, addressNumber, addressCity, addressState, addressZip etc. status is pending_setup, ready or blocked; setupGaps lists pending items (municipality_code, certificate).

GET/v1/companies200 OK

full_accessinvoices_read_write

Lists the companies in the account/environment.

Field	Type	Required	Description
limit	integer		Defaults to `50`; accepts integers from 1 to 1000 (an invalid value returns `400`).
cursor	string		`nextCursor` from the previous page, keeping the same filters.

curl "$BASE_URL/companies?limit=50" \
  -H "X-API-Key: $CORVO_API_KEY"

Response — 200 OK

{
  "data": [
    {
      "id": "3f1c8a90-6b2e-4d5a-9c11-8e2f0a7b4d11",
      "legalName": "Empresa Exemplo Ltda",
      "taxId": "11222333000181",
      "status": "ready",
      "environment": "test"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "eyJ2IjoxLCJjcmVhdGVkQXQiOiIyMDI2LTEwLTA5VDEyOjAwOjAwLjAwMDAwMFoiLCJpZCI6IjNmMWM4YTkwIn0"
  }
}

Ordering is createdAt DESC, then id DESC. Continue with pagination.nextCursor until hasMore: false; there is no total.

GET/v1/companies/:id200 OK

full_accessinvoices_read_write

Fetches a single company by id.

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

Response — 200 OK

{
  "data": {
    "id": "3f1c8a90-6b2e-4d5a-9c11-8e2f0a7b4d11",
    "legalName": "Empresa Exemplo Ltda",
    "taxId": "11222333000181",
    "municipalReg": "123456",
    "taxRegime": "Simples Nacional",
    "status": "ready",
    "environment": "test",
    "setupGaps": []
  }
}

A company that does not exist, was deleted, or belongs to another environment/account returns 404. An id that is not a valid UUID returns 400 (ERROR_BAD_REQUEST).

PATCH/v1/companies/:id200 OK

full_access

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.

Field	Type	Description
legalName	string	Legal name, up to 200 characters, not empty after trim.
taxId	string	The CNPJ cannot be changed. Sending the current CNPJ is accepted and ignored; any other value returns `422`. To use another CNPJ, create a new company.
taxRegime	string	`MEI` or `Simples Nacional`. Corvo serves only these two regimes: any other value returns `422` `ERROR_TAX_REGIME_NOT_SUPPORTED`.
tradeName	string	Up to 200 characters.
municipalReg	string or null	Optional. Stored but not sent on the invoice unless `sendMunicipalReg` is `true`. `null` clears it.
municipalityCode	string	Exactly 7 digits when provided; omit to keep the existing value. Cannot be cleared.
defaultServiceCode	string or null	Exactly 6 digits when provided. Omit to keep; null clears the default.
simpleNational	boolean	Omit it to keep the current value.
specialRegime	string	One of `"0"`–`"6"` (regEspTrib, RTC v1.01), same codes as on creation. Empty string clears it; omit to keep the current value.
simplesRate	string	Omit it to keep the current value. Send a new value to update it (for example, each month). Ignored for `MEI`.
simplesIssRate	string or null	Same format as on creation. `null` removes it.
address	object or null	Same fields as on creation. `null` clears the address.

curl -X PATCH "$BASE_URL/companies/$COMPANY_ID" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tradeName": "Novo nome", "municipalReg": "987654" }'

Response — 200 OK

{
  "data": {
    "id": "3f1c8a90-6b2e-4d5a-9c11-8e2f0a7b4d11",
    "tradeName": "Novo nome",
    "municipalReg": "987654",
    "status": "ready"
  }
}

municipalReg: null clears municipal registration and address: null clears the address. Omit defaultServiceCode to keep it; null clears it; empty or invalid values are rejected. A supplied municipalityCode must have 7 digits and cannot be cleared. environment cannot be changed. May return 400 on validation, 404, or 409 on a duplicate CNPJ.

DELETE/v1/companies/:id200 OK

full_access

Deletes a company (logical deletion).

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

Response — 200 OK

{
  "data": null
}

Returns 404 if the company is not found.