WEB SERVICE Eticons - NFS-e

Documentação API V2

Implementação para novos clientes e Migração da API V1 para a V2

Uso em homologação

Utilize credenciais e dados próprios de homologação. Não execute testes com tokens ou documentos de produção.

Sumário

1. Escopo e status desta versão

2. Autenticação e convenções HTTP

3. Conceitos e identificadores importantes

4. Consultas e rastreabilidade

5. Cancelamento de NFS-e - contrato preliminar

6. Envio de lotes de NFS-e

7. Contratos de resposta e tratamento de erros

8. Reenvio após correção de nota rejeitada

9. Referência completa dos campos do payload

10. Checklist de homologação

Exemplos protegidos

Todos os dados de pessoas, empresas, documentos, contatos, lotes e valores utilizados nos exemplos são fictícios e meramente ilustrativos.

1. Escopo e status desta versão

Este material orienta clientes que iniciarão a migração da API V1 para a API V2 do Web Service NFS-e Eticons. O conteúdo apresenta autenticação, endpoints, payload atualizado, campos do leiaute e contratos de retorno relevantes para a integração do cliente.

Versõesr

A implementação das versões e das regras da API V2: Campos, validações, obrigatoriedades e respostas poderão sofrer ajustes a depender dos ajsutes realizados pelo ADN Nacional.

O que este documento não expõe

• Regras operacionais internas que não alteram o contrato de comunicação do cliente.

• Dados reais utilizados durante desenvolvimento, validação ou suporte.

2. Autenticação e convenções HTTP

Todas as requisições devem utilizar o token fornecido pela Eticons no cabeçalho Authorization, no padrão Bearer. O token deve ser armazenado de forma segura e nunca incluído em logs públicos, chamados de suporte sem proteção ou código-fonte versionado. A solicitação do token deve dado a partir dos contatos: +55 83 8149-1192 ou pelo E-mail: suportetributos@e-ticons.com.br.

Authorization: Bearer <TOKEN_FORNECIDO_PELA_ETICONS>
Content-Type: application/json
Accept: application/json

3. Conceitos e identificadores importantes

Não confunda os identificadores

O número original enviado pelo cliente não é o numeroControleWs. O numeroControleWs é criado e devolvido pela Eticons para acompanhamento posterior do documento.

4. Consultas e rastreabilidade

4.1 Buscar NFS-e por NSU

GET https://webservice2.e-ticons.com.br/api/ws/v2/nfse/nsu/1/2/3550308

4.2 Consultar eventos por chave de acesso

GET https://webservice2.e-ticons.com.br/api/ws/v2/nfse/eventos/<CHAVE_DE_50_DIGITOS>/2/3550308

5. Cancelamento de NFS-e - contrato preliminar

Atenção

O cancelamento V2 ainda está em desenvolvimento. A estrutura abaixo representa o contrato previsto e poderá ser ajustada antes da disponibilização definitiva.

5.1 Exemplo para documento emitido na V2

{
  "numeroControleWs": "0002507",
  "chaveDeAcesso": "<CHAVE_DE_50_DIGITOS>",
  "ibge": "3550308",
  "tpAmb": 2,
  "ambGer": 1,
  "cMotivo": 1,
  "xMotivo": "Erro na emissão: valores tributários informados incorretamente.",
  "CnpjCpfAutor": "00000000000000",
  "nDFSe": "9001"
}

5.2 Compatibilidade com documento originado na V1

Documentos originados na V1 não receberam numeroControleWs no contrato anterior. Para esses casos, o campo deverá aceitar ausência ou null. Para documentos emitidos na V2, utilize sempre o numeroControleWs devolvido na emissão.

{
  "numeroControleWs": null,
  "chaveDeAcesso": "<CHAVE_DE_50_DIGITOS>",
  "ibge": "3550308",
  "tpAmb": 2,
  "ambGer": 1,
  "cMotivo": 1,
  "xMotivo": "Erro na emissão: valores tributários informados incorretamente.",
  "CnpjCpfAutor": "00000000000000",
  "nDFSe": "9001"
}

6. Envio de lotes de NFS-e

O payload abaixo substitui integralmente o exemplo de emissão da versão anterior deste manual. Todos os campos e agrupadores apresentados fazem parte do contrato preliminar atual.

Dados fictícios

Os valores abaixo servem somente para demonstrar estrutura e tipos. Documentos, contatos e nomes são fictícios; substitua-os por dados válidos de homologação.

6.1 Payload completo e anonimizado

