ghinfe 0.6.0

package/docs/openapi.yaml

@@ -0,0 +1,428 @@
+openapi: 3.0.3
+info:
+  title: GHINFE API
+  description: |
+    API de testes da biblioteca GHINFE para emissão de NF-e.
+    Use os endpoints em modo mock para validar integração sem certificado real.
+  version: 0.6.0
+  contact:
+    name: GHINFE
+servers:
+  - url: http://localhost:3333
+    description: Servidor local de desenvolvimento
+
+tags:
+  - name: NF-e
+    description: Operações de Nota Fiscal Eletrônica
+  - name: NFC-e
+    description: Cupom Fiscal Eletrônico (modelo 65)
+  - name: NFS-e
+    description: Nota Fiscal de Serviço Eletrônica
+  - name: SEFAZ
+    description: Endpoints e status SEFAZ
+  - name: Reforma
+    description: IBS/CBS (base PL_010)
+  - name: Sistema
+    description: Health check e informações
+
+paths:
+  /health:
+    get:
+      tags: [Sistema]
+      summary: Health check
+      responses:
+        '200':
+          description: API operacional
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+                  library:
+                    type: string
+                    example: ghinfe
+
+  /nfe/xml:
+    post:
+      tags: [NF-e]
+      summary: Gerar XML da NF-e
+      description: Monta o XML conforme layout SEFAZ 4.00 a partir do objeto de domínio.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NFeDocumento'
+      responses:
+        '200':
+          description: XML gerado com sucesso
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  chaveAcesso:
+                    type: string
+                  xml:
+                    type: string
+        '400':
+          $ref: '#/components/responses/ErroValidacao'
+
+  /nfe/validar-xsd:
+    post:
+      tags: [NF-e]
+      summary: Validar XML contra XSD
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [xml]
+              properties:
+                xml: { type: string }
+      responses:
+        '200':
+          description: XML válido
+        '422':
+          description: Erro de validação XSD
+
+  /nfce/xml:
+    post:
+      tags: [NFC-e]
+      summary: Gerar XML NFC-e (modelo 65)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NFCeDocumento'
+      responses:
+        '200':
+          description: XML gerado
+
+  /nfce/enviar-mock:
+    post:
+      tags: [NFC-e]
+      summary: Enviar NFC-e (mock SEFAZ)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NFCeDocumento'
+      responses:
+        '200':
+          description: Retorno mock
+
+  /nfe/chave:
+    post:
+      tags: [NF-e]
+      summary: Gerar chave de acesso
+      description: Gera chave NF-e de 44 dígitos com DV módulo 11.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [uf, cnpj, serie, numero]
+              properties:
+                uf: { type: string, example: 'SP' }
+                cnpj: { type: string, example: '12345678000199' }
+                modelo: { type: string, example: '55' }
+                serie: { type: integer, example: 1 }
+                numero: { type: integer, example: 42 }
+                tipoEmissao: { type: integer, example: 1 }
+                codigoNumerico: { type: string, example: '12345678' }
+      responses:
+        '200':
+          description: Chave gerada
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  chaveAcesso: { type: string }
+                  valida: { type: boolean, example: true }
+
+  /nfe/cancelar-mock:
+    post:
+      tags: [NF-e]
+      summary: Cancelar NF-e (mock)
+      description: Gera XML do evento 110111 e simula retorno SEFAZ.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NFeCancelamento'
+      responses:
+        '200':
+          description: Evento registrado (mock)
+        '422':
+          $ref: '#/components/responses/ErroSefaz'
+
+  /nfe/cce-mock:
+    post:
+      tags: [NF-e]
+      summary: Carta de Correção (mock)
+      description: Gera XML do evento 110110 e simula retorno SEFAZ.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NFeCartaCorrecao'
+      responses:
+        '200':
+          description: Evento registrado (mock)
+        '422':
+          $ref: '#/components/responses/ErroSefaz'
+
+  /nfe/enviar-mock:
+    post:
+      tags: [NF-e]
+      summary: Enviar NF-e (mock SEFAZ)
+      description: |
+        Gera XML, simula assinatura e envia para mock da SEFAZ.
+        Útil para testar fluxo completo sem certificado A1.
+      parameters:
+        - in: query
+          name: cenario
+          schema:
+            type: string
+            enum: [autorizado, duplicidade, schema, certificado, paralisado]
+            default: autorizado
+          description: Cenário de retorno simulado da SEFAZ
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NFeDocumento'
+      responses:
+        '200':
+          description: Retorno da SEFAZ (mock)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ResultadoEmissao'
+        '422':
+          description: Rejeição SEFAZ
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErroSefaz'
+
+  /nfe/cenarios-mock:
+    get:
+      tags: [NF-e]
+      summary: Listar cenários mock disponíveis
+      responses:
+        '200':
+          description: Lista de cenários
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  cenarios:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        descricao:
+                          type: string
+                        cStat:
+                          type: string
+
+components:
+  responses:
+    ErroValidacao:
+      description: Erro de validação
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Erro'
+
+  schemas:
+    NFeEndereco:
+      type: object
+      required: [logradouro, numero, bairro, codigoMunicipio, municipio, uf, cep]
+      properties:
+        logradouro: { type: string, example: 'Rua das Flores' }
+        numero: { type: string, example: '100' }
+        complemento: { type: string }
+        bairro: { type: string, example: 'Centro' }
+        codigoMunicipio: { type: string, example: '3550308' }
+        municipio: { type: string, example: 'São Paulo' }
+        uf: { type: string, example: 'SP' }
+        cep: { type: string, example: '01001000' }
+        telefone: { type: string }
+
+    NFeDocumento:
+      type: object
+      required: [ide, emitente, destinatario, itens]
+      properties:
+        chaveAcesso:
+          type: string
+          description: Opcional — gerada automaticamente se omitida
+          example: '35260712345678000199550010000000011000000011'
+        ambiente:
+          type: integer
+          enum: [1, 2]
+          example: 2
+        ide:
+          type: object
+          properties:
+            uf: { type: string, example: 'SP' }
+            codigoMunicipio: { type: string, example: '3550308' }
+            serie: { type: integer, example: 1 }
+            numero: { type: integer, example: 1 }
+            naturezaOperacao: { type: string, example: 'VENDA' }
+        emitente:
+          type: object
+          properties:
+            cnpj: { type: string, example: '12345678000199' }
+            razaoSocial: { type: string, example: 'EMPRESA EXEMPLO LTDA' }
+            ie: { type: string, example: '123456789' }
+            crt: { type: string, example: '3' }
+            endereco:
+              $ref: '#/components/schemas/NFeEndereco'
+        destinatario:
+          type: object
+          properties:
+            cpf: { type: string, example: '12345678909' }
+            razaoSocial: { type: string, example: 'CONSUMIDOR FINAL' }
+            indIEDest: { type: integer, example: 9 }
+            endereco:
+              $ref: '#/components/schemas/NFeEndereco'
+        itens:
+          type: array
+          items:
+            type: object
+            properties:
+              codigo: { type: string, example: '001' }
+              descricao: { type: string, example: 'PRODUTO TESTE' }
+              ncm: { type: string, example: '84713012' }
+              cfop: { type: string, example: '5102' }
+              unidade: { type: string, example: 'UN' }
+              quantidade: { type: number, example: 1 }
+              valorUnitario: { type: number, example: 100 }
+              valorTotal: { type: number, example: 100 }
+              cst: { type: string, example: '00' }
+              aliquotaIcms: { type: number, example: 18 }
+              valorIcms: { type: number, example: 18 }
+        frete:
+          type: object
+          properties:
+            modalidade: { type: integer, example: 9 }
+            valor: { type: number }
+        pagamentos:
+          type: array
+          items:
+            type: object
+            properties:
+              forma: { type: string, example: '01' }
+              valor: { type: number, example: 100 }
+
+    ResultadoEmissao:
+      type: object
+      properties:
+        chaveAcesso: { type: string }
+        retorno:
+          type: object
+          properties:
+            sucesso: { type: boolean }
+            autorizado: { type: boolean }
+            cStat: { type: string }
+            xMotivo: { type: string }
+            protocolo: { type: string }
+        xmlGerado: { type: string }
+        mock: { type: boolean }
+
+    NFeCancelamento:
+      type: object
+      required: [chaveAcesso, cnpj, uf, protocolo, justificativa]
+      properties:
+        chaveAcesso: { type: string }
+        cnpj: { type: string, example: '12345678000199' }
+        uf: { type: string, example: 'SP' }
+        ambiente: { type: integer, example: 2 }
+        protocolo: { type: string, example: '135260000000001' }
+        justificativa:
+          type: string
+          minLength: 15
+          example: 'Cancelamento por erro de digitacao no pedido'
+
+    NFeCartaCorrecao:
+      type: object
+      required: [chaveAcesso, cnpj, uf, correcao]
+      properties:
+        chaveAcesso: { type: string }
+        cnpj: { type: string, example: '12345678000199' }
+        uf: { type: string, example: 'SP' }
+        ambiente: { type: integer, example: 2 }
+        sequencia: { type: integer, example: 1 }
+        correcao:
+          type: string
+          minLength: 15
+          example: 'Correcao do endereco de entrega para Rua Nova, 500'
+
+    NFCeDocumento:
+      type: object
+      required: [ide, emitente, itens, csc]
+      properties:
+        ambiente: { type: integer, example: 2 }
+        ide:
+          type: object
+          properties:
+            uf: { type: string, example: 'SP' }
+            codigoMunicipio: { type: string, example: '3550308' }
+            serie: { type: integer, example: 1 }
+            numero: { type: integer, example: 1 }
+        emitente:
+          type: object
+          properties:
+            cnpj: { type: string }
+            razaoSocial: { type: string }
+            ie: { type: string }
+            crt: { type: string, example: '1' }
+            endereco:
+              $ref: '#/components/schemas/NFeEndereco'
+        destinatario:
+          type: object
+          properties:
+            cpf: { type: string }
+            razaoSocial: { type: string }
+        itens:
+          type: array
+          items:
+            type: object
+        csc:
+          type: object
+          required: [idCSC, codigo]
+          properties:
+            idCSC: { type: string, example: '000001' }
+            codigo: { type: string, example: 'SEU-CSC-SEFAZ' }
+
+    ErroSefaz:
+      type: object
+      properties:
+        error: { type: string, example: 'SefazError' }
+        code: { type: string, example: 'SEFAZ_204' }
+        cStat: { type: string }
+        xMotivo: { type: string }
+
+    Erro:
+      type: object
+      properties:
+        error: { type: string }
+        code: { type: string }
+        message: { type: string }

