Guia completo da NFS-e Municipal

A NFS-e Municipal utiliza o padrão do município ou provedor informado. Ela não usa o XML, as rotas nem o fluxo da NFS-e Nacional.

Use este guia para emitir, consultar, cancelar ou substituir uma NFS-e Municipal. Em todas as operações, a API identifica o padrão de integração pelo código IBGE do município emissor.

Escolha a operação

Todas as rotas recebem o XML nativo do padrão municipal no corpo da requisição. Os campos, elementos obrigatórios, regras e prazos variam conforme o município ou o provedor.

Pré-requisitos

Antes de iniciar, confirme que você possui:

• Token de acesso válido;
• Certificado digital A1 cadastrado para o CPF ou CNPJ do emitente;
• Código IBGE de sete dígitos do município emissor;
• XML de NFS-e conforme o layout e a versão do município ou provedor;
• Ambiente definido corretamente: homologação ou produção.

Confirme se o município, padrão e versão do layout estão disponíveis na lista de municípios desenvolvidos. Valide toda a integração em homologação antes de usar produção.

Entenda a rota de autorização

Para emitir uma NFS-e Municipal, utilize:

POST /api/v1/{CPF_CNPJ}/NFSe/Autorizar/{codigoMunicipio}?tpAmb={tpAmb}

Substitua:

• {CPF_CNPJ} pelo CPF ou CNPJ do emitente;
• {codigoMunicipio} pelo código IBGE do município emissor;
• {tpAmb} por 2 para homologação ou 1 para produção.

Exemplo para um emitente de São Paulo/SP:

POST /api/v1/12345678000199/NFSe/Autorizar/3550308?tpAmb=2

Etapa 1: monte o XML da NFS-e

Crie o XML conforme o layout oficial do município ou do provedor de NFS-e utilizado por ele.

Envie somente o XML de negócio exigido pelo padrão municipal. A API identifica o padrão pelo código IBGE, utiliza o certificado do emitente e processa as estruturas técnicas de comunicação necessárias.

Não envie um XML de DPS ou de NFS-e Nacional nesta rota.

Etapa 2: envie o pedido de autorização

Envie uma requisição POST para a rota correspondente, com:

• Header Authorization: Bearer {seu_token};
• Corpo da requisição contendo o XML municipal;
• Content-Type compatível com XML.

Exemplo conceitual:

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

<GerarNfseEnvio>...</GerarNfseEnvio>

Use como corpo o XML do padrão correto; GerarNfseEnvio é apenas um exemplo de estrutura e não é comum a todos os municípios.

Etapa 3: valide o retorno

A resposta contém o retorno original do webservice municipal. Verifique principalmente:

• O status e a mensagem de processamento;
• O número da NFS-e e o protocolo, quando a emissão for autorizada;
• O recibo ou lote, quando o provedor processar a emissão de forma assíncrona;
• As rejeições, quando houver inconsistências no XML ou nas regras municipais.

Armazene o XML de retorno junto ao documento emitido. Um HTTP 200 indica que a API devolveu a resposta do fluxo, mas a autorização deve ser confirmada pelos dados retornados pelo município ou provedor.

Erros comuns

• Município não atendido ou código IBGE incorreto: confirme se o município está implementado e se o código informado é o do emitente.
• Layout XML incompatível: valide o padrão e a versão exigidos pelo município ou provedor.
• Certificado não encontrado ou inválido: confirme se há um certificado A1 válido associado ao mesmo CPF ou CNPJ da rota.
• Rejeição do provedor: revise o XML, o ambiente e as regras municipais aplicáveis.
• Recibo ou lote pendente: consulte a emissão usando o XML de consulta do mesmo padrão municipal antes de reenviar a NFS-e.

Consultar uma NFS-e Municipal

Use a consulta para confirmar uma emissão, acompanhar um recibo ou lote pendente, ou recuperar a situação atual da NFS-e.

POST /api/v1/{CPF_CNPJ}/NFSe/Consultar/{codigoMunicipio}?tpAmb={tpAmb}

Envie no corpo o XML de consulta exigido pelo padrão municipal. Alguns provedores permitem consultar por número da NFS-e, RPS, recibo, lote ou período; utilize a estrutura prevista para o município.

Não reenvie uma emissão cujo retorno não foi recebido antes de realizar a consulta. Isso reduz o risco de duplicidade.

Cancelar uma NFS-e Municipal

Use o cancelamento somente para uma NFS-e já emitida, respeitando as regras e os prazos do município ou provedor.

POST /api/v1/{CPF_CNPJ}/NFSe/Cancelar/{codigoMunicipio}?tpAmb={tpAmb}

Envie o XML nativo de cancelamento. Ele normalmente identifica a NFS-e e inclui a justificativa quando o padrão municipal exigir.

Valide no retorno se o cancelamento foi efetivado. Um HTTP 200 apenas indica que a API recebeu e devolveu a resposta do provedor; a situação fiscal deve ser confirmada no XML retornado.

Substituir uma NFS-e Municipal

Use a substituição quando o município ou provedor oferecer esse recurso e a regra fiscal aplicável exigir uma nova NFS-e em lugar da original.

POST /api/v1/{CPF_CNPJ}/NFSe/Substituir/{codigoMunicipio}?tpAmb={tpAmb}

Envie o XML nativo de substituição, contendo as referências à NFS-e original e os dados da nova NFS-e conforme o layout municipal.

Nem todos os municípios disponibilizam substituição. Confirme a disponibilidade e o layout para o código IBGE informado antes de usar essa operação em produção.

Valide os retornos de todas as operações

As quatro operações retornam a resposta original do webservice municipal. Após qualquer chamada, verifique:

• O status e a mensagem retornados pelo município ou provedor;
• O número, protocolo, recibo ou lote, quando aplicável;
• Se o processamento é imediato ou assíncrono;
• As rejeições e campos apontados para correção.

Armazene o XML de retorno junto ao XML enviado. Esses arquivos são importantes para consulta posterior, auditoria e suporte.

Limites deste módulo

As operações municipais dependem do padrão implementado para o município. Este módulo não possui uma rota única de status do serviço ou de download de DANFE municipal.