Documentação API NFS-e

Guia completo para integração com o sistema de Nota Fiscal de Serviços Eletrônica da Centi

Começando

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 ICP-Brasil A1 ou A3, dentro da validade, do próprio prestador (CNPJ da matriz ou da filial) ou de sócio ativo, 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

1
Obter Credenciais

Entre em contato com a prefeitura do município para obter seu usuário e senha de acesso à API. É a mesma senha de acesso ao portal para emissão manual.

2
Preparar o XML

Monte o XML da NFS-e conforme o schema XSD fornecido. Assine digitalmente o XML com seu certificado digital, incluindo o certificado em <KeyInfo><X509Data><X509Certificate>.

3
Enviar via POST

Faça uma requisição POST para o endpoint da API com Content-Type: application/json e um corpo JSON com os campos Usuario, Senha e Xml (o XML assinado, como texto).

Autenticação

A API NFS-e não utiliza header de autenticação (não há HTTP Basic Auth nem token). As credenciais (usuário e senha) seguem no corpo JSON da requisição, junto com o XML, nos campos Usuario, Senha e Xml — os três são obrigatórios em todas as rotas (emitir, cancelar, substituir e consultar).

Formato do corpo (JSON)

{
  "Usuario": "{usuario}",
  "Senha": "{senha}",
  "Xml": "{XML assinado, como texto}"
}

Exemplo

Credenciais:

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

Corpo da requisição:

{
  "Usuario": "empresa123",
  "Senha": "senhaSegura@2025",
  "Xml": "<?xml version=\"1.0\" encoding=\"utf-8\"?><GerarNfseEnvio xmlns=\"http://www.centi.com.br/files/nfse.xsd\">...</GerarNfseEnvio>"
}

Header obrigatório:

Content-Type: application/json