package/examples/emitir-nfce.js

@@ -0,0 +1,51 @@
+import { NFCeService } from '../src/index.js';
+
+const documento = {
+  ambiente: 2,
+  ide: { uf: 'SP', codigoMunicipio: '3550308', serie: 1, numero: 1, presenca: 1 },
+  emitente: {
+    cnpj: '12345678000199',
+    razaoSocial: 'LOJA EXEMPLO LTDA',
+    nomeFantasia: 'LOJA EXEMPLO',
+    ie: '123456789012',
+    crt: '1',
+    endereco: {
+      logradouro: 'Av Paulista', numero: '1000', bairro: 'Bela Vista',
+      codigoMunicipio: '3550308', municipio: 'Sao Paulo', uf: 'SP', cep: '01310100',
+    },
+  },
+  destinatario: {
+    cpf: '12345678909',
+    razaoSocial: 'CONSUMIDOR FINAL',
+  },
+  itens: [{
+    codigo: '001',
+    descricao: 'PRODUTO TESTE NFC-E',
+    ncm: '22021000',
+    cfop: '5102',
+    unidade: 'UN',
+    quantidade: 2,
+    valorUnitario: 5.5,
+    valorTotal: 11.0,
+    cst: '00',
+    aliquotaIcms: 18,
+    valorIcms: 1.98,
+  }],
+  pagamentos: [{ forma: '17', valor: 11.0 }],
+  csc: { idCSC: '000001', codigo: 'CODIGO-CSC-EXEMPLO-SEFAZ' },
+  informacoesComplementares: 'NFC-e emitida pela biblioteca GHINFE',
+};
+
+const service = new NFCeService({ mock: true });
+
+console.log('=== GHINFE — NFC-e Modelo 65 ===\n');
+
+const doc = service.resolverDocumento(documento);
+const xml = service.gerarXml(doc);
+
+console.log('Chave:', doc.chaveAcesso);
+console.log('XML base (sem QR Code):', xml.substring(0, 350) + '...\n');
+console.log('Nota: QR Code v3 é adicionado após assinatura via adicionarQrCode() ou gerarXmlAssinado()\n');
+
+const retorno = await service.enviar(xml, doc.chaveAcesso);
+console.log('Retorno mock SEFAZ (XML sem assinatura — apenas demo):', retorno.cStat, '—', retorno.xMotivo);

