Notas Fiscais

Referência

Este recurso reúne dois conceitos diferentes: a configuração fiscal, que cadastra a empresa emissora e a tributação usada para emitir, e a nota fiscal propriamente dita. Uma configuração precisa existir e estar habilitada antes de qualquer nota poder ser emitida.

Notas e configuração fiscal dividem a mesma raiz de rota: /v1/invoices/notas para as notas e /v1/invoices/notas/config para a configuração. Um configId nunca é um notaId: eles identificam registros diferentes, mesmo com a rota parecida.

Configuração fiscal

A configuração fiscal cadastra a empresa emissora (CNPJ, município, tributação) e o certificado digital usado para autenticar a emissão junto à prefeitura. Uma conta pode ter configurações de mais de uma empresa: o configId escolhido na emissão define de qual delas a nota sai. Campos não enviados são preenchidos a partir do cadastro da conta, quando disponíveis.

Campo	Obrigatório	Descrição
`prestador.cnpj`	Sim	CNPJ da empresa emissora, 14 dígitos.
`prestador.codigo_municipio`	Sim	Código IBGE do município do prestador, 7 dígitos. Define se a nota sai pelo emissor Nacional ou Municipal.
`prestador.codigo_opcao_simples_nacional`	Sim	Regime tributário, como número: 1 não optante, 2 MEI, 3 ME/EPP.
`prestador.regime_especial_tributacao`	Sim	0 quando não há regime especial.
`codigo_tributacao_nacional_iss`	Sim	Código de tributação nacional do ISS, 6 dígitos.
`tributacao_iss`	Sim	1 tributável, 2 imunidade, 3 exportação, 4 não incidência.
`tipo_retencao_iss`	Sim	1 não retido, 2 retido pelo tomador, 3 pelo intermediário.
`situacao_tributaria_pis_cofins, aliquota_pis, aliquota_cofins`	Se não optante	Obrigatórios quando codigo_opcao_simples_nacional é 1 (não optante pelo Simples).
`percentual_total_tributos_simples_nacional`	Se optante	Obrigatório quando codigo_opcao_simples_nacional é 2 (MEI) ou 3 (ME/EPP).
`certificate.pfx_base64 / password`	Recomendado	Certificado digital A1 em base64. Sem certificado, a prefeitura normalmente recusa a empresa.
`quando_emitir`	Não	IMMEDIATE, AFTER_CONFIRMATION ou DAYS_AFTER_CONFIRMATION. Vale só para notas emitidas automaticamente a partir de cobrança ou fatura, não afeta a emissão avulsa deste guia.

JSON

{
  "config_name": "Matriz",
  "enabled": true,
  "quando_emitir": "IMMEDIATE",
  "codigo_tributacao_nacional_iss": "010701",
  "tributacao_iss": 1,
  "tipo_retencao_iss": 1,
  "situacao_tributaria_pis_cofins": "01",
  "aliquota_pis": 0.65,
  "aliquota_cofins": 3,
  "percentual_total_tributos_simples_nacional": 6,
  "prestador": {
    "cnpj": "99988877000108",
    "inscricao_municipal": "1234567",
    "nome_fantasia": "EMPRESA EXEMPLO LTDA",
    "email": "fiscal@exemplo.com.br",
    "codigo_municipio": "4205407",
    "codigo_opcao_simples_nacional": 1,
    "regime_especial_tributacao": 0
  },
  "certificate": {
    "pfx_base64": "MIIQ...",
    "password": "senha-do-certificado"
  }
}

JSON

{
  "id": "unc_1788193720141_65g0zh12p",
  "accountId": "460851686",
  "config_name": "Matriz",
  "enabled": true,
  "quando_emitir": "IMMEDIATE",
  "codigo_tributacao_nacional_iss": "010701",
  "tributacao_iss": 1,
  "tipo_retencao_iss": 1,
  "prestador": {
    "cnpj": "99988877000108",
    "nome_fantasia": "EMPRESA EXEMPLO LTDA",
    "inscricao_municipal": "1234567",
    "codigo_municipio": "4205407",
    "codigo_municipio_prestacao": "4205407",
    "codigo_opcao_simples_nacional": 1,
    "regime_especial_tributacao": 0
  },
  "focus": {
    "synced": true
  },
  "certificate": {
    "has_certificate": true,
    "expiry_date": "2026-11-18T11:01:15.000Z"
  },
  "createdAt": "2026-08-31T16:28:43.167Z",
  "updatedAt": "2026-08-31T16:28:43.167Z"
}

Criar e atualizar sincronizam a empresa (e o certificado) com a prefeitura no mesmo request. Se essa sincronização falhar, nada é gravado na criação e o certificado enviado é descartado: o erro chega como NF_CONFIG_SYNC_FAILED, com a mensagem devolvida pela prefeitura já traduzida. Excluir remove o cadastro só da ValidaPay: a empresa continua registrada na prefeitura e as notas já emitidas por essa configuração não são afetadas.