{
  "eticonsSystem": "NFW",
  "versao": "1.01",
  "versaoLote": "1.01",
  "tpAmb": 2,
  "idLote": "LOTE-HML-000001",
  "CNPJEmissor": "00000000000000",
  "dhTrans": "2026-09-01T10:00:00-03:00",
  "notas": [
    {
      "infNFSe": {
        "versao": "1.01",
        "xLocEmi": "MUNICIPIO EXEMPLO",
        "xLocPrestacao": "3550308",
        "nNFSe": "0009001",
        "cLocIncid": "3550308",
        "xLocIncid": "MUNICIPIO EXEMPLO",
        "xTribNac": "Descricao do servico conforme tributacao nacional.",
        "xNBS": "Descricao do servico conforme a NBS.",
        "verAplic": "1.0",
        "ambGer": 1,
        "tpEmis": 1,
        "cStat": 100,
        "dhProc": "2026-09-01T10:00:00-03:00",
        "nDFSe": 9001,
        "emit": {
          "im": "12345",
          "xNome": "EMPRESA PRESTADORA EXEMPLO LTDA",
          "fone": "11999999999",
          "email": "fiscal@example.com",
          "enderNac": {
            "xLgr": "RUA EXEMPLO",
            "nro": "100",
            "xBairro": "CENTRO",
            "cMun": "3550308",
            "UF": "SP",
            "CEP": "01001000"
          },
          "CnpjCpf": "00000000000000"
        },
        "valores": {
          "pAliqAplic": 2,
          "vISSQN": 2,
          "vLiq": 98,
          "vTotalRet": 2,
          "vDescIncond": 0,
          "vDescCond": 0,
          "vBC": 100
        },
        "IBSCBS": {
          "cLocalidadeIncid": "3550308",
          "xLocalidadeIncid": "MUNICIPIO EXEMPLO/SP",
          "valores": {
            "vBC": 100,
            "uf": {
              "pIBSUF": 0.1,
              "pRedAliqUF": 0,
              "pAliqEfetUF": 0.1
            },
            "mun": {
              "pIBSMun": 0,
              "pRedAliqMun": 0,
              "pAliqEfetMun": 0
            },
            "fed": {
              "pCBS": 0.9,
              "pRedAliqCBS": 0,
              "pAliqEfetCBS": 0.9
            }
          },
          "totCIBS": {
            "vTotNF": 100,
            "gIBS": {
              "vIBSTot": 0.1,
              "gIBSUFTot": {
                "vIBSUF": 0.1
              },
              "gIBSMunTot": {
                "vIBSMun": 0
              }
            },
            "gCBS": {
              "vCBS": 0.9
            }
          }
        },
        "DPS": {
          "versao": "1.01",
          "infDPS": {
            "tpAmb": 2,
            "dhEmi": "2026-09-01T10:00:00-03:00",
            "verAplic": "1.0",
            "serie": "1",
            "nDPS": "9001",
            "dCompet": "2026-09-01",
            "tpEmit": 1,
            "cLocEmi": "3550308",
            "prest": {
              "regTrib": {
                "opSimpNac": 3,
                "regEspTrib": 0,
                "regApTribSN": 1
              },
              "IM": "12345",
              "CnpjCpf": "00000000000000"
            },
            "toma": {
              "fone": "",
              "email": "contato@example.com",
              "end": {
                "endNac": {
                  "cMun": "3550308",
                  "CEP": "01001000"
                },
                "nro": "200",
                "xBairro": "CENTRO",
                "xLgr": "AVENIDA EXEMPLO"
              },
              "IM": "",
              "CnpjCpf": "00000000000000",
              "xNome": "TOMADOR EXEMPLO LTDA"
            },
            "serv": {
              "locPrest": {
                "cLocPrestacao": "3550308"
              },
              "obra": null,
              "infoCompl": {
                "xInfComp": ""
              },
              "cServ": {
                "xDescServ": "Servico prestado para fins de homologacao.",
                "cTribNac": "010101",
                "cNBS": "115071000",
                "cTribMun": "001"
              }
            },
            "valores": {
              "trib": {
                "tribMun": {
                  "tribISSQN": 1,
                  "tpRetISSQN": 1
                },
                "tribFed": {
                  "piscofins": {
                    "tpRetPisCofins": "0",
                    "CST": "00"
                  },
                  "vRetCP": 0,
                  "vRetIRRF": 0,
                  "vRetCSLL": 0
                },
                "totTrib": {
                  "vTotTrib": {
                    "vTotTribEst": 0,
                    "vTotTribFed": 0,
                    "vTotTribMun": 0
                  }
                }
              },
              "vDedRed": {
                "vDR": 0
              },
              "vServPrest": {
                "vServ": 100
              }
            },
            "IBSCBS": {
              "finNFSe": 0,
              "tpOper": null,
              "cIndOp": "100301",
              "indDest": 0,
              "gRefNFSe": {
                "refNFSe": null
              },
              "imovel": {
                "inscImobFisc": null,
                "cCIB": null,
                "CEP": null,
                "xLgr": null,
                "nro": null,
                "xCpl": null,
                "xBairro": null
              },
              "valores": {
                "trib": {
                  "gIBSCBS": {
                    "cClassTrib": "000001",
                    "CST": "000"
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}

7. Contratos de resposta e tratamento de erros

7.1 Nota autorizada

{
  "mensagem": "Lote processado pelo ADN.",
  "idLote": "LOTE-HML-000001",
  "instituicao": "MUNICIPIO EXEMPLO",
  "ibgeInstituicao": "3550308",
  "notas": [
    {
      "status": "Autorizado",
      "numeroControleWs": "0002507",
      "chaveAcesso": "<CHAVE_DE_50_DIGITOS>",
      "nsuRecepcao": "197",
      "xmlNFSe": "<XML_NFSE_BASE64_OU_CONTEUDO_CONFORME_CONTRATO>"
    }
  ]
}

7.2 Nota rejeitada

{
  "mensagem": "Lote processado pelo ADN.",
  "idLote": "LOTE-HML-000001",
  "instituicao": "MUNICIPIO EXEMPLO",
  "ibgeInstituicao": "3550308",
  "notas": [
    {
      "status": "Rejeitado",
      "numeroControleWs": "0002507",
      "chaveAcesso": null,
      "nsuRecepcao": null,
      "xmlNFSe": "<XML_RETORNADO_QUANDO_DISPONIVEL>",
      "codigoErro": "E0000",
      "mensagemErro": "Descrição ilustrativa da rejeição.",
      "complemento": ""
    }
  ]
}

Controle preservado

O numeroControleWs é retornado mesmo quando a nota é rejeitada. Se a mesma nota for corrigida e reenviada, esse número permanece inalterado.

7.3 Respostas HTTP

7.4 Indisponibilidade do ADN - HTTP 503

{
  "erro": "ADN_FORA_DO_AR",
  "mensagem": "O servidor do ADN não está respondendo."
}

8. Reenvio após correção de nota rejeitada

Uma nota rejeitada pode ser corrigida e enviada novamente. Para que a API reconheça que se trata do mesmo documento, preserve o identificador original do cliente e altere somente os dados que precisam de correção.

• Mantenha os mesmos valores de nNFSe e nDFSe para a mesma nota rejeitada.

• Não crie um novo identificador apenas para contornar uma rejeição.

• Corrija os campos apontados na resposta do ADN.

• Guarde o numeroControleWs devolvido; ele continuará representando a mesma NFS-e.

• Uma nota já autorizada não deve ser reenviada como se fosse nova.

Regra de identidade

Rejeição + correção + reenvio representam o mesmo documento. O número de controle da Eticons não muda.

9. Referência completa dos campos do payload

As tabelas a seguir reproduzem os campos do payload preliminar atualizado. Quando houver correspondência, tipo, ocorrência, tamanho, descrição e notas explicativas foram obtidos do leiaute DPS/NFS-e nacional fornecido. Campos do envelope Eticons e adaptações do contrato JSON são identificados no texto.

9.1 Envelope do lote

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.2 NFS-e - identificação

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.3 NFS-e - emitente

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.4 NFS-e - valores

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.5 NFS-e - IBS/CBS e totais

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.6 DPS - identificação

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.7 DPS - prestador e regime tributário

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.8 DPS - tomador e endereço

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.9 DPS - serviço

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.10 DPS - valores e tributos

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

9.11 DPS - IBS/CBS

Ocorrência e tamanho seguem o leiaute nacional quando houver correspondência. A ocorrência é relativa ao grupo pai.

10. Checklist de homologação

• Obter e armazenar com segurança o token de homologação.
• Enviar Authorization Bearer, Content-Type e Accept em todas as requisições.
• Utilizar eticonsSystem = "NFW" e tpAmb = 2 durante os testes.
• Usar identificadores de lote únicos e manter nNFSe/nDFSe na correção da mesma nota.
• Validar códigos IBGE, CPF/CNPJ, CEP, códigos de serviço, NBS e dados tributários antes do envio.
• Tratar o status de cada nota do lote, não apenas o status HTTP global.
• Persistir numeroControleWs, chaveAcesso e nsuRecepcao retornados.
• Não reenviar como nova uma nota já autorizada.
• Executar cenários de autorização, rejeição, correção/reenvio, indisponibilidade e cancelamento preliminar.
• Aguardar a versão definitiva antes de congelar regras de cancelamento em produção.

Controle de versão

Próxima publicação

A Eticons disponibilizará novas versões sempre que necessário e acompanhando as novas regras e implementações da NFSe Nacional.