Como autorizar 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.

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.

Próximos passos

Após a emissão, utilize as operações específicas do município para consultar, cancelar ou substituir a NFS-e, quando o padrão oferecer suporte a elas.