O XML vai dentro do campo Xml como uma string JSON comum: escape apenas as aspas (\") e as quebras de linha (\n), como qualquer serializador JSON faz. Não converta o XML em entidades HTML (&lt;, &gt;). Usuário ou senha inválidos não geram HTTP 401: a resposta é HTTP 200 com a recusa no XML de retorno (ex.: Usuário/senha inválidos.).

Estrutura da API

URL Base

https://api.centi.com.br

Por padrão, todas as requisições precisam informar a sigla da UF e o identificador do município em que o prestador está cadastrado, 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

Rotas disponíveis

Rota (POST) Raiz do XML Uso
/nfe/gerar GerarNfseEnvio Emissão da NFS-e
/nfe/substituir GerarNfseEnvio com <RpsSubstituido> Substituição de uma NFS-e já emitida
/nfe/cancelar CancelarNfseEnvio Cancelamento (ou solicitação de cancelamento) da NFS-e
/nfe/consultar/rps ConsultarNfseRpsEnvio Consulta da NFS-e gerada a partir do número do RPS
/nfe/gerar/homologacao
/nfe/substituir/homologacao		 GerarNfseEnvio Teste: executa as mesmas validações da emissão/substituição sem gravar a nota e devolve um retorno de teste (Numero 0000, CodigoVerificacao *TESTE*)

Todas as rotas são seguidas de /{UF}/{Tenant} e recebem o mesmo corpo JSON (Usuario, Senha e Xml) e devolvem o XML de retorno como texto. Limite de uso: até 15 requisições por segundo por IP (acima disso a resposta é HTTP 429).

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

Emitir Nota Fiscal

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/json

Body:
  {
    "Usuario": "{seu_usuario}",
    "Senha": "{sua_senha}",
    "Xml": "<?xml version=\"1.0\" encoding=\"utf-8\"?><GerarNfseEnvio xmlns=\"http://www.centi.com.br/files/nfse.xsd\"><Rps>...</Rps></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>

Obrigatoriedade por regra de negócio

No XSD, <CodigoNbs>, <CodigoINDOP> e <CodigoClassTrib> possuem minOccurs="0" para compatibilidade estrutural. Entretanto, no fluxo de emissão, a API exige as três tags quando o município está integrado ao Ambiente de Dados Nacional (ADN) — a partir de 03/08/2026 — ou quando a prefeitura parametrizou o NBS como obrigatório, e rejeita o RPS quando as informações estiverem ausentes, inválidas ou incompatíveis com o NBS informado. A única dispensa é o serviço de não incidência (item 99.01).

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

O grupo <Valores> passou a aceitar seis tags de detalhamento federal da NT 007. Elas são opcionais no XSD, mas devem respeitar obrigatoriamente a sequência abaixo, sempre após <DescontoCondicionado>, e com a grafia exata do schema (o XML diferencia maiúsculas de minúsculas): 

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

  <!-- Detalhamento Federal (NT 007) -->
  <CST>01</CST>
  <vBcPisCofins>1000.00</vBcPisCofins>
  <pAliqPis>0.65</pAliqPis>
  <pAliqCofins>3.00</pAliqCofins>
  <tpRetPisCofins>0</tpRetPisCofins>
</Valores>
TagTipoDescrição
CSTTexto (2 dígitos)Código de Situação Tributária de PIS/COFINS, conforme tabela da NT 007; obrigatório quando o grupo PIS/COFINS é informado
vBcPisCofinsDecimalBase de cálculo do débito próprio de PIS/COFINS; quando informada, o servidor recalcula ValorPis e ValorCofins
pAliqPisDecimalAlíquota de PIS aplicada (percentual, ex.: 0.65)
pAliqCofinsDecimalAlíquota de COFINS aplicada (percentual, ex.: 3.00)
tpRetPisCofinsNuméricoTipo de retenção de PIS/COFINS/CSLL, conforme tabela da NT 007 (ausente = 0, não retidos)
vRetCSLLDecimalSoma dos valores retidos de PIS, COFINS e CSLL

Pela NT 007, <ValorPis> e <ValorCofins> passam a representar o débito de apuração própria do prestador e não abatem o valor líquido. A retenção de INSS continua em <ValorInss> e a de IR em <ValorIr>; não existe tag <VlINSS>.

<Aliquota> passou a ser obrigatória no XSD

No schema atual, <Aliquota> deixou de ser opcional (minOccurs="0") e passou a minOccurs="1" dentro de <Valores>. XMLs sem essa tag falham na validação estrutural.

Blocos opcionais: CondicaoPagamento, DadosObra e DadosImovel

<DadosObra> e <DadosImovel> ficam dentro de <Prestador>, antes de <RazaoSocial>/<InscricaoMunicipal>. <CondicaoPagamento> fica no final de <InfDeclaracaoPrestacaoServico>, após <IncentivoFiscal>: 

  <Prestador>
    <CpfCnpj><Cnpj>12345678000195</Cnpj></CpfCnpj>

    <!-- 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>
      <CodigoMunicipioObra>5208707</CodigoMunicipioObra>
      <UfObra>GO</UfObra>
    </DadosObra>

    <!-- Dados do imóvel -->
    <DadosImovel>
      <Cib>987654321</Cib>
      <Cep>74000000</Cep>
      <Logradouro>AVENIDA ANHANGUERA</Logradouro>
      <Numero>123</Numero>
      <Bairro>CENTRO</Bairro>
    </DadosImovel>

    <InscricaoMunicipal>123456</InscricaoMunicipal>
  </Prestador>
  ...
  <IncentivoFiscal>2</IncentivoFiscal>

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

Onde enviar o <DadosObra>

Envie <DadosObra> somente dentro de <Prestador>: é a única posição lida pela API. Enviado diretamente em <InfDeclaracaoPrestacaoServico>, o grupo é ignorado e a nota sai sem os dados da obra. As tags usam PascalCase: <CnoObra>, <CepObra>, <LogradouroObra>, <NumeroObra>, <BairroObra>, <ComplementoObra>, <QuadraObra>, <LoteObra>, <CodigoMunicipioObra> (código IBGE do município da obra) e <UfObra> (opcional, apenas conferência — divergente do município, a nota é recusada). Os nomes com sufixo Fild (<cepObraFild> etc.) não são reconhecidos: são descartados sem aviso. Nos serviços de obra, informe o CNO ou o endereço completo da obra e o município da obra. <DadosImovel> também é aceito no final de <InfDeclaracaoPrestacaoServico> (se vier nas duas posições, prevalece o de <Prestador>) e é exigido — CIB ou CEP, Logradouro, Número e Bairro — quando o INDOP informado é de operação com imóvel.

Retenções e Detalhamento Federal (NT 007)

Quando há retenção de PIS, COFINS ou CSLL, informe o tipo de retenção em <tpRetPisCofins> e a soma dos valores retidos em <vRetCSLL> — sempre os dois juntos. Exemplo com PIS, COFINS e CSLL retidos (650,00 + 3.000,00 + 1.000,00): 

<Valores>
  <ValorServicos>100000.00</ValorServicos>
  <ValorDeducoes>0.00</ValorDeducoes>
  <ValorPis>650.00</ValorPis>
  <ValorCofins>3000.00</ValorCofins>
  <ValorInss>0.00</ValorInss>
  <ValorIr>0.00</ValorIr>
  <ValorCsll>0.00</ValorCsll>
  <OutrasRetencoes>0.00</OutrasRetencoes>
  <ValorIss>2000.00</ValorIss>
  <Aliquota>2.00</Aliquota>
  <DescontoIncondicionado>0.00</DescontoIncondicionado>
  <DescontoCondicionado>0.00</DescontoCondicionado>

  <!-- Detalhamento Federal (NT 007) -->
  <CST>01</CST>
  <vBcPisCofins>100000.00</vBcPisCofins>
  <pAliqPis>0.65</pAliqPis>
  <pAliqCofins>3.00</pAliqCofins>
  <tpRetPisCofins>3</tpRetPisCofins>
  <vRetCSLL>4650.00</vRetCSLL>
</Valores>
Tag Tipo Descrição
CST Texto (2 dígitos) Situação Tributária de PIS/COFINS: 00–09, 49, 50–56, 60–67, 70–75, 98, 99
vBcPisCofins Decimal Base de cálculo do débito próprio de PIS/COFINS (com ela, ValorPis = base × pAliqPis / 100 e ValorCofins = base × pAliqCofins / 100, calculados pelo servidor)
pAliqPis Decimal Alíquota de PIS (%)
pAliqCofins Decimal Alíquota de COFINS (%)
tpRetPisCofins Numérico 0 não retidos; 3 PIS/COFINS/CSLL retidos; 4 PIS/COFINS retidos; 5 só PIS; 6 só COFINS; 7 COFINS/CSLL; 8 só CSLL; 9 PIS/CSLL
vRetCSLL Decimal Soma de PIS + COFINS + CSLL retidos (abate o valor líquido)

<Aliquota> passou a ser obrigatória no XSD

No schema anterior <Aliquota> era minOccurs="0". No schema atual ela é minOccurs="1" dentro de <Valores>. A ausência da tag quebra a validação estrutural do XML.

Valores de domínio

Os códigos válidos de <CST> e <tpRetPisCofins> seguem as tabelas oficiais da NT 007 do padrão nacional da NFS-e. A nota é recusada quando o grupo PIS/COFINS é informado sem <CST>, quando <tpRetPisCofins> = 0 vem com <vRetCSLL> maior que zero, ou quando há tipo de retenção declarado sem valor em <vRetCSLL>. A retenção de CSLL enviada na tag antiga <ValorCsll> é convertida para <vRetCSLL>. Os nomes CstPisCofins, TpRetPisCofins, VlBcPisCofins, PAliqPis, PAliqCofins, VlRetCSLL e VlINSS, divulgados anteriormente nesta página, são aceitos apenas provisoriamente — migre para os nomes do XSD.

Blocos opcionais: CondicaoPagamento, DadosObra e DadosImovel

Posições aceitas pelo XSD e lidas pela API: <DadosObra> dentro de <Prestador>; <DadosImovel> dentro de <Prestador> ou no final de <InfDeclaracaoPrestacaoServico>; e, ao final de <InfDeclaracaoPrestacaoServico>, após <IncentivoFiscal>, nesta ordem: <CondicaoPagamento>, <DadosImovel> e <TipoOperacao>: 

  <Prestador>
    <CpfCnpj><Cnpj>12345678000195</Cnpj></CpfCnpj>
    <!-- 1. 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>
      <CodigoMunicipioObra>5208707</CodigoMunicipioObra>
      <UfObra>GO</UfObra>
    </DadosObra>
    <InscricaoMunicipal>123456</InscricaoMunicipal>
  </Prestador>
  ...
  <RegimeEspecialTributacao>1</RegimeEspecialTributacao>
  <OptanteSimplesNacional>2</OptanteSimplesNacional>
  <IncentivoFiscal>2</IncentivoFiscal>

  <!-- 2. Condições de pagamento (uma única <Parcela>) -->
  <CondicaoPagamento>
    <Condicao>7</Condicao>
    <QuantidadeParcela>3</QuantidadeParcela>
    <Observacao>Pagamento em 3 parcelas mensais</Observacao>
    <Parcela>
      <Parcela>1</Parcela>
      <Valor>333.34</Valor>
    </Parcela>
  </CondicaoPagamento>

  <!-- 3. Dados do imóvel (posição alternativa) -->
  <DadosImovel>
    <Cib>987654321</Cib>
    <InscricaoImobiliaria>1.2.3.4567.8</InscricaoImobiliaria>
    <Cep>74000000</Cep>
    <Logradouro>AVENIDA ANHANGUERA</Logradouro>
    <Numero>123</Numero>
    <Bairro>CENTRO</Bairro>
    <Complemento>SALA 2</Complemento>
  </DadosImovel>

  <!-- 4. Tipo de operação IBS/CBS (1 a 5) -->
  <TipoOperacao>1</TipoOperacao>
</InfDeclaracaoPrestacaoServico>

Posicionamento e capitalização do <DadosObra>

Envie <DadosObra> dentro de <Prestador> — no nível de <InfDeclaracaoPrestacaoServico> o grupo é ignorado. Todas as tags usam PascalCase — atenção especial ao <CnoObra> (e não <Cno>). Os nomes com sufixo Fild (<cepObraFild>, <logradouroObraFild> etc.) não são reconhecidos e são descartados. <TipoOperacao> (também aceito como <tpOper>) é exigido nos subitens 10.05, 15.09, 17.12 e 25.05 da LC 116; se omitido nesses casos, o servidor assume 1 quando <Condicao> = 7 (a prazo) e 5 nos demais.

Validações realizadas pelo sistema

  • Obrigatoriedade: com o município integrado ao ADN (a partir de 03/08/2026) ou com o NBS parametrizado como obrigatório pela prefeitura, as três tags são exigidas, exceto no serviço de não incidência (99.01).
  • NBS cadastrado: o <CodigoNbs> deve existir no cadastro de códigos NBS (com ou sem pontos).
  • 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 6 dígitos numéricos, sem pontos, e corresponder ao INDOP vinculado ao NBS.
  • Classificação Tributária x NBS: o <CodigoClassTrib> deve possuir 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

  • É obrigatório informar as tags <CodigoNbs>, <CodigoINDOP> e <CodigoClassTrib> do serviço.
  • Código NBS informado em <CodigoNbs> não existe no cadastro de código NBS.
  • Código NBS informado não está vinculado ao serviço informado em <ItemListaServico>. Verifique o cadastro do serviço (AR017).
  • Código INDOP inválido para o NBS informado.
  • Código de Classificação Tributária inválido para o NBS informado.

Response de Sucesso (HTTP 200)

Quando a nota é emitida com sucesso, a API retorna, como texto no corpo da resposta, um XML <GerarNfseResposta> contendo:

  • Número da NFS-e gerada (<Numero>)
  • Código de verificação (<CodigoVerificacao>)
  • Identificador da nota (atributo Id de <InfNfse>) — guarde-o: é exigido no cancelamento
  • Data e hora da emissão e situação da nota (<Status>: 0 Ativa, 1 Substituída, 2 Aguardando cancelamento, 3 Cancelada)
  • Valores apurados (<ValoresNfse>) e a declaração da prestação (<DeclaracaoPrestacaoServico>, com Serviço, Prestador e Tomador)
  • Bloco <DadosNotaNacional> com os dados da Reforma Tributária

O grupo <InfNfse> do retorno passou a incluir os campos <DescricaoCancelamento>, <DescricaoSubstituicao>, <Observacao> e o bloco <DadosNotaNacional>; a <Discriminacao> vem em <DeclaracaoPrestacaoServico>, dentro de <Servico>. A <ChaveAcessoNacional> vem vazia até a nota ser autorizada no Ambiente de Dados Nacional: 

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

Atenção à grafia de <AliqotaIBS>

A tag é declarada no XSD como <AliqotaIBS> (sem a letra "u"), diferente de <AliquotaCBS>. Ao fazer o parse do retorno, utilize exatamente a grafia do schema. Além disso, no grupo <ValoresNfse> os campos BaseCalculo, Aliquota, ValorIss e ValorLiquido são sempre retornados — o valor líquido vem em <ValorLiquido>, e não em <ValorLiquidoNfse> como consta no XSD —, seguidos do detalhamento (ValorServicos, ValorDeducoes, retenções e descontos) e das tags da NT 007. O retorno traz campos que não constam do XSD (ex.: Status, IssRetido, IdentificacaoRps): leia-o pelo nome das tags, sem validá-lo contra o schema.

Erros Comuns

Código Erro Solução
200 + <ListaMensagemRetorno> Nota recusada: credenciais inválidas, XML inválido, assinatura digital, prestador/tomador, NBS, INDOP, Classificação Tributária ou outra regra de negócio Leia a segunda <Mensagem> (motivo da recusa); a primeira traz o Cód. erro, número a informar ao suporte
200 + <ListaMensagemRetorno> ... bloqueada temporariamente para este emissor por excesso de erros consecutivos Sete recusas em 3 minutos bloqueiam o emissor por 5 minutos. Corrija o XML antes de reenviar e não reenvie em laço
200 + <ListaMensagemRetorno> ... temporariamente indisponível ... (envios anteriores em andamento ou limite de envios simultâneos do município) No máximo 3 envios simultâneos por CNPJ e um limite por município. Aguarde a resposta dos envios anteriores e reenvie
400 Corpo JSON inválido ou sem Usuario, Senha ou Xml; ou falha ao encaminhar a requisição ao município (JSON com error/message) Confira o JSON e a UF/Tenant da URL
415 Content-Type diferente de application/json Envie Content-Type: application/json
429 Mais de 15 requisições por segundo a partir do mesmo IP Aguarde o tempo informado no header Retry-After e reduza o paralelismo
500 Erro no servidor Tente novamente ou contate suporte

Cancelar Nota Fiscal

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>{atributo Id de <InfNfse> no retorno da emissão}</Id>
      </IdentificacaoNfse>
      <CodigoCancelamento>1</CodigoCancelamento>
    </InfPedidoCancelamento>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><!-- Assinatura Digital --></Signature>
  </Pedido>
</CancelarNfseEnvio>

Campos que passaram a ser obrigatórios

Em <IdentificacaoNfse>, as tags <CodigoVerificacao> e <Id> passaram a minOccurs="1". A tag <CodigoCancelamento> também deixou de ser opcional em <InfPedidoCancelamento>. A ordem exigida é: Numero, CpfCnpj, InscricaoMunicipal, CodigoMunicipio, CodigoVerificacao, DescricaoCancelamento, Id. A nota é localizada pela combinação Numero + CodigoVerificacao + Id, copiados do XML de retorno da emissão (InfNfse/Numero, InfNfse/CodigoVerificacao e o atributo Id de <InfNfse>). <DescricaoCancelamento> (até 500 caracteres) é obrigatória quando o código é 6.

Conforme a parametrização do município, o pedido cancela a nota imediatamente (<Status> 3 no retorno) ou registra uma solicitação que aguarda a autorização da prefeitura (<Status> 2). Podem se aplicar prazo máximo após a emissão e o bloqueio por competência (DMS/REST) encerrada; nota já cancelada ou já substituída não pode ser cancelada.

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 (exige <DescricaoCancelamento>)

Substituir Nota Fiscal

Endpoint

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

A substituição tem rota própria e usa o mesmo XML da geração (raiz <GerarNfseEnvio>), com informações adicionais sobre qual nota está sendo substituída. Na rota de geração (/nfe/gerar) o bloco <RpsSubstituido> é ignorado e a nota é emitida como uma nota nova.

Bloco RpsSubstituido

<Rps>
  <IdentificacaoRps>
    <Numero>2</Numero>
    <Serie>A1</Serie>
    <Tipo>1</Tipo>
  </IdentificacaoRps>
  <DataEmissao>2025-12-16T10:00:00</DataEmissao>
  <Status>1</Status>

  <!-- Bloco de Substituição: Numero = número da NFS-e a ser substituída -->
  <RpsSubstituido>
    <Numero>1542</Numero>
    <Serie>A1</Serie>
    <Tipo>1</Tipo>
  </RpsSubstituido>
</Rps>

Como funciona:

Ao enviar à rota /nfe/substituir um XML com o bloco <RpsSubstituido>, o sistema gera uma nova nota com os dados atualizados e marca a nota anterior como Substituída (<Status> 1) — ela não é cancelada. Em <RpsSubstituido><Numero> informe o número da NFS-e a ser substituída (o <Numero> de <InfNfse> no retorno), e em <IdentificacaoRps> um RPS novo, ainda não utilizado. Uma mesma nota só pode ser substituída uma vez, e a prefeitura pode bloquear a substituição ou a troca de tomador.

Principais Campos do XML

Campo Tipo Obrigatório Descrição
Numero Numérico SIM Número do RPS (único por prestador)
Serie Texto SIM Série do RPS
DataEmissao Data/hora SIM Data/hora do RPS (YYYY-MM-DDThh:mm:ss; a API também aceita YYYY-MM-DD). A NFS-e recebe a data/hora do processamento
InscricaoMunicipal (Prestador) Texto SIM Inscrição municipal do prestador, pela qual ele é localizado no cadastro do município
ValorServicos Decimal SIM Valor total dos serviços
ValorIss Decimal NÃO Valor do ISS; é recalculado pelo servidor (base de cálculo × alíquota)
Aliquota Decimal SIM Alíquota do ISS em percentual (ex.: 5.00), entre 2,00 e 5,00 e igual à do serviço cadastrado no município (exceto Simples Nacional/MEI e tributação fora do município)
ItemListaServico Texto SIM Código do serviço da LC 116/2003 (ex.: 01.07). Em alguns municípios a tag recebe o código interno do serviço; nesse caso a mensagem de recusa informa o código a utilizar
CodigoNbs Texto (12 caracteres, ex.: 1.2345.67.89) 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 NÃO Código CNAE
Discriminacao Texto SIM Descrição do serviço (até 2000 caracteres)
IssRetido Numérico NÃO 1=Sim (retido pelo tomador), 2=Não; ausente = não retido
CodigoMunicipio (Servico) Numérico (IBGE) SIM Código IBGE do município onde o serviço foi prestado
MunicipioIncidencia Numérico (IBGE) SIM Código IBGE do município de incidência do ISS (opcional no XSD, exigido pela API)
IdentificacaoTomador Grupo SIM CPF/CNPJ válido do tomador (ou <Estrangeiro>1 com <DocumentoEstrangeiro>); sem ele a nota é recusada
RazaoSocial (Tomador) Texto SIM Nome/razão social do tomador
CodigoMunicipio (Endereço do Tomador) Numérico (IBGE) SIM Município do tomador (para tomador estrangeiro, informe o país em <CodigoPais>)
Signature XMLDSig SIM Assinatura com o certificado do prestador ou de sócio ativo, incluindo o certificado X.509 em <KeyInfo>
CST Texto REGRA DE NEGÓCIO CST de PIS/COFINS (NT 007) — dentro de <Valores>; obrigatório quando o grupo PIS/COFINS é informado
tpRetPisCofins Numérico NÃO Tipo de retenção de PIS/COFINS/CSLL (NT 007); ausente = 0 (não retidos)
vBcPisCofins Decimal NÃO Base de cálculo de PIS/COFINS
pAliqPis / pAliqCofins Decimal NÃO Alíquotas de PIS e COFINS aplicadas
vRetCSLL Decimal NÃO Soma de PIS, COFINS e CSLL retidos (exige tpRetPisCofins diferente de 0)
ValorInss Decimal NÃO Contribuição Previdenciária retida (não existe tag VlINSS)
Condicao Numérico NÃO Condição de pagamento (1 à vista, 2 cheque, 3 cartão de crédito, 4 cartão de débito, 5 crédito em conta, 6 duplicata, 7 a prazo); 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> dentro de <Prestador> (PascalCase); nos serviços de obra, informe o CNO ou o endereço completo e o município da obra
Cib Texto NÃO Código CIB do imóvel, em <DadosImovel>; nas operações com imóvel, informe o CIB ou o endereço completo
TipoOperacao Numérico (1 a 5) REGRA DE NEGÓCIO Tipo de operação IBS/CBS, ao final de <InfDeclaracaoPrestacaoServico> (alias <tpOper>); exigido nos subitens 10.05, 15.09, 17.12 e 25.05

Códigos de Referência

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 Suporte técnico em informática
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
CST Texto (código numérico com zeros à esquerda, ex.: 01) Tabela de CST de PIS/COFINS da NT 007: 00–09, 49, 50–56, 60–67, 70–75, 98, 99
tpRetPisCofins Numérico inteiro Tabela de tipos de retenção da NT 007: 0 PIS/COFINS/CSLL não retidos; 3 PIS/COFINS/CSLL retidos; 4 PIS/COFINS retidos, CSLL não retido; 5 PIS retido, COFINS/CSLL não retidos; 6 COFINS retido, PIS/CSLL não retidos; 7 PIS não retido, COFINS/CSLL retidos; 8 PIS/COFINS não retidos, CSLL retido; 9 COFINS não retido, PIS/CSLL retidos (1 e 2 são legados)
Condicao Numérico inteiro (até 5 dígitos) Condição de pagamento (tabela Centi): 1 à vista, 2 cheque, 3 cartão de crédito, 4 cartão de débito, 5 crédito em conta, 6 duplicata, 7 a prazo
TipoOperacao Numérico inteiro (1 a 5) Tipo de operação IBS/CBS (tpOper da NFS-e Nacional): 1 fornecimento com pagamento posterior; 2 recebimento do pagamento com fornecimento já realizado; 3 fornecimento com pagamento já realizado; 4 recebimento do pagamento com fornecimento posterior; 5 fornecimento e recebimento do pagamento concomitantes

Referência oficial

Os domínios de CST e tpRetPisCofins estão declarados no XSD da Centi (tsCstPisCofins e tsTipoRetPisCofins) e seguem as tabelas publicadas na Nota Técnica 007 do padrão nacional da NFS-e. Consulte sempre a versão vigente da NT para a relação completa e atualizada dos códigos.

NBS, INDOP e Classificação Tributária

Campo Formato Validação aplicada
CodigoNbs 12 caracteres no formato 9.9999.99.99 (o servidor também aceita sem os pontos) Deve existir no cadastro NBS 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

Validação estrutural x validação de negócio

O XSD verifica presença opcional, sequência e formato. A compatibilidade entre Serviço, NBS, INDOP e Classificação Tributária é validada no processamento da API com base nos cadastros da Centi. A API não valida o XML contra o XSD no recebimento: uma tag com nome ou capitalização diferente do schema é ignorada sem aviso e o valor não chega à nota. Valide o XML contra o XSD antes de integrar.

Perguntas Frequentes

Como obter as credenciais de acesso?

Entre em contato com a prefeitura do município onde sua empresa está cadastrada.

Preciso de certificado digital?

Sim. O XML de emissão e de substituição deve ser assinado digitalmente com certificado ICP-Brasil A1 ou A3 dentro da validade, do próprio prestador (CNPJ da matriz ou da filial) ou de sócio ativo, com o certificado incluído em <KeyInfo><X509Data><X509Certificate>. Sem isso a resposta é Assinatura digital inválida., incorreta. ou expirada.

Existe ambiente de testes?

Sim. As rotas POST /nfe/gerar/homologacao/{UF}/{Tenant} e POST /nfe/substituir/homologacao/{UF}/{Tenant} executam as mesmas validações da emissão, sem gravar a nota, e devolvem um retorno de teste (Numero 0000 e CodigoVerificacao *TESTE*). As credenciais e os cadastros usados são os de produção.

Posso cancelar uma nota via API?

Sim, através do endpoint POST /nfe/cancelar/{UF}/{Tenant} com XML de cancelamento.

Posso substituir uma nota já emitida?

Sim. Use o endpoint POST /nfe/substituir/{UF}/{Tenant} com o mesmo XML da geração, adicionando o bloco <RpsSubstituido> com o número da NFS-e que está sendo substituída. Na rota de geração o bloco é ignorado.

Por que CodigoINDOP e CodigoClassTrib são opcionais no XSD, mas podem gerar rejeição?

O atributo minOccurs="0" mantém compatibilidade estrutural do schema. Na emissão, porém, o provider aplica regras de negócio e valida os códigos contra o cadastro do NBS. Assim, um XML pode passar na validação XSD e ainda ser rejeitado por inconsistência cadastral.

Documentação OpenAPI / Swagger

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

Especificação OpenAPI

Arquivos para Download

Exemplos completos de XML de cada requisição:

Schemas XSD

Arquivos de schema para validação estrutural dos XMLs (baixe os dois para a mesma pasta: o nfse.xsd importa o schema da assinatura digital):

Atualizações/Alterações

NOVO Revisão da documentação conforme as regras vigentes da API
  06/11/2026

A documentação, os XMLs de exemplo, o XSD e o validador foram revisados e alinhados ao comportamento atual da API. Não houve mudança na API: os pontos abaixo corrigem orientações que estavam divergentes.

Requisição:
  • Não há HTTP Basic Auth: usuário, senha e XML seguem no corpo JSON (Usuario, Senha e Xml), com Content-Type: application/json.
  • Recusas de negócio (inclusive credenciais inválidas) retornam HTTP 200 com <ListaMensagemRetorno>; os códigos HTTP de erro são 400, 415, 429 e 500.
  • A substituição usa a rota própria /nfe/substituir/{UF}/{Tenant}; em <RpsSubstituido><Numero> vai o número da NFS-e substituída, que passa à situação "Substituída".
  • Documentadas as rotas de consulta de RPS e de homologação (teste sem gravar a nota).
XML de envio:
  • NT 007: os nomes corretos das tags são <CST>, <vBcPisCofins>, <pAliqPis>, <pAliqCofins>, <tpRetPisCofins> e <vRetCSLL>. Não existe <VlINSS> (o INSS retido segue em <ValorInss>). Os nomes divulgados antes (CstPisCofins, VlRetCSLL etc.) são aceitos apenas provisoriamente.
  • <DadosObra> deve ser enviado dentro de <Prestador>; no nível de <InfDeclaracaoPrestacaoServico> ele é ignorado. Novas tags <CodigoMunicipioObra> e <UfObra>. As tags com sufixo Fild não são reconhecidas.
  • <DadosImovel> aceita também <InscricaoImobiliaria> e <Complemento>.
  • Documentado o <TipoOperacao> (alias <tpOper>) do IBS/CBS.
  • Obrigatórios na emissão: <InscricaoMunicipal> do prestador, <IdentificacaoTomador>, razão social e município do tomador, <CodigoMunicipio> e <MunicipioIncidencia> do serviço, e a assinatura com o certificado em <KeyInfo>.
  • Cancelamento: o código 6 (Outros) exige <DescricaoCancelamento>; o XSD passou a aceitar até 500 caracteres nesse campo.
XML de retorno:
  • O valor líquido vem em <ValorLiquido>; o retorno traz <Status>, o detalhamento dos valores e campos que não constam do XSD. O atributo Id de <InfNfse> é o identificador exigido no cancelamento.
Arquivos:
  • Os quatro modelos XML e o nfse.xsd foram atualizados; o schema da assinatura (xmldsig-core-schema20020212.xsd) passou a ser disponibilizado para download.
Documentação Modelos XML XSD Validador
Obrigatoriedade das tags CodigoNbs, CodigoINDOP e CodigoClassTrib
  09/09/2026

Em razão da alteração promovida pelo ADN (Ambiente de Dados Nacional) da NFS-e, as tags <CodigoNbs>, <CodigoINDOP> e <CodigoClassTrib> passam a ser obrigatórias no XML de emissão a partir de 03/08/2026. Esses dados alimentam o grupo IBSCBS exigido no leiaute nacional da DPS/NFS-e.

Fundamento normativo:
  • A LC 214/2025 instituiu o IBS e a CBS. As Notas Técnicas do CGNFS-e (NT 004 e NT 007) definem o grupo IBSCBS no leiaute da DPS/NFS-e.
  • O Portal Nacional da NFS-e prevê a obrigatoriedade do grupo IBS/CBS e de suas regras de validação a partir de 03/08/2026.
  • Anexo VI – Leiautes e Regras de Negócio V1.03.00 (NT 007), aba LEIAUTE DPS_NFS-e: cIndOp e cClassTrib possuem ocorrência 1-1 dentro do grupo.
  • No XSD nacional tiposComplexos_v1.01.xsd, o elemento IBSCBS possui minOccurs="0": ou o grupo é enviado completo, ou é omitido — não há meio-termo.
Regra prática para os integradores:
  • A partir de 03/08/2026, <CodigoNbs>, <CodigoINDOP> e <CodigoClassTrib> passam a ser obrigatórios no XML de emissão.
  • Os valores devem seguir a correlação oficial do Anexo VIII V1.01.00 (Item da LC 116 × NBS × cIndOp × cClassTrib). Combinações fora da tabela são rejeitadas pelo ADN.
  • Com o município integrado ao ADN, o XML de emissão sem esses campos é recusado com a mensagem É obrigatório informar as tags <CodigoNbs>, <CodigoINDOP> e <CodigoClassTrib> do serviço.
Estrutura esperada no grupo <Servico>: 
<ItemListaServico>01.07</ItemListaServico>
<CodigoNbs>1.2345.67.89</CodigoNbs>
<CodigoINDOP>010101</CodigoINDOP>
<CodigoClassTrib>000001</CodigoClassTrib>
<CodigoCnae>6201501</CodigoCnae>
Exceção — não incidência (9901):
  • Serviços de não incidência, com código de tributação nacional 9901, estão dispensados: o Anexo VIII não estabelece correlação para o item 99.01.01 e, nesses casos, o grupo IBS/CBS é omitido.
  • A dispensa vale somente para o 9901. Os demais subitens do grupo 99 (99.02, 99.03 e 99.04) possuem correlação oficial e seguem a regra geral.
Referências oficiais:
XML de emissão Campos obrigatórios ADN / IBS / CBS LC 214/2025 — NT 007
Atualização do XSD: retenções federais (NT 007), CondicaoPagamento, DadosObra e DadosImovel
  05/08/2026

O schema oficial da Centi foi atualizado, ampliando o XML de emissão com campos de detalhamento federal, blocos de condição de pagamento, obra e imóvel, além de endurecer a obrigatoriedade de alguns campos já existentes.

Novos campos em <Valores> (Detalhamento Federal — NT 007):
  • <CST>, <vBcPisCofins>, <pAliqPis>, <pAliqCofins>, <tpRetPisCofins> e <vRetCSLL> (nomes corrigidos em 06/11/2026).
  • Devem ser enviados no final do grupo <Valores>, após <DescontoCondicionado>, na ordem definida no XSD.
  • Os domínios de CST e tpRetPisCofins seguem as tabelas da NT 007.
Novos blocos:
  • <CondicaoPagamento> — Condicao, QuantidadeParcela, Observacao e uma <Parcela>; fica em <InfDeclaracaoPrestacaoServico>, após <IncentivoFiscal>.
  • <DadosObra> — CnoObra, CepObra, LogradouroObra, NumeroObra, BairroObra, ComplementoObra, QuadraObra, LoteObra, CodigoMunicipioObra e UfObra; fica dentro de <Prestador>.
  • <DadosImovel> — Cib, InscricaoImobiliaria, Cep, Logradouro, Numero, Bairro, Complemento; dentro de <Prestador> ou após <CondicaoPagamento>.
Campos que passaram a ser obrigatórios:
  • <Aliquota> dentro de <Valores>.
  • <Signature> na declaração de prestação de serviço e no pedido de cancelamento.
  • <CodigoVerificacao> e <Id> em <IdentificacaoNfse>, e <CodigoCancelamento> em <InfPedidoCancelamento>.
Outras alterações:
  • <CodigoNbs> é aceito com ou sem pontos separadores.
  • Nomenclatura de obra: use <CnoObra> (PascalCase). As tags legadas com sufixo Fild não são reconhecidas pela API e são descartadas.
  • O bloco <Prestador> passou a aceitar Endereco, Contato, RazaoSocial, NomeFantasia e InscricaoEstadual.
  • <Tomador> passou a aceitar Estrangeiro, DocumentoEstrangeiro e InscricaoEstadual.
  • No retorno, <InfNfse> inclui DescricaoCancelamento, DescricaoSubstituicao, Observacao e <DadosNotaNacional> (a Discriminacao vem em <Servico>).
  • O validador da documentação recebeu 5 novas regras e teve as regras de <DadosObra> revisadas.
XML de emissão Novo XSD NT 007 / PIS / COFINS Validador
Novas tags CodigoINDOP e CodigoClassTrib no XML de emissão
  03/08/2026

O XML de emissão passa a receber as tags <CodigoINDOP> e <CodigoClassTrib> dentro do grupo <Servico>, logo após <CodigoNbs>. Os dados são utilizados para validar a classificação da operação e garantir a persistência do NBS correto na NFS-e.

Estrutura esperada: 
<ItemListaServico>01.07</ItemListaServico>
<CodigoNbs>1.2345.67.89</CodigoNbs>
<CodigoINDOP>010101</CodigoINDOP>
<CodigoClassTrib>000001</CodigoClassTrib>
<CodigoCnae>6201501</CodigoCnae>
Regras aplicadas no processamento:
  • O NBS deve estar vinculado ao serviço informado em <ItemListaServico>, conforme cadastro AR017.
  • O INDOP deve conter 6 dígitos numéricos, sem pontos, e coincidir com o código vinculado ao NBS.
  • A Classificação Tributária deve conter 6 dígitos numéricos e coincidir com o cadastro do NBS.
  • Em caso de divergência, o RPS é rejeitado com mensagem específica ao contribuinte.
  • No XSD, as duas novas tags permanecem com minOccurs="0"; a obrigatoriedade é tratada como regra de negócio no provider.
Exemplos de mensagens:
  • Código INDOP inválido para o NBS informado.
  • Código de Classificação Tributária inválido para o NBS informado.
  • Código NBS informado não está vinculado ao serviço informado em <ItemListaServico>. Verifique o cadastro do serviço (AR017).
XML de emissão Validação de negócio NBS / INDOP / cClassTrib
Validador de XML NFS-e disponível na documentação
  02/06/2026

A documentação da API agora conta com um Validador de XML integrado. Antes de enviar seu XML à API, você pode verificar instantaneamente se a estrutura está correta — sem precisar abrir chamado de suporte.

O que o validador verifica:
  • Namespace correto (http://www.centi.com.br/files/nfse.xsd)
  • Encoding e estrutura XML (parse errors)
  • Tamanho fixo de CPF (11 dígitos), CNPJ (14 dígitos), CEP (8 dígitos) e UF (2 caracteres)
  • Campo <CodigoNbs> obrigatório por regra de negócio
  • Campos <CodigoINDOP> e <CodigoClassTrib> com exatamente 6 dígitos numéricos
  • Sequência correta das tags no grupo <Servico>: NBS → INDOP → Classificação Tributária
  • Datas no formato ISO 8601 (dateTime)
  • Valores decimais com ponto (não vírgula) como separador
  • Campos fora do XSD: <NaturezaOperacao>, <NomeFantasia> no Tomador, <Observacao> no nível principal
  • Validações de padrão XSD: IssRetido, Status, ExigibilidadeISS, CodigoCancelamento e outros
Como usar:
  • Acesse o menu Validador de XML na barra lateral
  • Arraste o arquivo .xml ou cole o conteúdo diretamente
  • Clique em Validar XML — o resultado aparece imediatamente
100% local Sem transmissão de dados XSD Centi
Novo campo CodigoNbs no XML de envio e retorno
  13/01/2026

A partir de 13/01/2026, os XMLs de envio e retorno passam a incluir o campo <CodigoNbs> (Nomenclatura Brasileira de Serviços) dentro do grupo <Servico>, efetuando assim a classificação do serviço conforme a NBS.

Detalhes da alteração:
  • Tag: <CodigoNbs> - Código da Nomenclatura Brasileira de Serviços (NBS)
  • Localização no XML de envio: <Servico> dentro de <InfDeclaracaoPrestacaoServico>
  • Localização no XML de retorno: <Servico> dentro de <DeclaracaoPrestacaoServico>
  • Formato no layout Centi atual: 12 caracteres conforme tsCodigoNbs do XSD (ex.: 1.2345.67.89)
  • Obrigatoriedade: Obrigatório quando o município está integrado ao ADN (a partir de 03/08/2026) ou quando a prefeitura parametriza o NBS como obrigatório — junto com <CodigoINDOP> e <CodigoClassTrib>
  • Relação com ItemListaServico: O código NBS deve ser compatível com o Item da Lista de Serviços (LC 116/2003) informado
Importante:
  • A tabela completa de códigos NBS está disponível no link "https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc/anexoviii-correlacaoitemnbsindopcclasstrib_ibscbs_v1-00-00.xlsx"
  • O código NBS deve ser selecionado conforme a atividade específica do serviço prestado
  • A relação entre ItemListaServico (LC 116/2003) e CodigoNbs é de 1 para N (um item da lista pode ter vários códigos NBS)
  • Sistemas integradores devem implementar validação do código NBS para evitar rejeição
No menu "Arquivos para Download", contém os XMLs de exemplo atualizados com o campo CodigoNbs.
Novo campo RpsSubstituido no XML de envio
  12/01/2026

O XML de envio agora suporta informações sobre RPS que está sendo substituído através da nova tag <RpsSubstituido> dentro do grupo <Rps>.

Detalhes da alteração:
  • Tag principal: <RpsSubstituido> - Contém dados do RPS que está sendo substituído
  • <Numero> - Número da NFS-e que está sendo substituída
  • <Serie> - Série (exigida pelo XSD)
  • <Tipo> - Tipo (exigido pelo XSD)
  • O bloco só é considerado na rota /nfe/substituir/{UF}/{Tenant}; na rota de geração ele é ignorado.
Novo grupo DadosObra (XML de envio)
  12/01/2026

O XML de envio agora permite informar dados detalhados da obra diretamente no grupo <Prestador> através da nova tag <DadosObra>.

Detalhes da alteração:
  • Tag principal: <DadosObra> - Contém informações detalhadas da obra
  • <CnoObra> - Código CNO (Cadastro Nacional de Obras) da obra
  • <CepObra> - CEP do local da obra
  • <LogradouroObra> - Logradouro completo da obra
  • <NumeroObra> - Número do endereço da obra
  • <BairroObra> - Bairro onde está localizada a obra
  • <ComplementoObra> - Complemento do endereço da obra
  • <QuadraObra> - Quadra da obra (quando aplicável)
  • <LoteObra> - Lote da obra (quando aplicável)

Atenção: todos os nomes de tag usam PascalCase (primeira letra maiúscula), igual ao padrão do XSD. Tags com inicial minúscula (cepObra, logradouroObra etc.) não são reconhecidas pelo sistema Centi, pois XML é case-sensitive: os dados são descartados e, nos serviços de obra, a nota é recusada por falta dos dados da obra. O XML de retorno da API usa os mesmos nomes (CnoObra, CepObra, LogradouroObra etc.); não existem tags com o sufixo "Fild".

Novo grupo Intermediario no XML de envio
  12/01/2026

O XML de envio agora suporta informações sobre intermediário de serviços através da nova tag <Intermediario>.

Detalhes da alteração:
  • Tag principal: <Intermediario> - Contém dados do intermediário de serviços
  • <IdentificacaoIntermediario> - Grupo com CPF/CNPJ e Inscrição Municipal do intermediário
  • <RazaoSocial> - Razão social do intermediário
  • O grupo é aceito pelo XSD; atualmente, porém, os dados do intermediário não são registrados na NFS-e emitida pela API.
Campos removidos do XML de envio
  12/01/2026

Alguns campos foram removidos do XML de envio para simplificação e adequação ao padrão nacional.

Campos que NÃO devem mais ser enviados:
  • <NaturezaOperacao> - Removido do nível principal de InfDeclaracaoPrestacaoServico
  • <Observacao> - Removido do nível principal (mantido apenas dentro de Servico)
  • <NomeFantasia> - Removido do grupo Tomador
Nova estrutura de dados da Nota Nacional no XML de retorno
  12/01/2026

A partir de 12/01/2026, o XML de retorno das notas fiscais incluirá uma nova tag <DadosNotaNacional> contendo informações sobre IBS, CBS e a chave de acesso nacional.

Detalhes da alteração:
  • Tag principal: <DadosNotaNacional> - Contém dados referentes à nota nacional
  • <AliqotaIBS> - Alíquota aplicada para calcular o IBS
  • <AliquotaCBS> - Alíquota aplicada para calcular o CBS
  • <ValorIBS> - Valor calculado do IBS
  • <ValorCBS> - Valor calculado do CBS
  • <ChaveAcessoNacional> - Chave de acesso do registro da nota nacional
Padronização dos nomes das tags em DadosNotaNacional
  12/01/2026

As tags dentro de <DadosNotaNacional> tiveram seus nomes padronizados para melhor legibilidade. Os nomes antigos não devem mais ser utilizados.

Mudanças nos nomes das tags:
  • <pAliqIBS> foi substituída por <AliqotaIBS>
  • <pAliqCBS> foi substituída por <AliquotaCBS>
  • <vIBS> foi substituída por <ValorIBS>
  • <vCBS> foi substituída por <ValorCBS>
  • <chAcesso> foi substituída por <ChaveAcessoNacional>
Novos campos informativos no XML de retorno
  12/01/2026

O XML de retorno foi enriquecido com novos campos informativos para melhor rastreabilidade e gestão das notas fiscais.

Novos campos adicionados:
  • <DescricaoCancelamento> - Descrição do motivo de cancelamento da nota
  • <DescricaoSubstituicao> - Descrição do motivo de substituição da nota
  • <Discriminacao> - Discriminação detalhada do serviço prestado (retornada em <DeclaracaoPrestacaoServico> → <Servico>)
  • <Observacao> - Observações adicionais sobre a nota fiscal
  • <Status> - Situação da nota: 0 Ativa, 1 Substituída, 2 Aguardando cancelamento, 3 Cancelada
  • <ValorCredito>, <EnderecoPrestadorServico> e <OrgaoGerador> - declarados no XSD, mas atualmente não preenchidos no retorno (o endereço do prestador vem em <DeclaracaoPrestacaoServico> → <Prestador>)
Novas estruturas de Cancelamento e Substituição
  12/01/2026

O XML de retorno agora inclui estruturas específicas para informações de cancelamento e substituição de notas fiscais.

Detalhes da alteração:
  • <NfseCancelamento> - Contém informações completas sobre o cancelamento da nota
  • <NfseSubstituicao> - Contém informações sobre a nota fiscal substituta
  • <Confirmacao> - Dados da confirmação do cancelamento
  • <DataHora> - Data e hora da confirmação do cancelamento
  • <NfseSubstituidora> - Número da nota fiscal que substituiu
  • Esses grupos estão declarados no XSD, mas atualmente a API não os preenche: a situação da nota é informada em <Status> (1 Substituída, 2 Aguardando cancelamento, 3 Cancelada) e em <DescricaoCancelamento>/<DescricaoSubstituicao>; a nota substituta traz o número da substituída em <NfseSubstituida>.
Grupo DadosObra retornado no Prestador
  12/01/2026

Quando enviados no XML de entrada, os dados da obra agora são retornados dentro do grupo <Prestador> no XML de retorno.

Detalhes da alteração:
  • Os mesmos campos enviados são retornados para confirmação, com os mesmos nomes (CnoObra, CepObra etc.); em nota sem obra o grupo vem com as tags vazias
  • Permite verificar se os dados da obra foram registrados corretamente
  • Localização: dentro de <DeclaracaoPrestacaoServico> → <Prestador>
Simplificação da estrutura ValoresNfse
  12/01/2026

A estrutura <ValoresNfse> foi simplificada, mantendo apenas os campos essenciais para o resumo dos valores da nota.

Campos mantidos em ValoresNfse:
  • <BaseCalculo> - Base de cálculo do ISS
  • <Aliquota> - Alíquota aplicada
  • <ValorIss> - Valor do ISS calculado
  • <ValorLiquido> - Valor líquido da nota fiscal (no XSD consta como ValorLiquidoNfse, mas a API retorna ValorLiquido)
Nota: Os valores detalhados (ValorServicos, ValorDeducoes, retenções, descontos e as tags da NT 007) vêm no próprio <ValoresNfse>, logo após esses quatro campos.
Estruturas aprimoradas para mensagens de retorno
  12/01/2026

O XML de retorno agora possui estruturas específicas para mensagens de alerta e erro, facilitando o tratamento de problemas.

Estruturas de mensagens:
  • <ListaMensagemAlertaRetorno> - Lista de alertas não-críticos
  • <ListaMensagemRetorno> - Lista de mensagens gerais (erros, avisos, confirmações)
  • <Codigo> - Código identificador da mensagem
  • <Mensagem> - Descrição da mensagem
  • <Correcao> - Sugestão de correção (quando aplicável)
  • Na prática, a recusa vem em <ListaMensagemRetorno> com duas <MensagemRetorno>: a primeira traz Cód. erro : seguido do número de registro (informe-o ao suporte) e a segunda, em <Mensagem>, o motivo da recusa.

Fique atualizado!

- Esta seção é atualizada sempre que há mudanças importantes nos XMLs, endpoints ou regras de validação da API.

- No menu "Arquivos para Download", contém o XML de exemplo com as novas tags.

- Valide a estrutura de seu XML antes de enviá-lo no menu "Validador de XML". Lembrando que este processo é somente uma dica opcional e não obrigatória.

Validador de XML

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.

Arraste o arquivo XML aqui ou clique para selecionar

ou cole o conteúdo do XML abaixo
Atalho: Ctrl+Enter para validar 0 caracteres

Use este checklist para diagnosticar erros de transmissão — problemas que ocorrem na camada HTTP/JSON, não no XML em si. São os casos mais comuns de erro (1, 1) mesmo com XML estruturalmente correto.

XML com HTML-encoding dentro do campo JSON
Causa o erro: There is an error in XML document (1, 1)
ERRO CRÍTICO

O campo "xml" no body JSON está com o conteúdo HTML-encoded: os caracteres < > " estão sendo enviados como &lt; &gt; &quot;. Quando o servidor extrai o valor do campo "xml" e tenta fazer o parse como XML, encontra &lt; no lugar de < — causando falha imediata no parse na posição (1,1).

// ERRADO — como está chegando no servidor: "xml": "&lt;GerarNfseEnvio&gt;&lt;Rps&gt;..." // CORRETO — como deve ser enviado: "xml": "<?xml version="1.0" encoding="utf-8"?><GerarNfseEnvio xmlns="http://www.centi.com.br/files/nfse.xsd"><Rps>..."

Como verificar no Postman: No body da requisição (raw → JSON), o valor do campo "xml" deve começar exatamente com <?xml ou <GerarNfseEnvio. Se começar com &lt;?xml ou &lt;GerarNfseEnvio, ainda está HTML-encoded e precisa ser corrigido.

Content-Type incorreto — body é JSON mas header diz XML
Header: Content-Type
ERRO CRÍTICO

O body enviado é JSON (com os campos senha, usuario e xml), mas o header Content-Type está configurado como application/xml. A API só aceita corpo JSON: a requisição é recusada antes de chegar ao processamento da nota (HTTP 415 Unsupported Media Type).

// ERRADO: Content-Type: application/xml; charset=utf-8 // CORRETO: Content-Type: application/json
XML desatualizado dentro da collection do Postman
Campo "xml" no body JSON
ATENÇÃO

O conteúdo do campo "xml" na collection pode estar usando uma versão antiga do XML — sem declaração <?xml...?>, sem namespace, ou com estrutura que não corresponde ao schema atual da Centi. Após corrigir o Content-Type e o HTML-encoding, substitua o conteúdo do campo "xml" pelo XML mais recente, validado pela aba "Estrutura do XML".

// Estrutura correta do body JSON: { "usuario": "seu_usuario", "senha": "sua_senha", "xml": "<?xml version="1.0" encoding="utf-8"?><GerarNfseEnvio xmlns="http://www.centi.com.br/files/nfse.xsd">...</GerarNfseEnvio>" }
Caracteres de controle ou BOM no início do XML
Encoding UTF-8 / BOM
VERIFICAR

Alguns editores ou sistemas salvam arquivos XML com BOM (Byte Order Mark) UTF-8 (EF BB BF) no início. O parser XML do servidor interpreta o BOM como conteúdo inválido, causando erro na posição (1,1). Verifique se o arquivo XML não contém BOM — o conteúdo deve começar exatamente com <?xml ou com a tag raiz, sem caracteres invisíveis antes.

URL da requisição — UF e Tenant corretos
https://api.centi.com.br/nfe/gerar/{UF}/{Tenant}
VERIFICAR

Certifique-se de que a URL contém a UF em minúsculas e o Tenant (nome do município) correto para o prestador. Uma URL apontando para o município errado pode retornar erros de autenticação ou de validação de dados.

// Formato correto: POST https://api.centi.com.br/nfe/gerar/go/rioverde POST https://api.centi.com.br/nfe/cancelar/sp/campinas // Erros comuns: POST https://api.centi.com.br/nfe/gerar/GO/RioVerde ← UF maiúscula POST https://api.centi.com.br/nfe/gerar/go/rio-verde ← hífen no tenant
Resumo — checklist rápido antes de enviar
Conferir sempre antes de reportar erro
RESUMO

Verifique antes de cada envio:

✓ Content-Type: application/json ✓ Campo "xml" contém XML puro — começa com <?xml ou <GerarNfseEnvio ✓ Não há &lt; &gt; &quot; no valor do campo "xml" ✓ XML validado na aba "Estrutura do XML" sem erros ✓ CodigoNbs, CodigoINDOP e CodigoClassTrib estão dentro de Servico e na ordem correta ✓ CodigoINDOP e CodigoClassTrib possuem 6 dígitos numéricos ✓ URL: UF minúscula, Tenant sem acento ou hífen ✓ Credenciais corretas (usuario + senha)