Emitir nota fiscal

POST Emitir Nota Fiscal emite uma nota de serviço avulsa, sem vínculo com cobrança ou assinatura. A emissão é sempre imediata: o campo quando_emitir da configuração vale apenas para notas geradas automaticamente a partir de cobrança ou fatura, não para esta rota. O tomador não precisa estar cadastrado como cliente.

Campo	Obrigatório	Descrição
`configId`	Sim	Configuração fiscal usada para emitir, de GET Listar Configurações Fiscais. Define de qual empresa (CNPJ) a nota sai.
`type`	Não	Modelo do documento fiscal. Único valor aceito hoje é NFSE, assumido quando o campo é omitido.
`amount`	Sim	Valor do serviço em reais, ex.: 150.00.
`descricao`	Sim	Discriminação do serviço impressa na nota.
`ref`	Não	Referência própria. Se omitida, a API gera uma.
`customer.document`	Sim	CPF (11) ou CNPJ (14) do tomador, só números.
`customer.name`	Sim	Nome completo ou razão social do tomador.
`customer.address`	Sim	Endereço do tomador. Quando cityCode não vem, o código IBGE é resolvido a partir do CEP.

JSON

{
  "configId": "unc_1776888897617_ppwgo7oef",
  "type": "NFSE",
  "amount": 150.00,
  "descricao": "Consultoria em tecnologia da informação",
  "customer": {
    "document": "11144477735",
    "name": "Alexandre Souza",
    "email": "alexandre@exemplo.com.br",
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  }
}

JSON

{
  "success": true,
  "status": "PROCESSING",
  "ref": "nf_1788101026585_uqaspo7bn",
  "id": "nf_1788101026585_uqaspo7bn",
  "nfStatus": "processando_autorizacao",
  "tipo": "nacional",
  "issuedAt": "2026-08-30T14:43:49.719Z",
  "internalStatus": "PROCESSING",
  "provedor": "Nacional"
}

Identificador e status da nota

O {notaId} usado em Consultar, Cancelar, Reemitir e Reenviar é o campo invoiceId da nota, o mesmo valor devolvido em id e ref na emissão. Isso vale inclusive para notas avulsas, que não têm fatura de verdade por trás.

Status	Significado
`PROCESSING`	Emitida, aguardando resposta da prefeitura. Estado inicial de toda emissão.
`AUTHORIZED`	Autorizada. É o status que libera cancelamento e reenvio por e-mail.
`ERROR`	A prefeitura recusou a emissão. A nota pode ser reemitida se estiver vinculada a uma cobrança ou fatura real.
`CANCELED`	Cancelada na prefeitura por DELETE Cancelar Nota Fiscal.
`REPLACED`	Substituída por uma reemissão bem-sucedida. A nota vigente passa a ser a nova.

Cancelar, reemitir e reenviar

As três ações partem de estados diferentes da nota e não são intercambiáveis:

Ação	Pré-condição	O que muda	Erro se falhar
Cancelar	Nota AUTHORIZED	Cancela na prefeitura dentro do prazo por ela definido; a nota final fica CANCELED.	`NF_NOT_AUTHORIZED`
Reemitir	Nota não autorizada e vinculada a uma cobrança ou fatura real	A nota anterior fica REPLACED e uma nova é gerada em seu lugar.	`NOTA_ALREADY_ISSUED ou INVOICE_NOT_FOUND`
Reenviar	Nota AUTHORIZED	Reenvia por e-mail a nota já emitida, para até 10 destinatários. Não gera nova nota.	`NOTA_NOT_ISSUED`

Reemitir busca a cobrança ou fatura de origem da nota. Uma nota avulsa, como as criadas por POST Emitir Nota Fiscal, não tem cobrança nem fatura por trás: tentar reemiti-la falha com INVOICE_NOT_FOUND. Para uma nota avulsa que falhou ou foi recusada, emita uma nova nota com POST Emitir Nota Fiscal em vez de usar Reemitir.

Operações disponíveis

Notas Fiscais

Método	Operação	Descrição
`GET`	Listar Notas Fiscais	Lista as notas da conta, mais recente primeiro, com filtros e paginação por cursor.
`GET`	Consultar Nota Fiscal	Retorna uma nota específica, com links de PDF, XML e código de verificação.
`POST`	Emitir Nota Fiscal	Emite uma nota avulsa, sem vínculo com cobrança ou assinatura.
`DELETE`	Cancelar Nota Fiscal	Cancela na prefeitura uma nota já autorizada.
`POST`	Reemitir Nota Fiscal	Gera uma nova nota para uma emissão que falhou na prefeitura.
`POST`	Reenviar Nota por E-mail	Reenvia por e-mail uma nota já autorizada, para até 10 destinatários.

Configuração Fiscal

