{
  "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"
  ],
  "sourceRefs": [
    "https://github.com/james-suite/james/blob/master/app/Jobs/ScrapeNfceInvoiceJob.php",
    "https://github.com/james-suite/james/blob/master/routes/financial.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Visão geral\n\nO 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.\n\nAtualmente o provedor suportado é o **SVRS** (Sefaz Virtual do Rio Grande do Sul), com resolução preparada para receber novos portais no futuro.\n\n## Fluxo de uso\n\n1. Abra `Finanças > Transações > Nova Transação`.\n2. Clique em **Importar NFC-e**.\n3. Escolha uma das formas de informar a nota:\n   - cole ou digite a URL pública do QR Code;\n   - use **Colar URL** para ler a área de transferência; ou\n   - clique em **Ler QR Code** para usar a câmera do dispositivo.\n4. Envie a solicitação.\n5. O sistema redireciona imediatamente para a listagem e coloca a consulta na fila.\n6. Após o processamento, uma notificação abre a edição do rascunho.\n7. Revise os dados, escolha uma conta ou cartão e salve a transação.\n\nO 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.\n\nQuando 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.\n\n## Dados importados\n\nO rascunho pode conter:\n\n- emitente e documento do emitente (CPF/CNPJ);\n- data de emissão;\n- valor total e desconto;\n- itens, quantidade, preço unitário e total;\n- chave de acesso de 44 dígitos;\n- URL completa normalizada do portal.\n\nO 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.\n\n## Status e impacto financeiro\n\nToda NFC-e importada começa como `draft` (rascunho). Enquanto estiver nesse status, ela não participa de:\n\n- saldo de contas;\n- limite utilizado e totais de faturas de cartão;\n- dashboard, relatórios e resumos;\n- alertas de vencimento e rotinas automáticas.\n\nAo revisar a transação:\n\n- vinculá-la a uma conta permite salvá-la como `posted` (efetivada) ou `pending` (pendente);\n- vinculá-la a um cartão resolve a fatura correspondente e salva a compra como `pending`;\n- o pagamento da fatura posteriormente promove as compras elegíveis para `posted`.\n\n## Processamento assíncrono\n\nO endpoint autenticado apenas valida a URL, verifica duplicidade pela chave de acesso e despacha `ScrapeNfceInvoiceJob`. O job:\n\n- é único por chave fiscal;\n- possui três tentativas e backoff de `5`, `15` e `30` segundos;\n- usa timeout de 90 segundos;\n- grava a transação e seus itens em uma única transação de banco;\n- envia notificações pelos canais Database e Telegram.\n\nEm 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`.\n\n## Segurança e limitações\n\nO 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.\n\nAs 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.\n\nA implementação não inclui OCR, navegador automatizado ou histórico de tentativas.",
  "sections": [
    {
      "id": "visao-geral",
      "level": 2,
      "title": "Visão geral",
      "text": "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.",
      "line": 1
    },
    {
      "id": "fluxo-de-uso",
      "level": 2,
      "title": "Fluxo de uso",
      "text": "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.",
      "line": 7
    },
    {
      "id": "dados-importados",
      "level": 2,
      "title": "Dados importados",
      "text": "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.",
      "line": 24
    },
    {
      "id": "status-e-impacto-financeiro",
      "level": 2,
      "title": "Status e impacto financeiro",
      "text": "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`.",
      "line": 37
    },
    {
      "id": "processamento-assincrono",
      "level": 2,
      "title": "Processamento assíncrono",
      "text": "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`.",
      "line": 52
    },
    {
      "id": "seguranca-e-limitacoes",
      "level": 2,
      "title": "Segurança e limitações",
      "text": "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.",
      "line": 64
    }
  ],
  "sourcePath": "content/nfce.md",
  "visuals": [],
  "apiVersion": 1
}