ERP.Fiscal.PlugNotas 0.1.18

ERP.Fiscal

Biblioteca .NET de integração fiscal (NF-e via PlugNotas), pensada para consumo por aplicações ABP. Centraliza HTTP, parsers, retry, classificação de erros e contratos neutros — sem acoplar domínio de ERP.

Pacotes publicados automaticamente no GitHub Packages a cada push em main e no nuget.org (versões 0.1.x e releases com tag v*).

Links dos pacotes

Última versão publicada: 0.1.3. Novas versões 0.1.x seguem o contador em nuget.props após cada merge em main.

Funcionalidades

Fronteira lib vs consumidor

Pacotes NuGet

Feeds: nuget.org (recomendado) ou GitHub Packages — ver Links dos pacotes.

Target: .NET 10 (net10.0)

Versionamento

O contador PackagePatchNumber é commitado automaticamente na main após cada publicação bem-sucedida (chore: bump package version … [skip ci]).

Consumir via GitHub Packages

URL do feed (importante)

O feed NuGet do GitHub é por owner/organização, não por repositório:

https://nuget.pkg.github.com/jpolvora/index.json

Pacotes NuGet no GitHub exigem autenticação no restore, mesmo quando o repositório é público.

Visibilidade do pacote

Pacotes publicados pelo CI deste repositório (via GITHUB_TOKEN) ficam vinculados ao owner jpolvora e herdam a visibilidade do repositório fonte.

1. Autenticação (máquina de desenvolvimento)

Crie um Personal Access Token (classic) com escopo read:packages. Se o repositório for privado, inclua também repo.

Opção A — CLI (recomendado, uma vez por máquina):

dotnet nuget add source "https://nuget.pkg.github.com/jpolvora/index.json" \
  --name github \
  --username SEU_USUARIO_GITHUB \
  --password SEU_PAT \
  --store-password-in-clear-text

Opção B — variável de ambiente (CI local / scripts):

export NUGET_AUTH_TOKEN=SEU_PAT
# username = GitHub username; password = PAT

Opção C — Visual Studio: Tools → NuGet Package Manager → Package Sources → adicionar a URL acima e credenciais.

2. nuget.config no projeto consumidor

Coloque na raiz da solution do seu ERP (ou em samples/, como referência). O dotnet restore procura o arquivo no diretório atual e nos pais.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="github" value="https://nuget.pkg.github.com/jpolvora/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="github">
      <package pattern="ERP.Fiscal.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Referência completa: samples/nuget.config.

O packageSourceMapping garante que apenas ERP.Fiscal.* venha do GitHub; o restante continua no nuget.org.

3. PackageReference no .csproj

No módulo Application (ou host) do seu ERP ABP:

<ItemGroup>
  <PackageReference Include="ERP.Fiscal.Abstractions" Version="0.1.*" />
  <PackageReference Include="ERP.Fiscal.PlugNotas" Version="0.1.*" />
</ItemGroup>

Restore:

dotnet restore

4. Registrar o módulo ABP

using ERP.Fiscal.PlugNotas;
using Volo.Abp.Modularity;

[DependsOn(typeof(PlugNotasFiscalModule))]
public class MeuErpApplicationModule : AbpModule
{
}

Implemente INfeAmbientePolicy no consumidor (ex.: ler OnlySandbox dos Settings locais).

5. Configuração (appsettings.json)

{
  "PlugNotas": {
    "SandboxApiKey": "",
    "ProductionApiKey": "",
    "OnlySandbox": true,
    "TipoContrato": 1,
    "Retry": { "MaxAttempts": 3, "BaseDelayMs": 1000 }
  }
}

Detalhes: docs/plugnotas/01-ambientes-autenticacao.md.

6. GitHub Actions no consumidor

No workflow do ERP que restaura pacotes:

permissions:
  contents: read
  packages: read

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-dotnet@v4
    with:
      dotnet-version: 10.0.x

  - name: Authenticate GitHub Packages
    run: >
      dotnet nuget add source "https://nuget.pkg.github.com/jpolvora/index.json"
      --name github
      --username "${{ github.repository_owner }}"
      --password "${{ secrets.GITHUB_TOKEN }}"
      --store-password-in-clear-text

  - run: dotnet restore
  - run: dotnet build --no-restore

