Datasets para validação de notas fiscais

O dataset Documento Fiscal - Acompanhamento (FISCAL_TRACKING) tem como finalidade consultar e coletar dados de autenticidade de documentos fiscais em fontes públicas oficiais (se houver automação compatível disponível).

Esse dataset é uma evolução do serviço Invoice Extraction.

Clique aqui para baixar a última versão da lista de cobertura da consulta de autenticidade.

TIP

Não encontrou o tipo de documento fiscal ou a localidade desejada em nossa lista de cobertura? Entre em contato com nosso Suporte e forneça amostras dos documentos fiscais. Assim, poderemos avaliar a viabilidade de atender a esse tipo de documento ou localidade.

Os tipos de documentos aceitos

O arquivo a ser processado no Content Extraction e consultado no Enrichmento via RPA deve limitar-se a um único documento fiscal por requisição. Essa restrição deve-se ao fato de que a validação e a navegação à fonte oficial ocorre de maneira individualizada para cada requisição."

Tipo	Descrição
NFe	Nota Fiscal Eletrônica (modelo 55).
NFCe	Nota Fiscal de Consumidor Eletrônica (modelo 65).
NFSe	Nota Fiscal de Serviço Eletrônica.
CTe	Conhecimento de Transporte Eletrônico.
NF3e	Nota Fiscal de Energia Elétrica Eletrônica (modelo 66).
MDFe	Documento Auxiliar do MDF-e – Manifesto Eletrônico de Documentos Fiscais.
CIOT	Código Identificador da Operação de Transporte (CIOT) na ANTT.

Parâmetros obrigatórios

É preciso informar, no corpo da requisição ao Enrichment, pelo menos um dos seguintes parâmetros:

mostqiResponse: Resultado em JSON da extração previamente realizada pela rota de Content Extraction, contendo os campos identificados no documento fiscal, bem como o dado ou link presente no QR Code da nota, quando disponível.

mostqiResponseBase64: Resultado da extração realizada pela rota de Content Extraction convertido em Base64, contendo os campos identificados no documento fiscal, bem como o dado ou link presente no QR Code da nota, quando disponível.

Dentre os campos retornados pela extração do Content Extraction, é importante que estejam presentes:

chave_acesso: Chave de acesso com 44 dígitos presente em documentos dos tipos NFe, NFCe, CTe, MDFe e NF3e.

chave_acesso_adn: Chave de acesso com 50 dígitos presente em documentos do tipo NFSe emitidos por municípios aderentes ao Ambiente Nacional e em conformidade com o padrão nacional.

qrcode: QR Code contendo a URL ou os dados necessários para consulta, quando presente no documento fiscal.

Além dos campos acima, no caso de documentos do tipo NFSe, quando não houver nem o qrcode nem a chave_acesso_adn do Ambiente Nacional, a consulta poderá ser realizada por meio de parâmetros textuais, desde que essa modalidade esteja implementada para a localidade consultada.

Nesses cenários, a consulta será baseada no conjunto de informações exigido pela fonte, que pode variar conforme o município ou sistema utilizado. Esse conjunto de dados será identificado automaticamente pela camada de consulta de autenticidade a partir das informações previamente extraídas pela camada de iOCR, como chave_verificacao, inscricao_municipal_prestador, entre outros.

Para consultas de CIOT, é obrigatório que estejam presentes os seguintes campos:

ciot: Código Identificador da Operação de Transporte.

rntrc: Registro Nacional de Transportadores Rodoviários de Cargas.

Sugestão de fluxo

Para otimizar os resultados e automatizar o processo, recomendamos que o dataset FISCAL_TRACKING seja usado em conjunto com a rota Content Extraction, seguindo o fluxo abaixo.

Esse fluxo garante maior precisão e eficiência na análise dos documentos fiscais.

Etapa 1: Extração de Dados

Envie o documento fiscal para a rota Content Extraction para realizar a extração das informações.

TIP

💡 Importante: Certifique-se de definir o atributo returnMetadata da rota Content Extraction como verdadeiro!

Isso permite a extração de QR Codes presentes em documentos fiscais, mesmo para modelos não treinados pelo mostQI, ampliando significativamente a abrangência e a relevância do dataset FISCAL_TRACKING.

Etapa 2: Enriquecimento de Dados

Na requisição ao serviço Enrichment, inserir:

O response da rota Content Extraction (JSON) no atributo mostqiResponse.

O nome da consulta (query) FISCAL_TRACKING no atributo query.

