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>

Classificação do Serviço: NBS, INDOP e Classificação Tributária

No XML de emissão, as tags <CodigoNbs>, <CodigoINDOP> e <CodigoClassTrib> devem ser enviadas dentro do grupo <Servico>, respeitando a sequência abaixo:

<Servico>
  <Valores>
    <!-- valores do serviço -->
  </Valores>
  <IssRetido>2</IssRetido>
  <ItemListaServico>01.07</ItemListaServico>
  <CodigoNbs>1.2345.67.89</CodigoNbs>
  <CodigoINDOP>010101</CodigoINDOP>
  <CodigoClassTrib>000001</CodigoClassTrib>
  <CodigoCnae>6201501</CodigoCnae>
  <!-- demais campos do serviço -->
</Servico>

Retenções Federais e Detalhamento PIS/COFINS (NT 007)

O grupo <Valores> passou a aceitar sete novas tags de detalhamento federal. Elas são opcionais no XSD, mas devem respeitar obrigatoriamente a sequência abaixo, sempre após <DescontoCondicionado>:

<Valores>
  <ValorServicos>1000.00</ValorServicos>
  <ValorDeducoes>0.00</ValorDeducoes>
  <ValorPis>0.00</ValorPis>
  <ValorCofins>0.00</ValorCofins>
  <ValorInss>0.00</ValorInss>
  <ValorIr>0.00</ValorIr>
  <ValorCsll>0.00</ValorCsll>
  <OutrasRetencoes>0.00</OutrasRetencoes>
  <ValorIss>50.00</ValorIss>
  <Aliquota>5</Aliquota>
  <DescontoIncondicionado>0.00</DescontoIncondicionado>
  <DescontoCondicionado>0.00</DescontoCondicionado>

  <!-- Detalhamento Federal (NT 007) -->
  <CstPisCofins>01</CstPisCofins>
  <TpRetPisCofins>1</TpRetPisCofins>
  <VlBcPisCofins>0.00</VlBcPisCofins>
  <PAliqPis>0.00</PAliqPis>
  <PAliqCofins>0.00</PAliqCofins>
  <VlRetCSLL>0.00</VlRetCSLL>
  <VlINSS>0.00</VlINSS>
</Valores>

Tag	Tipo	Descrição
CstPisCofins	Texto	Código de Situação Tributária de PIS/COFINS, conforme tabela da NT 007
TpRetPisCofins	Numérico	Tipo de retenção de PIS/COFINS, conforme tabela da NT 007
VlBcPisCofins	Decimal	Valor da base de cálculo de PIS/COFINS
PAliqPis	Decimal	Alíquota de PIS aplicada (percentual)
PAliqCofins	Decimal	Alíquota de COFINS aplicada (percentual)
VlRetCSLL	Decimal	Valor de CSLL retido
VlINSS	Decimal	Contribuição Previdenciária retida

Blocos opcionais: CondicaoPagamento, DadosObra e DadosImovel

Estes três grupos ficam no final de <InfDeclaracaoPrestacaoServico>, após <IncentivoFiscal> e nesta ordem:

  <RegimeEspecialTributacao>1</RegimeEspecialTributacao>
  <OptanteSimplesNacional>2</OptanteSimplesNacional>
  <IncentivoFiscal>2</IncentivoFiscal>

  <!-- Condições de pagamento -->
  <CondicaoPagamento>
    <Condicao>1</Condicao>
    <QuantidadeParcela>3</QuantidadeParcela>
    <Observacao>Pagamento em 3 parcelas mensais</Observacao>
    <Parcela>
      <Parcela>1</Parcela>
      <Valor>333.34</Valor>
    </Parcela>
  </CondicaoPagamento>

  <!-- Dados da obra (construção civil) -->
  <DadosObra>
    <CnoObra>123456789012</CnoObra>
    <CepObra>74000000</CepObra>
    <LogradouroObra>AVENIDA ANHANGUERA</LogradouroObra>
    <NumeroObra>123</NumeroObra>
    <BairroObra>CENTRO</BairroObra>
    <ComplementoObra>QUADRA 5</ComplementoObra>
    <QuadraObra>5</QuadraObra>
    <LoteObra>12</LoteObra>
  </DadosObra>

  <!-- Dados do imóvel -->
  <DadosImovel>
    <CibImovel>987654321</CibImovel>
    <CepImovel>74000000</CepImovel>
    <LogradouroImovel>AVENIDA ANHANGUERA</LogradouroImovel>
    <NumeroImovel>123</NumeroImovel>
    <BairroImovel>CENTRO</BairroImovel>
  </DadosImovel>