package/examples/emitir-nfe.js

@@ -0,0 +1,83 @@
+import { NFeService } from '../src/index.js';
+
+/** Documento de exemplo — homologação SEFAZ. */
+const documento = {
+  chaveAcesso: '35260712345678000199550010000000011000000011',
+  ambiente: 2,
+  ide: {
+    uf: 'SP',
+    codigoMunicipio: '3550308',
+    serie: 1,
+    numero: 1,
+    naturezaOperacao: 'VENDA',
+    consumidorFinal: 1,
+    presenca: 1,
+  },
+  emitente: {
+    cnpj: '12345678000199',
+    razaoSocial: 'EMPRESA EXEMPLO LTDA',
+    nomeFantasia: 'EXEMPLO',
+    ie: '123456789012',
+    crt: '3',
+    endereco: {
+      logradouro: 'Rua Exemplo',
+      numero: '100',
+      bairro: 'Centro',
+      codigoMunicipio: '3550308',
+      municipio: 'São Paulo',
+      uf: 'SP',
+      cep: '01001000',
+    },
+  },
+  destinatario: {
+    cpf: '12345678909',
+    razaoSocial: 'NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL',
+    indIEDest: 9,
+    endereco: {
+      logradouro: 'Rua Cliente',
+      numero: '200',
+      bairro: 'Jardim',
+      codigoMunicipio: '3550308',
+      municipio: 'São Paulo',
+      uf: 'SP',
+      cep: '01020000',
+    },
+  },
+  itens: [
+    {
+      codigo: '001',
+      descricao: 'NOTA FISCAL EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL',
+      ncm: '84713012',
+      cfop: '5102',
+      unidade: 'UN',
+      quantidade: 1,
+      valorUnitario: 100.0,
+      valorTotal: 100.0,
+      cst: '00',
+      aliquotaIcms: 18,
+      valorIcms: 18,
+    },
+  ],
+  frete: { modalidade: 9 },
+  pagamentos: [{ forma: '01', valor: 100.0 }],
+  informacoesComplementares: 'Documento gerado pela biblioteca GHINFE',
+};
+
+const service = new NFeService({ mock: true });
+
+console.log('=== GHINFE — Geração de XML NF-e ===\n');
+
+const xml = service.gerarXml(documento);
+console.log('XML gerado (primeiros 500 chars):\n');
+console.log(xml.substring(0, 500) + '...\n');
+
+console.log('Para assinar com certificado A1:');
+console.log('  const xmlAssinado = service.gerarXmlAssinado(documento, { pfx: buffer, senha: "..." });\n');
+
+console.log('Para emitir completo (mock SEFAZ):');
+console.log('  const resultado = await service.emitir(documento, { pfx, senha });\n');
+
+// Emissão mock sem certificado (apenas envio do XML não assinado para demo)
+const retorno = await service.enviar(xml, documento.chaveAcesso);
+console.log('Retorno mock SEFAZ:');
+console.log(JSON.stringify(retorno, null, 2));

