Notas Fiscais

Emitir Nota de uma Cobrança

Emite a nota de uma cobrança que já existe — a que nunca emitiu e também a que falhou. O identificador na URL é o da cobrança: invoiceId de uma fatura de assinatura ou chargeId de uma cobrança avulsa.

Diferente da emissão avulsa, a nota nasce ligada à cobrança: herda cliente, valor e, quando existe, assinatura e ciclo.

De onde vem a configuração fiscal

Na ordem: o configId do corpo, depois o da nota anterior, o nfConfigId da cobrança e o da assinatura. Não achando nenhum, a resposta é NF_CONFIG_REQUIRED e nada é emitido.

Quando a emissão é recusada

INVOICE_NOT_FOUND (404) — cobrança inexistente ou de outra conta
INVOICE_STATUS_NOT_EMITTABLE — só emite cobrança pendente, aguardando pagamento ou paga
NOTA_ALREADY_ISSUED — já existe nota autorizada, vinculada ou agendada para essa cobrança
NOTA_PROCESSING — há uma emissão em andamento aguardando o retorno da prefeitura
NF_INCOMPLETE_DATA — faltam dados do tomador; details lista exatamente o que falta
NF_CONFIG_NOT_FOUND — a configuração informada não existe ou está desabilitada

Para conferir os dados antes sem emitir nada, use POST /v1/invoices/notas/{notaId}/verificar-emissao.

Case de uso:

Como prestador, quero emitir a nota de uma cobrança que ficou sem nota, sem precisar refazer a cobrança.

POST/v1/invoices/notas/:notaid/emitir

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string · header · required

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

nota.fiscal/write

Path Parameters

Name	Type	Required	Description
notaid	string	Required	Notaid

Body

application/json

Content-Type:application/json

{
  "configId": "unc_1776888897617_ppwgo7oef"
}

Schema

configIdstringOptional

Configuração fiscal a usar; sem ela vale a da cobrança ou da assinatura

← Anterior

Emitir Nota Fiscal

Verificar Dados para Emissão

const url = 'https://sandbox.validapay.com.br/v1/invoices/notas/{{notaId}}/emitir';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "configId": "unc_1776888897617_ppwgo7oef"
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200200

{
  "success": true,
  "invoiceId": "inv_1788101026585_uqaspo7bn",
  "subscriptionId": "sub_1788101026585_a1b2c3d4e",
  "cycleNumber": 3,
  "type": "NFSE",
  "status": "PROCESSING",
  "numero": null,
  "tipo": "nacional"
}

400400 - dados incompletos

{
    "error": {
        "message": "Dados incompletos para emitir a nota fiscal: CEP do cliente, Município do cliente (código IBGE)",
        "code": "NF_INCOMPLETE_DATA",
        "details": [
            "CEP do cliente",
            "Município do cliente (código IBGE)"
        ],
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

400400 - sem emissor

{
    "error": {
        "message": "Informe o emissor (configId) para emitir a nota fiscal",
        "code": "NF_CONFIG_REQUIRED",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

404404

{
    "error": {
        "message": "Cobrança não encontrada",
        "code": "INVOICE_NOT_FOUND",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Emitir Nota Fiscal

Verificar Dados para Emissão