Seidor Tax Core

Biblioteca TypeScript completa para gestão de obrigações fiscais brasileiras, oferecendo estruturas de dados, regras de negócio, conversão de documentos e geração de relatórios fiscais (SPED, EFD, REINF e outros).

Motivação

Desde a recepção de documentos, a apuração de impostos e a geração das obrigações fiscais, costuma haver muitas similaridades de regras entre si. Muitas vezes, essas similaridades são implementadas de forma isolada em cada parte do sistema, o que gera retrabalho e inconsistências.

Esta biblioteca centraliza e padroniza:

• Modelos de documentos fiscais brasileiros (NF-e, NFC-e, NFSe, CT-e, CCe)
• Geração de arquivos SPED (Fiscal, Contribuições, ICMS/IPI)
• Validação e formatação de dados fiscais (CNPJ, CPF, códigos IBGE)
• Perfis de estabelecimentos e regimes tributários
• Conversão entre formatos de documentos
• Gerenciamento de dados mestres (municípios, estados, códigos de serviço)

📦 Módulos

1. taxReport - Framework de Geração de Relatórios Fiscais

Geração de relatórios fiscais brasileiros (SPED Fiscal, SPED Contribuições, EFD-ICMS/IPI) com API type-safe.

Características principais:

• Classes base: TaxReport, Block, Register
• Decorators TypeScript para definição de campos (@Key, @Numeric, @Decimal, @Alphanumeric)
• Estratégias de duplicação configuráveis (Error, Ignore, Overwrite)
• Sistema de eventos para validação (RegisterEventNotifier)
• Otimizado para grandes volumes (1M+ registros)
• Múltiplas estratégias de output (Console, StringArray, File)

Documentação completa: lib/taxReport/README.md

2. documents - Modelo de Domínio de Documentos Fiscais

Definição completa de entidades para documentos fiscais e seus componentes.

Classes principais:

• Document - Documento fiscal com metadados, datas, valores e referências
• Item - Itens/linhas de documentos
• Person - Entidades (emitente, destinatário)
• Address - Informações de endereço
• Tax - Cálculos e rastreamento de impostos
• ImportDeclaration - Declarações de importação

Builders fluentes:

• BuilderDocument, BuilderItem, BuilderPerson, BuilderAddress, BuilderTax

Enumerações: 25+ enums para tipos de documentos, status, operações, pagamentos, origens de produtos, códigos de serviço e classificações fiscais brasileiras.

Persistência: Suporte a MongoDB via infra/db/mongo/ com repositórios e builders.

3. conversionDocuments - Conversão de Formatos de Documentos

Conversão entre diferentes formatos de documentos fiscais brasileiros.

Formatos suportados:

• NF-e - Nota Fiscal Eletrônica
• NFC-e - Nota Fiscal ao Consumidor Eletrônica
• NFSe - Nota Fiscal de Serviços Eletrônica
• CCe - Carta de Correção Eletrônica
• CT-e - Conhecimento de Transporte Eletrônico
• Communication - Documentos de comunicação genéricos
• Payment - Documentos de pagamento
• Receipt - Documentos de recibo

Cada tipo possui interfaces de request/input para componentes (Address, Person, Item, Tax) e utilitários de conversão.

4. documentRollback - Reversão de Estado de Documentos

Gerenciamento de rollback e reversão de estados de documentos fiscais.

Funcionalidades:

• Reversão de alterações em documentos
• Recriação de estados anteriores
• Capacidade de auditoria
• Suporte para todos os tipos de documentos (CCe, CT-e, NF-e, NFSe, etc.)

5. profiles - Gestão de Perfis de Estabelecimentos

Gerenciamento de perfis fiscais e configurações de regimes tributários especializados.

Classes principais:

• Profile - Perfil fiscal com validade e configurações
• Establishment - Filiais/estabelecimentos com identificação fiscal e endereço

Perfis especializados por regime tributário:

• EcdSpecializedProfile - Escrituração Contábil Digital (ECD)
• EcfSpecializedProfile - Escrituração Contábil Fiscal (ECF)
• EfdContribSpecializedProfile - SPED Contribuições (PIS/COFINS)
• EfdIcmsIpiSpecializedProfile - SPED ICMS/IPI
• ReinfSpecializedProfile - REINF (Retenções e Informações Fiscais)

