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

Referência da API de NFS-e

Base URL: https://api.corvo.tech/v1. Autenticação pelo header X-API-Key. Cada seção leva à página da documentação com parâmetros e exemplos.

Empresas

Detalhes e exemplos

Método	Endpoint	Sucesso	Descrição
POST	/v1/companies	201 Created	Cadastra uma empresa.
GET	/v1/companies	200 OK	Lista as empresas da conta, com paginação por cursor.
GET	/v1/companies/:id	200 OK	Consulta uma empresa pelo id.
PATCH	/v1/companies/:id	200 OK	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.
DELETE	/v1/companies/:id	200 OK	Exclui uma empresa (exclusão lógica).

Certificados

Detalhes e exemplos

Método	Endpoint	Sucesso	Descrição
POST	/v1/companies/:companyId/certificates	201 Created	Envia o certificado A1 (.p12/.pfx) da empresa em `multipart/form-data`.
GET	/v1/companies/:companyId/certificates	200 OK	Lista os certificados de uma empresa.
DELETE	/v1/companies/:companyId/certificates/:certId	204 No Content	Revoga um certificado e atualiza a prontidão da empresa.

Notas fiscais

Detalhes e exemplos

Método	Endpoint	Sucesso	Descrição
POST	/v1/invoices	202 Accepted	Solicita a emissão de uma NFS-e. A emissão é assíncrona: o sucesso HTTP significa que a solicitação foi registrada/enfileirada, não autorização fiscal. Os exemplos usam o CNPJ (`companyTaxId`) da empresa cadastrada com `municipalityCode` e `defaultServiceCode`. O município do emitente sempre vem da empresa.
POST	/v1/invoices/batches	202 Accepted	Solicita a emissão de 1 a 50 notas em uma única chamada, de uma empresa ou de várias. Cada item tem os mesmos campos de `POST /v1/invoices` mais um `idempotencyKey` opcional. Os itens são conferidos um a um: os válidos são salvos juntos em uma única transação e os inválidos voltam como `rejected` com o motivo e não são salvos. A emissão continua assíncrona, como em `POST /v1/invoices`.
POST	/v1/invoices/calculate	200 OK	Calcula os tributos de uma nota sem emitir: não grava nota, não consome crédito, não reserva número de DPS, não agenda nem chama a Sefin. Use para conferir a configuração fiscal e mostrar o valor ao cliente antes de `POST /v1/invoices`.
GET	/v1/invoices	200 OK	Lista notas com filtros e paginação por cursor.
GET	/v1/invoices/:id	200 OK	Consulta uma nota pelo id.
GET	/v1/invoices/:id/xml	200 OK	Baixa o XML da nota autorizada.
GET	/v1/invoices/:id/pdf	200 OK	Baixa o PDF da nota autorizada.
GET	/v1/invoices/:id/events	200 OK	Consulta o histórico de transições de status da nota, do mais antigo ao mais recente. Paginado como qualquer lista (`limit`, `cursor`).
POST	/v1/invoices/:id/download-url	200 OK	Gera uma URL assinada e temporária para baixar o documento.
POST	/v1/invoices/:id/email	202 Accepted	Solicita o envio de email com os documentos para o endereço armazenado em `customerSnapshot.email`.
POST	/v1/invoices/:id/cancel	200 OK / 202 Accepted	Cancela uma nota. Uma nota `queued` (agendada ou ainda não processada) é cancelada na hora; uma NFS-e `authorized` passa a `cancelling` enquanto o evento 101101 é enviado à Sefin. Uma nota `processing` (em emissão) registra o pedido: `202`, ainda `processing`, com `cancellationRequestedAt` preenchido.

Webhooks

Detalhes e exemplos

Método	Endpoint	Sucesso	Descrição
GET	/v1/webhooks	200 OK	Lista as configurações de webhook da conta.
POST	/v1/webhooks	201 Created	Cadastra uma configuração de webhook.
DELETE	/v1/webhooks/:id	200 OK	Exclui uma configuração de webhook.
POST	/v1/webhooks/:id/test	200 OK	Envia o evento `webhook.test` para a URL cadastrada.
GET	/v1/webhooks/deliveries	200 OK	Lista as entregas de webhook, ordenadas por criação decrescente.
GET	/v1/webhooks/deliveries/stats	200 OK	Consulta estatísticas das entregas recentes.
POST	/v1/webhooks/deliveries/:id/retry	200 OK	Agenda nova tentativa de entrega de um webhook.

Plano e cotas

Detalhes e exemplos

Método	Endpoint	Sucesso	Descrição
GET	/v1/billing/plan	200 OK	Consulta o plano atual e o consumo do período.
GET	/v1/billing/usage	200 OK	Consulta a disponibilidade de emissão e as cotas do plano.
POST	/v1/billing/upgrade	200 OK	Agenda a troca para o plano de destino na assinatura.
POST	/v1/billing/downgrade	200 OK	Agenda uma mudança de plano para o fim do período.
GET	/v1/plans	200 OK	Lista os planos com preço mensal e franquia.
GET	/v1/plans/:slug	200 OK	Consulta o preço de um plano.
GET	/v1/plans/quote	200 OK	Recomenda o plano para um volume mensal de notas e estima o custo total.

Erros

Detalhes e exemplos

HTTP	Uso
200 / 201 / 202	Ação concluída / recurso criado / processamento assíncrono aceito.
204	Operação concluída sem corpo.
400	DTO, parâmetro, JSON, UUID, `limit` ou cursor inválido.
401 / 403	Autenticação ausente ou inválida / acesso negado (escopo, endpoint não habilitado para API key, empresa bloqueada).
404	Recurso inexistente, inclusive de outro tenant.
409 / 410	Conflito (CNPJ duplicado, idempotência conflitante, documentos ainda não prontos) / recurso encerrado.
413 / 415	Payload excessivo / codificação não suportada.
422	Validação fiscal no domínio ou regra de negócio rejeitada (prontidão, certificado, cota).
429	Rate limit ou cooldown; respeite `Retry-After`.
500 / 502 / 503 / 504	Erro interno / dependência inválida / indisponibilidade / timeout.

code	Quando ocorre
`ERROR_VALIDATION`	Corpo ou query inválidos; veja `details[]`.
`ERROR_INVALID_LIMIT`	`limit` fora de 1–1000 ou não inteiro (400).
`ERROR_INVALID_CURSOR`	Cursor adulterado ou de outra coleção, tenant ou filtro (400).
`ERROR_RATE_LIMIT_EXCEEDED`	Limite de requisições excedido (429).
`ERROR_INSUFFICIENT_CREDITS` / `ERROR_QUOTA_EXCEEDED`	Créditos ou cota insuficientes para emitir.
`ERROR_COMPANY_NOT_READY` / `ERROR_COMPANY_BLOCKED`	Empresa sem certificado em `live`, ou bloqueada.
`ERROR_IDEMPOTENCY_CONFLICT`	Mesma `Idempotency-Key` com payload diferente (409).
`ERROR_TAX_REGIME_NOT_SUPPORTED`	Só empresas MEI e Simples Nacional são atendidas (422).
`ERROR_VALIDATION` com `details[].code` `ERROR_DEDUCTION_NOT_ALLOWED_FOR_REGIME` ou `ERROR_SIMPLES_SUBLIMIT_NOT_SUPPORTED`	Dedução da base do ISS que o MEI ou o Simples não pode declarar, ou Simples acima do sublimite (`regApTribSN` 2 ou 3), que ainda não é suportado (422).
`ERROR_GONE`	Operação encerrada, como a compra avulsa de créditos (410).