Exemplo do corpo de requisição para a chamada ao Enrichment

Envie no parâmetro mostqiResponse o conteúdo completo retornado pela rota de Content Extraction.

{
  "query":"FISCAL_TRACKING",
  "parameters":{
     "mostqiResponse":{
        "result":[
           "..."
        ],
        "metadata":{
           "barcodes":[
              {
                 "kind":"qrcode",
                 "page":1,
                 "value":"https://..."
              }
           ]
        },
        "requestId":"ifG31hTBAHS1pXTMTczXF",
        "elapsedMilliseconds":10370,
        "status":{
           "message":"Ok",
           "code":"200",
           "errors":[
              
           ]
        }
     }
  }
}

INFO

Uma query pode incluir um ou mais datasets. Os nomes das consultas (queries) são definidos pelo Suporte da MOST ou pelo próprio cliente.

A query FISCAL_TRACKING foi criada especificamente para retornar os dados do dataset FISCAL_TRACKING. No entanto, é fundamental ressaltar que o nome da query nem sempre será idêntico ao nome do dataset que ela contém.

Dados retornados

Os dados retornados variam de acordo com as informações disponibilizadas pela fonte oficial correspondente a cada tipo de documento fiscal e/ou localidade.
As informações coletadas estarão organizadas nos objetos fields e tables, cada um contendo duas identificações:

name: apresenta o nome do campo padronizado.

sourceName: apresenta o título original do campo conforme disponibilizado pela fonte oficial.

Veja o exemplo abaixo com um trecho de retorno:

