Empresas

Cadastre e gerencie as empresas para emissão de NFS-e.

Permissões: consultas usam nfse.companies.view; escrita usa nfse.companies.manage.

Do cadastro à emissão

POST /v1/companies com taxRegime e municipalityCode. municipalReg é opcional.
POST /v1/companies/:id/certificates com o certificado A1.
POST /v1/invoices.

O regime informado no cadastro cria o perfil fiscal da empresa, vigente desde hoje e já aprovado por quem fez a chamada (usuário ou chave de API). Sem tomador ou com tomador CPF não há etapa de aprovação nem cadastro de serviço: a classificação vem do catálogo oficial pelo service.code. Com tomador CNPJ a retenção federal depende da política do serviço: cadastre o perfil do serviço com withholdingPolicy NONE_CONFIRMED ou CONFIGURED e aprove-o, senão o cálculo volta blocked com TAX_APPLICABILITY_UNKNOWN. GET /v1/companies/:id mostra status e setupGaps (municipality_code, certificate). Use POST /v1/invoices/calculate para conferir antes de emitir.

Mudar taxRegime, simpleNational ou specialRegime com PATCH no mesmo dia do cadastro retorna 409 (ERROR_CONFLICT, mensagem profile_validity_conflict), porque o perfil aprovado não é reescrito. Para uma mudança com data, use PUT /v1/companies/:id/fiscal-profile com validFrom. Perfis de serviço (/v1/companies/:id/service-tax-profiles) são opcionais e passam a ser exigidos quando o regime pede IBS/CBS ou ISS configurado: o cálculo retorna FISCAL_CLASSIFICATION_REQUIRED com os campos que faltam.

POST/v1/companies201 Created

full_access

Cadastra uma empresa.

Campo	Tipo	Obrigatório	Descrição
legalName	string	✓	Razão social, até 200 caracteres, não vazia após trim.
taxId	string	✓	CNPJ válido; normalizado antes de verificar duplicidade.
taxRegime	string	✓	`MEI` ou `Simples Nacional`. A Corvo atende só esses dois regimes: qualquer outro valor devolve `422` `ERROR_TAX_REGIME_NOT_SUPPORTED`.
tradeName	string		Até 200 caracteres.
municipalReg	string ou null		Opcional, e não vazia quando enviada. Fica guardada, mas não vai na nota a menos que `sendMunicipalReg` seja `true`. `null` limpa o valor (e desliga `sendMunicipalReg`).
sendMunicipalReg	boolean		Padrão `false`. Envia a inscrição municipal na DPS só se o município registrou esta empresa no cadastro nacional e a Receita exigir; senão a nota é rejeitada (E0120).
municipalityCode	string	✓	Código IBGE de exatamente 7 dígitos, obrigatório em teste e produção. Usado como município do emitente e padrão do local da prestação.
defaultServiceCode	string		Código nacional (cTribNac) de exatamente 6 dígitos; padrão das novas notas. Sem ele, informe `service.code` na emissão.
simpleNational	boolean		Se omitido, acompanha o regime (`true` para MEI e Simples Nacional).
specialRegime	string		Um valor entre `"0"` e `"6"` (regEspTrib, RTC v1.01): 0 Nenhum, 1 Ato Cooperado, 2 Estimativa, 3 Microempresa Municipal, 4 Notário ou Registrador, 5 Profissional Autônomo, 6 Sociedade de Profissionais.
simplesRate	string		Obrigatório para `Simples Nacional`, ignorado para `MEI`. Alíquota efetiva total (%) do seu DAS, a que aparece no PGDAS-D, por exemplo `"6.54"` (0 a 100, no máximo 2 casas decimais). Vai em toda nota (`pTotTribSN`). A Corvo não calcula o DAS.
simplesIssRate	string		Opcional, só `Simples Nacional`. Alíquota efetiva de ISS (%) da sua faixa (1,80 a 5,00), necessária só quando algum cliente retém ISS. Ignorada para `MEI`.
address	objeto		`street` (200), `number` (20), `complement` (100), `district` (100), `city` (100), `state` (2) e `zip` (10), todos opcionais. UF válida, normalizada para maiúsculas. CEP com 8 dígitos, armazenado sem pontuação.

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"
    }
  }'

Resposta — 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"
  }
}

CNPJ repetido na mesma conta/ambiente retorna 409. Em live, o cadastro pode falhar por limite de empresas ou plano bloqueado (422).

O corpo de entrada usa address, mas a resposta expõe campos planos: addressStreet, addressNumber, addressCity, addressState, addressZip etc. status é pending_setup, ready ou blocked; setupGaps lista pendências (municipality_code, certificate).

GET/v1/companies200 OK

full_accessinvoices_read_write

Lista as empresas da conta, com paginação por cursor.

Query

Campo	Tipo	Obrigatório	Descrição
limit	integer		Padrão `50`; aceita inteiros de 1 a 1000 (valor inválido retorna `400`).
cursor	string		`nextCursor` da página anterior, mantendo os mesmos filtros.

curl "$BASE_URL/companies?limit=50&cursor=2026-10-10T12%3A00%3A00.000Z%7C3f1c8a90" \
  -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

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

Ordenação createdAt DESC, depois id DESC. Continue com pagination.nextCursor até hasMore: false; não há total.

GET/v1/companies/:id200 OK

full_accessinvoices_read_write

Consulta uma empresa pelo id.

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

Resposta — 200 OK

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

Empresa inexistente, excluída ou de outro ambiente/conta retorna 404. Um id que não seja um UUID válido retorna 400 (ERROR_BAD_REQUEST).

PATCH/v1/companies/:id200 OK

full_access

Atualiza uma empresa. Aceita os campos da criação, todos opcionais, **exceto o CNPJ**: ele não pode ser alterado (enviar o CNPJ atual é aceito e ignorado; outro valor retorna 422). Para outro CNPJ, cadastre uma nova empresa. Envie simplesRate (e simplesIssRate, ou null para remover) para atualizar a alíquota do Simples, por exemplo todo mês.

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" }'

Resposta — 200 OK

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

municipalReg: null limpa a inscrição; address: null limpa o endereço. defaultServiceCode omitido mantém o padrão; null remove; valor vazio ou inválido é rejeitado. municipalityCode exige 7 dígitos quando informado e não pode ser apagado. environment não pode ser alterado.

Pode retornar 400 por validação, 404 ou 409 por CNPJ duplicado.

DELETE/v1/companies/:id200 OK

full_access

Exclui uma empresa (exclusão lógica).

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

Resposta — 200 OK

{
  "data": null
}

Exclusão lógica, sem corpo na requisição. Retorna 404 se a empresa não for encontrada.