</InfDeclaracaoPrestacaoServico>

Retenções e Detalhamento Federal (NT 007)

O grupo <Valores> passou a aceitar sete novos campos de detalhamento federal. Eles são opcionais no XSD, porém devem obrigatoriamente ser enviados após <DescontoCondicionado>, respeitando a sequência abaixo:

<Valores>
  <ValorServicos>1000.00</ValorServicos>
  <ValorDeducoes>0.00</ValorDeducoes>
  <ValorPis>0.00</ValorPis>
  <ValorCofins>0.00</ValorCofins>
  <ValorInss>0.00</ValorInss>
  <ValorIr>0.00</ValorIr>
  <ValorCsll>0.00</ValorCsll>
  <OutrasRetencoes>0.00</OutrasRetencoes>
  <ValorIss>50.00</ValorIss>
  <Aliquota>5</Aliquota>
  <DescontoIncondicionado>0.00</DescontoIncondicionado>
  <DescontoCondicionado>0.00</DescontoCondicionado>

  <!-- Detalhamento Federal (NT 007) -->
  <CstPisCofins>01</CstPisCofins>
  <TpRetPisCofins>1</TpRetPisCofins>
  <VlBcPisCofins>1000.00</VlBcPisCofins>
  <PAliqPis>0.65</PAliqPis>
  <PAliqCofins>3.00</PAliqCofins>
  <VlRetCSLL>0.00</VlRetCSLL>
  <VlINSS>0.00</VlINSS>
</Valores>

Tag	Tipo	Descrição
CstPisCofins	Texto	Código de Situação Tributária de PIS/COFINS, conforme tabela da NT 007
TpRetPisCofins	Numérico	Tipo de retenção de PIS/COFINS, conforme tabela da NT 007
VlBcPisCofins	Decimal	Valor da base de cálculo de PIS/COFINS
PAliqPis	Decimal	Alíquota de PIS (%)
PAliqCofins	Decimal	Alíquota de COFINS (%)
VlRetCSLL	Decimal	Valor retido de CSLL
VlINSS	Decimal	Contribuição Previdenciária Retida

Blocos opcionais: CondicaoPagamento, DadosObra e DadosImovel

Três blocos opcionais foram disponibilizados no final de <InfDeclaracaoPrestacaoServico>, obrigatoriamente após <IncentivoFiscal> e nesta ordem:

  <RegimeEspecialTributacao>1</RegimeEspecialTributacao>
  <OptanteSimplesNacional>2</OptanteSimplesNacional>
  <IncentivoFiscal>2</IncentivoFiscal>

  <!-- 1. Condições de pagamento -->
  <CondicaoPagamento>
    <Condicao>1</Condicao>
    <QuantidadeParcela>3</QuantidadeParcela>
    <Observacao>Pagamento em 3 parcelas mensais</Observacao>
    <Parcela>
      <Parcela>1</Parcela>
      <Valor>333.34</Valor>
    </Parcela>
    <Parcela>
      <Parcela>2</Parcela>
      <Valor>333.33</Valor>
    </Parcela>
  </CondicaoPagamento>

  <!-- 2. Dados da obra (construção civil) -->
  <DadosObra>
    <CnoObra>123456789012</CnoObra>
    <CepObra>74000000</CepObra>
    <LogradouroObra>AVENIDA ANHANGUERA</LogradouroObra>
    <NumeroObra>123</NumeroObra>
    <BairroObra>CENTRO</BairroObra>
    <ComplementoObra>QUADRA 10</ComplementoObra>
    <QuadraObra>10</QuadraObra>
    <LoteObra>5</LoteObra>
  </DadosObra>

  <!-- 3. Dados do imóvel -->
  <DadosImovel>
    <CibImovel>987654321</CibImovel>
    <CepImovel>74000000</CepImovel>
    <LogradouroImovel>AVENIDA ANHANGUERA</LogradouroImovel>
    <NumeroImovel>123</NumeroImovel>
    <BairroImovel>CENTRO</BairroImovel>
  </DadosImovel>
</InfDeclaracaoPrestacaoServico>

Validações realizadas pelo sistema