Se o consumidor estiver em outra org/conta, o PAT precisa de acesso de leitura aos pacotes de jpolvora (pacote público no GitHub Packages ainda exige auth).

Azure DevOps: docs/consumers/azure-devops.md.

7. Alternativa: só nuget.org (sem feed GitHub)

Se o consumidor não usar GitHub Packages, basta o feed público:

https://api.nuget.org/v3/index.json

<PackageReference Include="ERP.Fiscal.Abstractions" Version="0.1.3" />
<PackageReference Include="ERP.Fiscal.PlugNotas" Version="0.1.3" />

Ou versão flutuante: 0.1.* para a última 0.1.x publicada.

Páginas: Abstractions · PlugNotas

Exemplo mínimo (smoke test)

Projeto de referência que consome somente NuGet (sem project reference ao código-fonte):

samples/ERP.Fiscal.PackageSmokeTest

# autenticar (ver seção acima)
dotnet test samples/ERP.Fiscal.PackageSmokeTest/ERP.Fiscal.PackageSmokeTest.csproj -c Release

Com pacotes locais (desenvolvimento desta lib):

dotnet pack ERP.Fiscal.slnx -c Release -o ./artifacts/packages -p:PackageVersion=0.1.0-local
dotnet nuget add source ./artifacts/packages --name local-erp-fiscal
dotnet test samples/ERP.Fiscal.PackageSmokeTest -c Release -p:ErpFiscalPackageVersion=0.1.0-local

Ou use samples/nuget.config.local.example copiado como nuget.config.local.

Integração com Consumidores & Agentes (IA)

Esta biblioteca define uma separação rígida de responsabilidades entre o seu ecossistema central (neutro) e as regras específicas dos ERPs consumidores.

Para facilitar a integração e guiar o desenvolvimento por agentes de IA e desenvolvedores em projetos consumidores (ex.: FiscalWR), disponibilizamos uma Skill de Agente portátil:

• Skill portátil: consume-erp-fiscal (localizada em .agents/skills/erp-fiscal-consumer/SKILL.md).

Como Instalar a Skill no ERP Consumidor

1. Crie a pasta .agents/skills/consume-erp-fiscal/ na raiz do repositório do seu ERP consumidor.
2. Copie o arquivo SKILL.md deste repositório e cole nesta pasta recém-criada do ERP consumidor.
3. Isso ativará instruções automatizadas para o agente do consumidor, ensinando-o a configurar pacotes NuGet, registrar módulos ABP, e seguir o padrão de limites/fronteiras entre o ERP e a biblioteca ERP.Fiscal.

Desenvolvimento (código-fonte)

Estrutura

ERP.Fiscal/
├── src/
│   ├── ERP.Fiscal.Abstractions/    # interfaces + DTOs neutros
│   └── ERP.Fiscal.PlugNotas/       # HTTP, parsers, providers, módulo ABP
├── test/
│   └── ERP.Fiscal.PlugNotas.Tests/ # 91 testes unitários
├── samples/
│   └── ERP.Fiscal.PackageSmokeTest/
├── docs/plugnotas/                 # documentação PlugNotas compilada
├── .github/workflows/validate-pr.yml
└── .github/workflows/deploy-main.yml

Build e testes

dotnet build ERP.Fiscal.slnx
dotnet test ERP.Fiscal.slnx

Gerar pacotes localmente

dotnet pack ERP.Fiscal.slnx -c Release -o ./artifacts/packages

CI/CD (GitHub Actions)

1. Validate PR (validate-pr.yml) — executado em Pull Requests para a main: faz restore, build, teste unitário, pack local e executa o Smoke Test isolado.
2. Deploy Main (deploy-main.yml) — executado em merges/pushes na main e tags v*:
   • Em push na main: resolve versão, build, teste, pack, publish no GitHub Packages e faz bump de versão automático.
   • Em tag v*: pack e publish da versão estável no GitHub Packages e nuget.org (se configurado).

Code review agêntico (PR → main only): .github/workflows/cursor-code-review.yml

Documentação

Dependências da lib

ERP.Fiscal.Abstractions não possui dependências NuGet externas.

Licença

MIT