Método	Operação	Descrição
`GET`	Listar Configurações Fiscais	Lista as configurações fiscais (empresas emissoras) da conta.
`GET`	Consultar Configuração Fiscal	Retorna uma configuração fiscal pelo id.
`POST`	Criar Configuração Fiscal	Cadastra a empresa emissora, a tributação e o certificado digital.
`PUT`	Atualizar Configuração Fiscal	Altera os campos enviados; os demais são preservados.
`DELETE`	Excluir Configuração Fiscal	Remove a configuração da ValidaPay. Não afeta o cadastro na prefeitura nem notas já emitidas.

Erros comuns

code	Status	Quando acontece
`MISSING_FIELDS`	400	Emitir: faltou customer.document, amount, descricao ou configId. Cancelar: faltou motivo (vai na query string, não no corpo).
`NOTA_TYPE_NOT_SUPPORTED`	400	Emitir: type diferente de NFSE, o único modelo aceito hoje.
`NOTA_CONFIG_NOT_FOUND`	400 / 404	Emitir (400): configId não existe ou está desabilitado. Consultar, Atualizar e Excluir Configuração (404): o id de configuração não existe.
`NF_EMISSION_FAILED`	400	Emitir: falha genérica na emissão (prefeitura recusou, município indisponível etc.).
`NOTA_NOT_FOUND`	404	Consultar e Cancelar: o notaId não existe ou não pertence à conta autenticada.
`NF_NOT_AUTHORIZED`	400	Cancelar: a nota não está autorizada para cancelamento (inclui o caso de já estar cancelada).
`NF_CANCEL_FAILED`	400	Cancelar: a prefeitura não confirmou o cancelamento.
`NOTA_ALREADY_ISSUED`	400	Reemitir: a nota já está autorizada, portanto não pode ser reemitida.
`NOTA_REISSUE_FAILED`	400	Reemitir: a nova tentativa de emissão também falhou.
`INVOICE_NOT_FOUND`	404	Reemitir: a nota não está vinculada a uma cobrança ou fatura real. É sempre o caso de uma nota avulsa.
`NOTA_NOT_ISSUED`	400	Reenviar: a nota ainda não foi autorizada.
`EMAILS_REQUIRED`	400	Reenviar: nenhum e-mail informado em emails.
`TOO_MANY_EMAILS`	400	Reenviar: mais de 10 e-mails no mesmo pedido.
`NOTA_RESEND_FAILED`	400	Reenviar: falha ao reenviar pelo provedor.
`NF_CONFIG_SYNC_FAILED`	400	Criar e Atualizar Configuração: falha ao sincronizar prestador ou certificado com a prefeitura. Na criação, nada é gravado quando isso acontece.
`NO_FIELDS_TO_UPDATE`	400	Atualizar Configuração: corpo enviado sem nenhum campo.

Perguntas frequentes

Preciso ter uma configuração fiscal antes de emitir uma nota?▾

Sim. configId é obrigatório em Emitir Nota Fiscal e precisa apontar para uma configuração existente e habilitada (enabled: true). Sem isso, a API recusa com NOTA_CONFIG_NOT_FOUND.

Uma conta pode ter mais de uma configuração fiscal?▾

Sim. É possível cadastrar configurações de mais de uma empresa (CNPJ) na mesma conta. O configId escolhido na emissão define de qual empresa a nota sai, e cada nota devolvida por Listar ou Consultar traz um objeto emissor (configId, cnpj, nome) indicando qual configuração a emitiu.

Qual a diferença entre consultar a nota de novo e usar Reemitir?▾

Consultar (GET) só lê o status atual, sem alterar nada. Reemitir (POST) gera uma nota nova quando a anterior não foi autorizada: a antiga fica REPLACED e a nova ocupa o lugar dela. Reemitir só funciona quando a nota está vinculada a uma cobrança ou fatura real; uma nota avulsa que falhou precisa ser emitida de novo com POST Emitir Nota Fiscal.

Cancelar uma nota é definitivo, ou tem prazo?▾

O cancelamento é enviado à prefeitura do município emissor, que aplica seu próprio prazo. Dentro do prazo, DELETE Cancelar Nota Fiscal funciona normalmente. Fora dele, a prefeitura recusa e o erro chega como NF_CANCEL_FAILED; nesse ponto a correção passa a exigir substituir a nota, não mais cancelar.

O campo type precisa ser enviado em toda emissão?▾

Não. Quando omitido, assume NFSE, o único modelo suportado hoje. Enviar qualquer outro valor retorna 400 com NOTA_TYPE_NOT_SUPPORTED.

Excluir uma configuração fiscal cancela as notas já emitidas por ela?▾

Não. DELETE Excluir Configuração Fiscal remove o cadastro apenas da ValidaPay; a empresa continua registrada na prefeitura e as notas já emitidas por aquela configuração não são alteradas.

Próximos passos

Criar Configuração Fiscal Emitir Nota Fiscal Listar Notas Fiscais Webhooks: eventos disponíveis

Essa página foi útil?