• NBS x Serviço: o <CodigoNbs> deve estar associado ao serviço informado em <ItemListaServico>, conforme o cadastro AR017.
• INDOP x NBS: o <CodigoINDOP> deve possuir exatamente 6 dígitos numéricos, sem pontos, e corresponder ao INDOP vinculado ao NBS.
• Classificação Tributária x NBS: o <CodigoClassTrib> deve possuir exatamente 6 dígitos numéricos e corresponder à classificação vinculada ao NBS.
• Persistência: após a validação, o identificador interno do NBS é gravado na nota fiscal gerada.

Exemplos de rejeição

• Código NBS inválido para o serviço informado.
• Código INDOP inválido para o NBS informado.
• Classificação Tributária inválida para o NBS informado.

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
• Bloco <DadosNotaNacional> com os dados da Reforma Tributária

O grupo <InfNfse> do retorno passou a incluir os campos <DescricaoCancelamento>, <DescricaoSubstituicao>, <Discriminacao>, <Observacao> e o bloco <DadosNotaNacional>:

<DadosNotaNacional>
  <AliqotaIBS>0</AliqotaIBS>
  <AliquotaCBS>0</AliquotaCBS>
  <ValorIBS>0</ValorIBS>
  <ValorCBS>0</ValorCBS>
  <ChaveAcessoNacional>...</ChaveAcessoNacional>
</DadosNotaNacional>

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 ou vínculo fiscal inconsistente	Verifique CNPJ/CPF, NBS, INDOP, Classificação Tributária e o vínculo com o serviço
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>
        <Id>nfse_guid_123456789012345678901234567890</Id>
      </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
CodigoNbs	Texto	REGRA DE NEGÓCIO	Código NBS vinculado ao serviço cadastrado na AR017
CodigoINDOP	Numérico (6 dígitos)	REGRA DE NEGÓCIO	Indicador da operação, sem pontos, vinculado ao NBS informado; minOccurs="0" no XSD
CodigoClassTrib	Numérico (6 dígitos)	REGRA DE NEGÓCIO	Classificação Tributária vinculada ao NBS informado; minOccurs="0" no XSD
CodigoCnae	Numérico	SIM	Código CNAE
Discriminacao	Texto	SIM	Descrição do serviço
IssRetido	Numérico	SIM	1=Sim, 2=Não
CstPisCofins	Texto	NÃO	CST de PIS/COFINS (NT 007) — dentro de <Valores>
TpRetPisCofins	Numérico	NÃO	Tipo de retenção de PIS/COFINS (NT 007)
VlBcPisCofins	Decimal	NÃO	Base de cálculo de PIS/COFINS
PAliqPis / PAliqCofins	Decimal	NÃO	Alíquotas de PIS e COFINS aplicadas
VlRetCSLL	Decimal	NÃO	Valor de CSLL retido
VlINSS	Decimal	NÃO	Contribuição Previdenciária retida
Condicao	Numérico	NÃO	Condição de pagamento; obrigatório se <CondicaoPagamento> for enviado
QuantidadeParcela	Numérico	NÃO	Quantidade de parcelas; obrigatório dentro de <CondicaoPagamento>
CnoObra	Texto	NÃO	CNO da obra, em <DadosObra> (PascalCase)
CibImovel	Texto	NÃO	Código CIB do imóvel, em <DadosImovel>

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

Detalhamento Federal (NT 007)

Campo	Formato	Origem do domínio
CstPisCofins	Texto (código numérico com zeros à esquerda, ex.: 01)	Tabela de CST de PIS/COFINS da NT 007
TpRetPisCofins	Numérico inteiro	Tabela de tipos de retenção de PIS/COFINS da NT 007
Condicao	Numérico inteiro (até 5 dígitos)	Condição de pagamento, conforme domínio da NT 007

NBS, INDOP e Classificação Tributária

Campo	Formato	Validação aplicada
CodigoNbs	Código textual conforme cadastro NBS	Deve existir e estar vinculado ao ItemListaServico informado
CodigoINDOP	6 dígitos numéricos, sem pontuação	Deve coincidir exatamente com o INDOP cadastrado para o NBS
CodigoClassTrib	6 dígitos numéricos	Deve coincidir exatamente com a Classificação Tributária cadastrada para o NBS

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)

Schemas XSD

Arquivos de schema para validação estrutural dos XMLs:

• NFSe.xsd

Verifique a estrutura do seu XML, os formatos de NBS/INDOP/Classificação Tributária e a configuração da requisição antes de enviar à API. O processamento é 100% local; vínculos cadastrais são confirmados somente pelo provider da Centi.