{
    "result": {
        "processId": "ff1d10bb-8800-4dd5-be1e-a0b18c4306a9",
        "tier": "FISCAL_TRACKING",
        "query": "FISCAL_TRACKING",
        "status": "DONE",
        "parameters": {
            "mostqiResponse": {
                "result": [...]
            }
        },
        "datasets": [
            {
                "name": "fiscal_tracking",
                "code": "fiscal_tracking_ondemand_fiscal_817669",
                "status": "DONE",
                "fromCache": false,
                "errors": [],
                "data": [
                    {
                        "type": "documento-fiscal",
                        "stdType": null,
                        "score": null,
                        "tags": null,
                        "extractions": [
                            {
                                "source": "official",
                                "score": null,
                                "tags": [
                                    "country=bra",
                                    "goal=query",
                                    "has=address",
                                    "id=bra-fiscal-nfse-40305-1",
                                    "language=pt-BR",
                                    "of=service",
                                    "std-type=fiscal-document",
                                    "subtype=invoice",
                                    "subtype=nfse",
                                    "type=documento-fiscal"
                                ],
                                "sections": [
                                    {
                                        "name": null,
                                        "score": 1,
                                        "pages": [
                                            {
                                                "number": 1
                                            }
                                        ],
                                        "fields": [
                                            {
                                                "name": "autenticidade_nota",
                                                "sourceName": "autenticidade da nota",
                                                "value": "1",
                                                "score": 1
                                            },
                                            {
                                                "name": "url",
                                                "sourceName": "url",
                                                "value": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprint.aspx?inscricao=999999&nf=00099999&verificacao=ZZZZZZZZ",
                                                "score": 1
                                            },
                                            {
                                                "name": "situacao_tipo",
                                                "sourceName": null,
                                                "value": "autorizada",
                                                "score": 1
                                            },
                                            {
                                                "name": "download",
                                                "sourceName": null,
                                                "value": "JVB...",
                                                "score": 1
                                            },
                                            {
                                                "name": "download_mimetype",
                                                "sourceName": null,
                                                "value": "application/pdf",
                                                "score": 1
                                            }
                                        ],
                                        "tables": []
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "requestId": "rD3YITSfgl2vNNvg7QYmy",
    "elapsedMilliseconds": 10527,
    "status": {
        "message": "Ok",
        "code": "200",
        "errors": null
    }
}

INFO

Se houver automação compatível para a nota processada pelo iOCR, será realizada a navegação para a consulta do documento fiscal na fonte oficial. No entanto, se o documento não for encontrado na fonte, o resultado da fonte "official" não será retornado, exceto para casos em que a fonte explicitar se tratar de uma nota falsificada ou inválida.

Dicionário de dados: `autenticidade_nota` e `situacao_tipo`

Se a nota for encontrada na fonte, além dos campos coletados, o atributo autenticidade_nota será retornado com o valor "1".

            {
              "name": "autenticidade_nota",
              "value": "1",
              "score": 1
            }

Se a nota não for encontrada na fonte, mas a fonte retornar explicitamente que se trata de uma nota falsificada ou inválida, o resultado da fonte "official" será retornado com o atributo autenticidade_nota definido como "0".

            {
              "name": "autenticidade_nota",
              "value": "0",
              "score": 1
            }

Além do atributo autenticidade_nota, abaixo estão os campos que compõem o bloco de situação e status da nota fiscal eletrônica.

Campo	Tipo	Descrição	Exemplo
situacao_tipo	String	Status simplificado e padronizado da nota. É o principal campo para validar a situação fiscal atual do documento.	"normal", "autorizada", "cancelada", "substituida", null (quando a informação não é explicitamente disponibilizada pela fonte ou não pode ser coletada de forma automatizada).
situacao_data	Datetime	Data e hora em que ocorreu a última alteração de status na prefeitura de origem.	"2026-05-25T14:15:00Z", null (quando a informação não é explicitamente disponibilizada pela fonte ou não pode ser coletada de forma automatizada).
situacao_motivo	String	A justificativa ou razão atrelada ao status atual do documento.	"Cancelada pelo emitente", null (quando a informação não é explicitamente disponibilizada pela fonte ou não pode ser coletada de forma automatizada).
situacao	String	Texto descritivo bruto retornado diretamente pela fonte (prefeitura), frequentemente consolidando a data e o motivo.	"Nota Cancelada em DD/MM/AAAA - Motivo: Cancelada e substituída pela nota NNNNN", null (quando a informação não é explicitamente disponibilizada pela fonte ou não pode ser coletada de forma automatizada).

Boas práticas e fluxo de análise recomendado

Atenção: O fato de uma nota ter sido localizada (retornando autenticidade_nota: 1) não garante que ela esteja ativa ou seja válida para fins fiscais. Sempre realize uma análise combinada dos campos retornados e, quando disponível no resultado, também dos artefatos adicionais, como imagens, XML ou PDF do documento fiscal.

Fluxo de verificação lógica

Validação de existência: Certifique-se de que o campo autenticidade_nota possui o valor 1.

Validação de status: Se a nota existe, examine a chave situacao_tipo para determinar se o documento está ativo ("autorizada", "normal"), inativo ("cancelada", "substituida") ou se não foi possível determinar a situação (null).

Tratamento de dados ausentes (null)

Devido à falta de padronização das fontes municipais, o status pode não ser retornado de forma estruturada. Caso situacao_tipo retorne null, adote os seguintes passos de contingência:

Análise de texto livre: Inspecione os demais campos textuais do payload, com especial atenção ao campo observacoes.

Verificação visual (arquivo): Acesse o link retornado no campo url ou o arquivo binário em base64. Algumas prefeituras não disponibilizam o status de forma explicita e pesquisável no resultado da consulta de autenticidade, mas aplicam uma marca d'água ou carimbo de "Cancelada" diretamente no PDF/Imagem do documento.

Comportamento em caso de erro na fonte

Caso o sistema encontre instabilidades na origem (ex: site da prefeitura indisponível, timeout) ou receba parâmetros inválidos, a API priorizará o retorno da mensagem de erro original da fonte no corpo da resposta.

Clique aqui para baixar a última versão da lista de cobertura da consulta de autenticidade.

TIP

Não encontrou o tipo de documento fiscal ou a localidade desejada em nossa lista de cobertura? Entre em contato com nosso Suporte e forneça amostras dos documentos fiscais. Assim, poderemos avaliar a viabilidade de atender a esse tipo de documento ou localidade.

Dataset de Documentos Fiscais

Os tipos de documentos aceitos#

Parâmetros obrigatórios#

Sugestão de fluxo#

Exemplo do corpo de requisição para a chamada ao Enrichment#

Dados retornados#

Dicionário de dados: autenticidade_nota e situacao_tipo#

Boas práticas e fluxo de análise recomendado#

Fluxo de verificação lógica#

Tratamento de dados ausentes (null)#

Comportamento em caso de erro na fonte#

Os tipos de documentos aceitos

Parâmetros obrigatórios

Sugestão de fluxo

Exemplo do corpo de requisição para a chamada ao Enrichment

Dados retornados

Dicionário de dados: `autenticidade_nota` e `situacao_tipo`

Boas práticas e fluxo de análise recomendado

Fluxo de verificação lógica

Tratamento de dados ausentes (null)

Comportamento em caso de erro na fonte