Infraestrutura: ProfileRestRepository para integração via REST API.

6. valueObjects - Objetos de Valor do Domínio

Objetos de valor reutilizáveis e imutáveis para conceitos fiscais brasileiros.

Classes:

• CPF - Validação e formatação de CPF (pessoa física)
• CNPJ - Validação e formatação de CNPJ (pessoa jurídica)
• Email - Validação de e-mail
• OurDate - Manipulação de datas com formatos brasileiros
  • Suporte a múltiplos formatos (LayoutDateFormat)
  • Parsing e formatação

7. errors - Gestão de Erros e Mensagens

Tratamento centralizado de erros com templates de mensagens localizadas.

Exports:

• MessageCode & MessageCodeType - Enumeração de códigos de erro
• Messages - Templates de mensagens localizadas
• formatMessage & logWithContext - Utilitários de formatação e logging

Características:

• Sistema de dicionário organizado
• Mensagens baseadas em templates
• Type-safe na formatação de mensagens
• Suporte a múltiplos idiomas

8. masterData - Gestão de Dados de Referência

Gerenciamento de dados de referência brasileiros.

Classes:

• State - Informações de estados brasileiros
• Municipality - Dados de municípios com códigos IBGE
• MunicipalObligation - Metadados de obrigações municipais
• ServiceCode - Códigos de classificação de serviços

Infraestrutura: MemoryMasterDataRepository para cache em memória.

🏗️ Arquitetura

A biblioteca é organizada em arquitetura em camadas:

1. Camada de Domínio (documents, profiles, masterData)

   • Entidades de negócio e objetos de valor
   • Enumerações e tipos

2. Camada de Aplicação (conversionDocuments, documentRollback)

   • Casos de uso e transformações
   • Conversões de formatos de documentos

3. Camada de Framework (taxReport)

   • Framework genérico para relatórios fiscais
   • Arquitetura extensível para diferentes tipos de relatórios

4. Camada de Infraestrutura (diretórios infra dentro dos módulos)

   • Persistência em banco de dados (MongoDB)
   • Integrações REST
   • Implementações em memória

5. Preocupações Transversais

   • Gestão de erros (errors)
   • Objetos de valor (valueObjects)
   • Dados de referência (masterData)

🚀 Começando

Instalação

npm install @seidor/br-fiscal

Uso Básico

Criando um Documento Fiscal

import { BuilderDocument, DocumentType, DocumentStatus } from '@seidor/br-fiscal';

const document = new BuilderDocument()
  .setId('doc-123')
  .setDocumentType(DocumentType.NFE)
  .setStatus(DocumentStatus.AUTHORIZED)
  .setAmount(1000.00)
  .build();

Validando CNPJ/CPF

import { CNPJ, CPF } from '@seidor/br-fiscal';

const cnpj = new CNPJ('12.345.678/0001-90');
if (cnpj.isValid()) {
  console.log('CNPJ válido:', cnpj.format());
}

const cpf = new CPF('123.456.789-00');
if (cpf.isValid()) {
  console.log('CPF válido:', cpf.format());
}

Gerando Relatório SPED

import { TaxReport, Block, Register } from '@seidor/br-fiscal';

// Consulte a documentação completa em lib/taxReport/README.md

📚 Documentação Adicional

• Tax Report Framework: lib/taxReport/README.md
  • Arquitetura
  • Guia Rápido
  • Exemplos
  • FAQ

🔑 Características Principais

• Type-Safe: Uso extensivo de TypeScript, decorators e enums
• Orientado a Padrões: Builder pattern, Repository pattern, Observer pattern
• Extensível: Classes abstratas e interfaces em toda a biblioteca
• Otimizado para Performance: Preparado para processar grandes volumes de registros fiscais
• Específico para o Brasil: Suporte completo aos requisitos fiscais brasileiros
• Bem Documentado: README, exemplos e documentação de arquitetura extensivos

📄 Licença

Consulte o arquivo LICENSE para mais informações.