API.UniNFemd

Guia geral da NFS-e Nacional

Visão geral das operações da NFS-e Nacional pela API, incluindo emissão via DPS, consultas, distribuição por NSU, DANFE e eventos posteriores.

#NFS-e Nacional#DPS#consulta#distribuição NSU#DANFE#eventos#XML#API

Guia geral da NFS-e Nacional

A NFS-e Nacional possui fluxo próprio: o prestador envia um DPS (Declaração de Prestação de Serviço) e a plataforma nacional gera a NFS-e. Ela não utiliza os layouts nem as rotas da NFS-e Municipal.

Pré-requisitos

Para utilizar as operações, tenha:

Token de acesso válido;
Certificado digital A1 cadastrado para o CPF ou CNPJ do emitente;
DPS, XML de evento ou XML de distribuição conforme o layout oficial aplicável;
Ambiente correto: homologação ou produção.

Use tpAmb=2 para homologação e tpAmb=1 para produção nas operações que exigem o parâmetro.

Operações disponíveis

Necessidade	Método e rota	Informações necessárias
Emitir NFS-e	`POST /api/v1/{CPF_CNPJ}/NFSeNacional/Autorizar`	XML do DPS.
Emitir e receber DANFE	`POST /api/v1/{CPF_CNPJ}/NFSeNacional/AutorizarNFSeComDanfe`	XML do DPS.
Consultar NFS-e	`GET /api/v1/{CPF_CNPJ}/NFSeNacional/Consultar/{chaveDFe}?tpAmb={tpAmb}`	Chave da NFS-e.
Consultar pelo DPS	`GET /api/v1/{CPF_CNPJ}/NFSeNacional/ConsultarDPS/{chaveDPS}?tpAmb={tpAmb}`	Chave do DPS original.
Distribuir documentos	`POST /api/v1/{CPF_CNPJ}/NFSeNacional/Distribuicao?tpAmb={tpAmb}`	XML de distribuição com NSU.
Baixar DANFE	`GET /api/v1/{CPF_CNPJ}/NFSeNacional/DANFE/{chaveDFe}`	Chave da NFS-e.
Enviar evento	`POST /api/v1/{CPF_CNPJ}/NFSeNacional/RecepcaoEvento?tpAmb={tpAmb}`	XML de evento.

Emitir uma NFS-e

Envie o DPS para a rota de autorização. A plataforma nacional valida o documento, gera a NFS-e e devolve o resultado.

POST /api/v1/12345678000199/NFSeNacional/Autorizar
Authorization: Bearer {seu_token}
Content-Type: application/xml

<DPS>...</DPS>

No retorno, armazene o XML recebido, a chave da NFS-e e os dados de autorização. A chave da NFS-e é diferente da chave do DPS.

Consulte o guia Como autorizar NFS-e Nacional para os detalhes da emissão.

Consultar uma NFS-e pela chave

Use a chave da NFS-e autorizada para recuperar a situação e o XML do documento.

GET /api/v1/12345678000199/NFSeNacional/Consultar/{chaveDFe}?tpAmb=2
Authorization: Bearer {seu_token}

Essa é a consulta recomendada quando a chave da NFS-e foi armazenada no momento da autorização.

Consultar uma NFS-e pela chave do DPS

Se a chave da NFS-e não foi armazenada, consulte pelo DPS que originou a emissão.

GET /api/v1/12345678000199/NFSeNacional/ConsultarDPS/{chaveDPS}?tpAmb=2
Authorization: Bearer {seu_token}

O retorno permite localizar a NFS-e associada ao DPS informado.

Consultar distribuição por NSU

Use a distribuição para recuperar NFS-e disponibilizadas ao contribuinte a partir de um Número Sequencial Único (NSU).

POST /api/v1/12345678000199/NFSeNacional/Distribuicao?tpAmb=2
Authorization: Bearer {seu_token}
Content-Type: application/xml

Envie no corpo o XML distribuicaoNFSe com o NSU e os demais campos exigidos pelo layout. Para o fluxo e exemplo completos.

Obter o DANFE

Após a autorização, baixe o PDF do DANFE usando a chave da NFS-e:

GET /api/v1/12345678000199/NFSeNacional/DANFE/{chaveDFe}
Authorization: Bearer {seu_token}

Se precisar do DANFE no momento da emissão, use a rota AutorizarNFSeComDanfe.

Enviar eventos

Use a recepção de eventos para operações posteriores, como cancelamento, quando aplicável.

POST /api/v1/12345678000199/NFSeNacional/RecepcaoEvento?tpAmb=2
Authorization: Bearer {seu_token}
Content-Type: application/xml

<Evento>...</Evento>

O XML do evento e os prazos aplicáveis devem seguir o padrão nacional e a legislação vigente.

Erros comuns

Credenciais inválidas: confira o token de acesso; uma resposta 401 com Invalid client ou Invalid client credentials indica falha de autenticação.
Certificado não encontrado ou inválido: confirme o certificado A1 associado ao CPF ou CNPJ da rota.
DPS ou evento incompatível: revise o XML, a versão do layout e o ambiente informado.
Chave não encontrada: confirme se foi informada a chave correta da NFS-e ou do DPS e se o ambiente corresponde ao da emissão.
Rejeição da plataforma nacional: valide os campos obrigatórios e as regras fiscais antes de reenviar o documento.