Documentação API NFS-e

A API NFS-e da Centi permite que empresas emitam notas fiscais de serviço diretamente de seus sistemas próprios através de integração via API REST.

Pré-requisitos

• Credenciais de acesso: Usuário e senha fornecidos pela prefeitura municipal
• Certificado Digital: Certificado A1 ou A3 válido para assinatura dos XMLs
• Cadastro ativo: Empresa cadastrada e habilitada no sistema da prefeitura
• Conhecimento técnico: Familiaridade com APIs REST e formato XML

Quick Start - 3 Passos

A API NFS-e utiliza autenticação via HTTP Basic Auth. Você deve incluir suas credenciais (usuário e senha) codificadas em Base64 no header Authorization.

Formato do Header

Authorization: Basic {base64(usuario:senha)}

Exemplo

Credenciais:

Usuário: "empresa123"
Senha: "senhaSegura@2025"

Codificação Base64:

echo -n "empresa123:senhaSegura@2025" | base64
# Resultado: ZW1wcmVzYTEyMzpzZW5oYVNlZ3VyYUAyMDI1

Header Final:

Authorization: Basic ZW1wcmVzYTEyMzpzZW5oYVNlZ3VyYUAyMDI1

URL Base

https://api.centi.com.br

Por padrão, todas as requisições precisam informar a sigla UF do prestador do serviço e o identificador do prestador (nome da cidade) representado pela variável Tenant.

Formato das URLs

https://api.centi.com.br/{recurso}/{UF}/{Tenant}

Exemplo:

https://api.centi.com.br/nfe/gerar/go/rioverde

Parâmetro	Descrição	Exemplo
{UF}	Sigla da UF em minúsculo	go, sp, rj
{Tenant}	Nome do município	rioverde, goiania

Endpoint

POST https://api.centi.com.br/nfe/gerar/{UF}/{Tenant}

Request Completo

POST https://api.centi.com.br/nfe/gerar/go/rioverde

Headers:
  Content-Type: application/xml; charset=utf-8
  Authorization: Basic {suas_credenciais_base64}

Body:
  <GerarNfseEnvio xmlns="http://www.centi.com.br/files/nfse.xsd">
    <!-- XML da NFS-e -->
  </GerarNfseEnvio>

Response de Sucesso (HTTP 200)

Quando a nota é emitida com sucesso, a API retorna um XML contendo:

• Número da NFS-e gerada
• Código de verificação
• Data e hora da emissão
• XML completo da nota autorizada

Erros Comuns

Código	Erro	Solução
401	Credenciais inválidas	Verifique usuário e senha
400	XML mal formatado	Valide o XML contra o XSD
422	Dados inválidos	Verifique CNPJ/CPF, códigos
500	Erro no servidor	Tente novamente ou contate suporte

Endpoint

POST https://api.centi.com.br/nfe/cancelar/{UF}/{Tenant}

Estrutura do XML de Cancelamento

<CancelarNfseEnvio xmlns="http://www.centi.com.br/files/nfse.xsd">
  <Pedido>
    <InfPedidoCancelamento>
      <IdentificacaoNfse>
        <Numero>123456</Numero>
        <CpfCnpj>
          <Cnpj>12345678000195</Cnpj>
        </CpfCnpj>
        <InscricaoMunicipal>12345</InscricaoMunicipal>
        <CodigoMunicipio>5218805</CodigoMunicipio>
        <CodigoVerificacao>ABCD1234</CodigoVerificacao>
        <DescricaoCancelamento>Motivo do cancelamento</DescricaoCancelamento>
      </IdentificacaoNfse>
      <CodigoCancelamento>1</CodigoCancelamento>
    </InfPedidoCancelamento>
    <Signature><!-- Assinatura Digital --></Signature>
  </Pedido>
</CancelarNfseEnvio>

Código de Cancelamento

Código	Descrição
1	Rasura
2	Erro preenchimento
3	Fim do prazo de validade
4	Fora de sequência numérica e cronológica
5	Desacordo comercial
6	Outros

Endpoint

POST https://api.centi.com.br/nfe/gerar/{UF}/{Tenant}

A substituição utiliza o mesmo endpoint de geração, mas com informações adicionais sobre qual nota está sendo substituída.

Bloco RpsSubstituido

<Rps>
  <IdentificacaoRps>
    <Numero>2</Numero>
    <Serie>A1</Serie>
    <Tipo>1</Tipo>
  </IdentificacaoRps>
  <DataEmissao>2025-12-16</DataEmissao>
  <Status>1</Status>
  
  <!-- Bloco de Substituição -->
  <RpsSubstituido>
    <Numero>1</Numero>
    <Serie>A1</Serie>
    <Tipo>1</Tipo>
  </RpsSubstituido>
</Rps>

Campo	Tipo	Obrigatório	Descrição
Numero	Numérico	SIM	Número do RPS
Serie	Texto	SIM	Série do RPS
DataEmissao	Data	SIM	Data emissão (YYYY-MM-DD)
ValorServicos	Decimal	SIM	Valor total dos serviços
ValorIss	Decimal	SIM	Valor do ISS
Aliquota	Decimal	SIM	Alíquota do ISS (%)
ItemListaServico	Texto	SIM	Código serviço LC 116/2003
CodigoCnae	Numérico	SIM	Código CNAE
Discriminacao	Texto	SIM	Descrição do serviço
IssRetido	Numérico	SIM	1=Sim, 2=Não

ISS Retido

Código	Significado
1	Sim - ISS retido pelo tomador
2	Não - ISS recolhido pelo prestador

Códigos de Serviço (Principais)

Código	Descrição
01.07	Desenvolvimento de programas
04.01	Medicina e biomedicina
07.01	Engenharia, arquitetura
16.02	Transporte municipal
17.01	Assessoria ou consultoria

Schema XSD

• http://app.centi.com.br/files/nfse.xsd
• http://app.centi.com.br/files/xmldsig-core-schema20020212.xsd

Tenha acesso a documentação interativa no padrão OpenAPI.

Baixe os exemplos completos de XML:

• Modelo_XML_Gerar_NFSe (XML)
• Modelo_XML_Cancelar_NFSe (XML)
• Modelo_XML_Substituir_NFSe (XML)
• Modelo_XML_Retorno_NFSe (XML)