package/examples/emitir-nfse.js

@@ -0,0 +1,46 @@
+import { NFSeService } from '../src/index.js';
+
+const documento = {
+  numero: 1,
+  serie: 'NF',
+  ambiente: 2,
+  codigoMunicipio: '3550308',
+  cnpjPrestador: '12345678000199',
+  inscricaoMunicipal: '12345678',
+  optanteSimplesNacional: 1,
+  servico: {
+    itemListaServico: '01.01',
+    discriminacao: 'Desenvolvimento de software conforme contrato 001/2026',
+    codigoMunicipio: '3550308',
+    valorServicos: 1500.0,
+    aliquotaIss: 5.0,
+    valorIss: 75.0,
+    issRetido: 2,
+  },
+  tomador: {
+    cnpj: '98765432000100',
+    razaoSocial: 'CLIENTE EXEMPLO LTDA',
+    email: 'fiscal@cliente.com.br',
+    endereco: {
+      logradouro: 'Rua das Acacias',
+      numero: '200',
+      bairro: 'Centro',
+      codigoMunicipio: '3550308',
+      uf: 'SP',
+      cep: '01005000',
+    },
+  },
+  informacoesComplementares: 'NFS-e gerada pela biblioteca GHINFE',
+};
+
+const service = new NFSeService({ mock: true });
+
+console.log('=== GHINFE — NFS-e ABRASF 2.04 ===\n');
+
+const xml = service.gerarXml(documento);
+console.log('XML RPS (trecho):', xml.substring(0, 400) + '...\n');
+
+const resultado = await service.emitir(documento);
+console.log('Retorno mock:');
+console.log('  NFS-e:', resultado.retorno.numeroNfse);
+console.log('  Código verificação:', resultado.retorno.codigoVerificacao);

