---
id: nfce
title: Importação de NFC-e
description: Importação assíncrona de dados fiscais do SVRS para rascunhos de transações.
type: feature
status: observed
visibility: public
tags: finanças, nfce, importação
related: financas, transacoes, automacoes, deploy
source_refs: https://github.com/james-suite/james/blob/master/app/Jobs/ScrapeNfceInvoiceJob.php, https://github.com/james-suite/james/blob/master/routes/financial.php
---

## Visão geral

O módulo de importação de **Nota Fiscal de Consumidor eletrônica (NFC-e)** transforma uma URL pública de consulta em um rascunho de transação financeira. A importação consulta o portal fiscal, extrai os dados da nota e deixa a confirmação da conta, cartão e status para a revisão do usuário.

Atualmente o provedor suportado é o **SVRS** (Sefaz Virtual do Rio Grande do Sul), com resolução preparada para receber novos portais no futuro.

## Fluxo de uso

1. Abra `Finanças > Transações > Nova Transação`.
2. Clique em **Importar NFC-e**.
3. Escolha uma das formas de informar a nota:
   - cole ou digite a URL pública do QR Code;
   - use **Colar URL** para ler a área de transferência; ou
   - clique em **Ler QR Code** para usar a câmera do dispositivo.
4. Envie a solicitação.
5. O sistema redireciona imediatamente para a listagem e coloca a consulta na fila.
6. Após o processamento, uma notificação abre a edição do rascunho.
7. Revise os dados, escolha uma conta ou cartão e salve a transação.

O botão de importação bloqueia envios duplicados enquanto a solicitação atual está sendo enviada. Após uma leitura válida pela câmera, a URL é preenchida no formulário para conferência antes do envio.

Quando o processamento falha, a notificação exibida na central e nos canais configurados traz a ação **Tentar novamente**. Esse reenvio é protegido, pertence somente ao usuário que iniciou a importação e não cria outra transação caso a NFC-e já tenha sido importada.

## Dados importados

O rascunho pode conter:

- emitente e documento do emitente (CPF/CNPJ);
- data de emissão;
- valor total e desconto;
- itens, quantidade, preço unitário e total;
- chave de acesso de 44 dígitos;
- URL completa normalizada do portal.

O documento do emitente é armazenado apenas com dígitos e formatado na apresentação. A URL completa normalizada, incluindo o parâmetro da NFC-e, é armazenada para permitir a consulta posterior da mesma nota; ela não é incluída em logs.

## Status e impacto financeiro

Toda NFC-e importada começa como `draft` (rascunho). Enquanto estiver nesse status, ela não participa de:

- saldo de contas;
- limite utilizado e totais de faturas de cartão;
- dashboard, relatórios e resumos;
- alertas de vencimento e rotinas automáticas.

Ao revisar a transação:

- vinculá-la a uma conta permite salvá-la como `posted` (efetivada) ou `pending` (pendente);
- vinculá-la a um cartão resolve a fatura correspondente e salva a compra como `pending`;
- o pagamento da fatura posteriormente promove as compras elegíveis para `posted`.

## Processamento assíncrono

O endpoint autenticado apenas valida a URL, verifica duplicidade pela chave de acesso e despacha `ScrapeNfceInvoiceJob`. O job:

- é único por chave fiscal;
- possui três tentativas e backoff de `5`, `15` e `30` segundos;
- usa timeout de 90 segundos;
- grava a transação e seus itens em uma única transação de banco;
- envia notificações pelos canais Database e Telegram.

Em produção, o worker da fila precisa estar ativo no Supervisor. Consulte o [Guia de Deploy](doc:deploy#7-schedulers-e-processos-em-background-supervisor) para a configuração de `james-worker` e do `schedule:work`.

## Segurança e limitações

O resolvedor aceita somente provedores configurados e hosts HTTPS autorizados, rejeitando formatos incompatíveis e destinos não permitidos. Para o SVRS, são aceitas as URLs públicas atuais do portal DFe e as URLs legadas do portal da Sefaz-RS; ambas são consultadas no endpoint compatível do SVRS. O leitor também reconhece variações de layout do portal, incluindo notas com frete destacado.

As ações **Colar URL** e **Ler QR Code** exigem uma conexão HTTPS e as permissões correspondentes do navegador. Se a área de transferência ou a câmera não estiverem disponíveis, negadas ou em uso por outro aplicativo, informe a URL manualmente. O QR Code só preenche o campo quando contém uma URL HTTPS válida de NFC-e com chave de acesso de 44 dígitos.

A implementação não inclui OCR, navegador automatizado ou histórico de tentativas.