Notas Fiscais
Referência
A ValidaPay emite nota fiscal de serviço (NFS-e) pelo CNPJ do seu cliente, a partir de uma configuração fiscal cadastrada uma vez por empresa emissora. Este guia explica como a configuração funciona, por qual padrão a nota sai e o que a API permite fazer depois da emissão.
Não há webhook de nota fiscal
A prefeitura responde de forma assíncrona: a emissão volta como PROCESSING e o desfecho aparece na consulta da nota, não em um evento. Acompanhe por Consultar Nota Fiscal.
Como uma nota nasce
São quatro caminhos, todos apontando para a mesma configuração fiscal. Com nfConfigId na cobrança, customer.address passa a ser obrigatório — a nota precisa do endereço do tomador.
nfConfigId em POST /v1/charges — a nota sai junto da cobrança, sem chamada extra.
Automática pela assinatura
nfConfigId no produto ou na assinatura, para emitir a cada ciclo sem repetir o campo.
POST /v1/invoices/notas para um serviço cobrado fora da plataforma.
POST /v1/invoices/notas/{notaId}/emitir para a cobrança que ficou sem nota ou cuja emissão falhou.
A configuração fiscal
É o cadastro da empresa emissora: CNPJ, regime tributário, certificado digital A1, tributos padrão e o momento da emissão. Fica em /v1/invoices/notas/config e devolve um id no formato unc_…, que circula com dois nomes:
| Onde | Campo |
|---|---|
| Emissão avulsa | configId |
| Cobrança, produto e assinatura | nfConfigId |
Uma conta pode ter várias configurações, uma por empresa — o CNPJ em prestador.cnpj define de qual empresa a nota sai.
Criar ou atualizar uma configuração valida e registra a empresa emissora. Se essa etapa falhar, nada é gravado e o certificado enviado é descartado: não existe configuração pela metade.
Certificado digital
O A1 em certificate.pfx_base64 com a password é o que autoriza a emissão. A senha nunca volta nas consultas — a resposta traz apenas has_certificate e expiry_date.
Credencial da prefeitura
Municípios com sistema próprio podem exigir também o acesso ao portal, no bloco prefeitura — nem todos pedem login, e em parte deles a senha é uma chave digital gerada no portal. O mesmo bloco leva a numeração do RPS: serie_rps e proximo_numero_rps continuam a sequência já registrada na prefeitura.
Municipal ou nacional: quem decide é o município
O código IBGE em prestador.codigo_municipio determina por qual padrão a nota sai, e isso muda quais campos da configuração são lidos. Você não precisa escolher: a rota é resolvida na emissão. tipo_nf força um dos dois e só faz sentido quando o município aceita ambos.
| NFS-en nacional | NFS-e municipal | |
|---|---|---|
| Quando | Município no padrão nacional da NFS-e — a maioria | Município com sistema próprio |
| Campos usados | codigo_tributacao_nacional_iss, tributacao_iss, tipo_retencao_iss, serie_dps | item_lista_servico, aliquota_iss, iss_retido, natureza_operacao |
| Campos extras | PIS/COFINS ou percentual do Simples, conforme o regime | codigo_cnae e codigo_tributario_municipio, quando o município exige |
| Credencial da prefeitura | Não exige — basta o certificado digital | Pode exigir credencial do portal, no bloco prefeitura |
| Numeração | serie_dps, declarada no cadastro e enviada em cada emissão | prefeitura.serie_rps e prefeitura.proximo_numero_rps |
Na dúvida sobre em qual padrão o município está, preencha os dois conjuntos — o que não se aplica é ignorado.
Campos exigidos pelo regime
O regime vem de prestador.codigo_opcao_simples_nacional, sempre como número. Faltando um campo do regime, a configuração não é gravada e a resposta traz a mensagem da validação com o código INTERNAL_ERROR.
| Valor | Regime | Campos obrigatórios |
|---|---|---|
1 | Não optante | situacao_tributaria_pis_cofins, aliquota_pis, aliquota_cofins |
2 | MEI | percentual_total_tributos_simples_nacional |
3 | ME/EPP | percentual_total_tributos_simples_nacional |
Quando a nota é emitida
invoiceTiming, na configuração fiscal, vale para as notas geradas por cobrança. A emissão avulsa sai sempre na hora, qualquer que seja o valor.
| Valor | Emissão |
|---|---|
IMMEDIATE | Junto com a cobrança. É o padrão. |
AFTER_CONFIRMATION | Somente após a confirmação do pagamento. |
DAYS_AFTER_CONFIRMATION | daysAfterConfirmation dias após a confirmação (padrão 1). |
Configurações criadas pelo painel trazem também quando_emitir, com os mesmos valores. É apenas o espelho gravado pela tela — quem define o agendamento é invoiceTiming.
O identificador da nota
Todas as rotas de nota usam o mesmo identificador: o campo invoiceId da listagem. Na nota avulsa ele é o ref que você informou na emissão; na nota de cobrança, é o identificador da própria cobrança.
O campo ref da resposta é outra coisa: o identificador interno da nota, útil apenas para suporte.
Status da nota
| Status | Significado |
|---|---|
PROCESSING | Enviada; a prefeitura ainda não respondeu. |
ISSUED / AUTHORIZED | Autorizada. Equivalentes: o primeiro vem da emissão síncrona, o segundo da confirmação da prefeitura. |
FAILED / ERROR | Recusada; nf.errors traz as mensagens do que precisa ser corrigido. |
CANCELED | Cancelada na prefeitura. |
REPLACED | Substituída por uma reemissão. |
No filtro status da listagem os pares são intercambiáveis: AUTHORIZED traz também as ISSUED, e ERROR traz também as FAILED.
Erros mais comuns
| Código | Significado |
|---|---|
NOTA_CONFIG_NOT_FOUND | Configuração fiscal inexistente ou desabilitada. |
NF_CONFIG_REQUIRED | Nenhuma configuração encontrada para a cobrança. |
NF_INCOMPLETE_DATA | Faltam dados do tomador; details lista exatamente o que falta. |
INVOICE_STATUS_NOT_EMITTABLE | Só emite cobrança pendente, aguardando pagamento ou paga. |
NOTA_ALREADY_ISSUED | Já existe nota autorizada, vinculada ou agendada para a cobrança. |
NOTA_PROCESSING | Emissão em andamento aguardando o retorno da prefeitura. |
NOTA_NOT_ISSUED | Reenvio por e-mail de nota que ainda não foi autorizada. |
NF_NOT_AUTHORIZED | Cancelamento de nota que não está autorizada. |
NF_CANCEL_FAILED | A prefeitura recusou o cancelamento — normalmente prazo vencido. |
NOTA_TYPE_NOT_SUPPORTED | type diferente de NFSE; os demais modelos ainda não foram liberados. |
Boas práticas
- Rode Verificar Dados para Emissão antes de emitir: ele devolve em pendencias exatamente o que falta no cadastro do cliente, sem emitir nada.
- Guarde o invoiceId da nota logo após a emissão — é a chave de todas as outras rotas.
- Acompanhe certificate.expiry_date das configurações: certificado vencido derruba a emissão inteira da empresa.
- Corrija a causa antes de reemitir; a mensagem da prefeitura está em nf.errors, na consulta da nota.
- Nota autorizada não se corrige: cancele dentro do prazo do município e emita outra.