package/examples/endpoints-sefaz.js

@@ -0,0 +1,14 @@
+import { SefazEndpointResolver } from '../src/index.js';
+
+console.log('=== GHINFE — Endpoints SEFAZ Multi-UF ===\n');
+
+const ufs = ['SP', 'RJ', 'MG', 'PR', 'RS', 'SC', 'BA', 'GO'];
+
+for (const uf of ufs) {
+  const { autorizador, endpoints } = SefazEndpointResolver.obterEndpoints(uf, 2);
+  console.log(`${uf} → ${autorizador}`);
+  console.log(`  Autorização: ${endpoints.autorizacao?.substring(0, 70)}...`);
+  console.log(`  Evento:      ${endpoints.evento?.substring(0, 70)}...\n`);
+}
+
+console.log('Total UFs suportadas:', SefazEndpointResolver.listarUFs().length);

package/examples/eventos-nfe.js

@@ -0,0 +1,49 @@
+import { NFeService } from '../src/index.js';
+import { NFE_EVENTOS } from '../src/index.js';
+
+const chaveAcesso = '35260712345678000199550010000000011000000011';
+
+const service = new NFeService({ mock: true, mockEventoScenario: 'registrado' });
+
+console.log('=== GHINFE — Cancelamento e CC-e (mock) ===\n');
+
+// --- Cancelamento ---
+const dadosCancelamento = {
+  chaveAcesso,
+  cnpj: '12345678000199',
+  uf: 'SP',
+  ambiente: 2,
+  protocolo: '135260000000001',
+  justificativa: 'Cancelamento por erro de digitacao no pedido do cliente',
+};
+
+const xmlCancelamento = service.gerarXmlCancelamento(dadosCancelamento);
+console.log('XML Cancelamento (trecho):', xmlCancelamento.substring(0, 300) + '...\n');
+
+const retornoCancelamento = await service.enviarEventoMock(
+  xmlCancelamento,
+  chaveAcesso,
+  NFE_EVENTOS.CANCELAMENTO
+);
+console.log('Retorno cancelamento:', retornoCancelamento.cStat, '—', retornoCancelamento.xMotivo);
+console.log('Protocolo evento:', retornoCancelamento.protocolo, '\n');
+
+// --- Carta de Correção ---
+const dadosCce = {
+  chaveAcesso,
+  cnpj: '12345678000199',
+  uf: 'SP',
+  ambiente: 2,
+  sequencia: 1,
+  correcao: 'Correcao do endereco de entrega: Rua Nova, 500, Bairro Centro',
+};
+
+const xmlCce = service.gerarXmlCartaCorrecao(dadosCce);
+console.log('XML CC-e (trecho):', xmlCce.substring(0, 300) + '...\n');
+
+const retornoCce = await service.enviarEventoMock(
+  xmlCce,
+  chaveAcesso,
+  NFE_EVENTOS.CARTA_CORRECAO
+);
+console.log('Retorno CC-e:', retornoCce.cStat, '—', retornoCce.xMotivo);

package/examples/gerar-chave.js

@@ -0,0 +1,25 @@
+import {
+  gerarChaveAcesso,
+  validarChaveAcesso,
+  parseChaveAcesso,
+  calcularDigitoVerificador,
+} from '../src/utils/chave.utils.js';
+
+console.log('=== GHINFE — Chave de Acesso ===\n');
+
+const chave = gerarChaveAcesso({
+  uf: 'SP',
+  cnpj: '12345678000199',
+  modelo: '55',
+  serie: 1,
+  numero: 42,
+  tipoEmissao: 1,
+  codigoNumerico: '12345678',
+});
+
+console.log('Chave gerada:', chave);
+console.log('DV válido:', validarChaveAcesso(chave));
+console.log('Parse:', parseChaveAcesso(chave));
+
+const chave43 = chave.substring(0, 43);
+console.log('DV calculado:', calcularDigitoVerificador(chave43));