UUID de documento

O que significa UUID?

UUID é a sigla em inglês para Universally Unique Identifier, ou identificador universalmente único. Trata-se de um padrão para criar códigos de 128 bits, normalmente escritos como 32 caracteres hexadecimais (números de 0 a 9 e letras de a até f) divididos em cinco grupos separados por hífens, como 3f2a9c1e-7b4d-4e8a-9c21-5d6f0a1b2c3d.

A grande vantagem do UUID é que ele pode ser gerado por qualquer sistema, sem consultar um cadastro central, com uma chance de repetição tão pequena que, na prática, é desconsiderada. Por isso ele é muito usado para identificar registros em bancos de dados e recursos em APIs.

Para que serve o UUID de documento na emissão fiscal?

Quando um sistema envia os dados de uma nota para uma API fiscal, a autorização pela SEFAZ ou pela prefeitura nem sempre acontece na hora. Em um fluxo assíncrono, a API recebe o pedido, devolve imediatamente um UUID e continua o processamento em segundo plano.

A partir daí, esse código vira a referência do documento dentro da integração: é com ele que o sistema consulta o status, recebe notificações por webhook, baixa o XML e o PDF, solicita cancelamento ou investiga uma rejeição. Ele funciona como o número de protocolo de um atendimento, que acompanha o caso do início ao fim.

Qual a diferença entre UUID, chave de acesso e número da nota?

O número e a série da nota são sequenciais e controlados por cada emitente, conforme as regras fiscais. A chave de acesso da NF-e, NFC-e, CT-e e MDF-e é um código oficial de 44 dígitos que identifica o documento perante o fisco e aparece no DANFE e em consultas públicas. Na NFS-e, a identificação oficial depende do padrão adotado pelo município ou pelo Padrão Nacional.

Já o UUID é um identificador técnico da plataforma de emissão. Ele não é impresso no documento auxiliar, não tem validade jurídica e não serve para consulta na SEFAZ ou na prefeitura. Sua função é organizar a comunicação entre o sistema do cliente e a API.

Por que não usar apenas o número da nota como identificador?

O número fiscal pode não ser suficiente para identificar um documento na integração. Em uma API que atende várias empresas, dois CNPJs diferentes podem ter notas com o mesmo número e série. Além disso, em alguns modelos, como certas NFS-e, o número oficial só é conhecido depois da autorização.

O UUID resolve esses casos porque existe desde a criação do pedido de emissão e é único em toda a plataforma, independentemente da empresa, do tipo de documento ou da situação da nota, seja ela autorizada, rejeitada ou ainda em processamento.

Como o sistema deve guardar e usar o UUID?

A prática recomendada é salvar o UUID no banco de dados do sistema logo após o envio, vinculado ao pedido, venda ou ordem de serviço que originou a nota. Assim, qualquer consulta futura pode ser feita direto pelo identificador, sem buscas por filtros amplos.

Também é útil registrar o UUID nos logs de integração, o que facilita o suporte e a auditoria. Em integrações com agentes de inteligência artificial via MCP, o UUID permite que o agente consulte ou execute ações sobre um documento específico, sem ambiguidade.

Exemplos de UUID de documento

• Um ERP envia os dados de uma NF-e para a API fiscal, recebe como resposta o UUID do documento com status em processamento e grava esse código junto ao pedido de venda.
• Uma plataforma de e-commerce recebe um webhook informando que a NFC-e foi autorizada; pelo UUID contido na notificação, ela identifica a venda correspondente e libera o envio do PDF ao cliente.
• O time de suporte de um software de gestão recebe a reclamação de uma nota rejeitada e localiza o problema no Console buscando pelo UUID registrado no log da integração.
• Um agente de IA conectado via MCP recebe o pedido de verificar uma NFS-e e usa o UUID do documento para consultar o status e o motivo da rejeição.