nfse-php

Framework-agnostic PHP library for issuing, querying, and cancelling Nota Fiscal de Serviço Eletrônica (NFS-e) via SEFIN Nacional (ABRASF 2.04 / SEFIN 1.0).

Scope

• Emit NFS-e (emit)
• Query NFS-e (query)
• Cancel NFS-e (cancel)
• Generate the DANFSe PDF locally from the NFS-e XML (getDanfse / Danfse\DanfseGenerator)
• Sign DPS XML with PFX credentials
• Read secrets from OpenBao/Vault or an in-memory store

Installation

composer require librecodeoop/nfse-php

Quick Start

use LibreCodeCoop\NfsePHP\Config\CertConfig;
use LibreCodeCoop\NfsePHP\Config\EnvironmentConfig;
use LibreCodeCoop\NfsePHP\Dto\DpsData;
use LibreCodeCoop\NfsePHP\Http\NfseClient;
use LibreCodeCoop\NfsePHP\SecretStore\OpenBaoSecretStore;

$store  = new OpenBaoSecretStore(addr: 'http://localhost:8200', token: getenv('VAULT_TOKEN'));
$env    = new EnvironmentConfig(sandboxMode: true);
$cert   = new CertConfig(
    cnpj: '11222333000181',
    pfxPath: '/secure/path/certificate.pfx',
    vaultPath: 'pfx/11222333000181',
);

$client = new NfseClient(environment: $env, cert: $cert, secretStore: $store);

$dps = new DpsData(
    cnpjPrestador: '11222333000181', // Example only: configure with your provider CNPJ
    municipioIbge: '3303302',
    // ... other fields
);

$receipt = $client->emit($dps);
echo $receipt->nfseNumber; // NFS-e number returned by the SEFIN gateway

Secret Storage with OpenBao

PFX passwords are stored in OpenBao (or Vault) KV v2, for example in nfse/pfx/{cnpj}.

use LibreCodeCoop\NfsePHP\SecretStore\OpenBaoSecretStore;

$store = new OpenBaoSecretStore(
    addr:      getenv('VAULT_ADDR'),   // e.g. http://openbao:8200
    roleId:    getenv('VAULT_ROLE_ID'),
    secretId:  getenv('VAULT_SECRET_ID'),
    mount:     'nfse',               // KV v2 mount
);

// Store the PFX password after upload
$store->put('pfx/11222333000181', ['password' => 'secret']);

// Retrieve during signing
$password = $store->get('pfx/11222333000181')['password'];

For development/CI without OpenBao, use NoOpSecretStore (in-memory only, no server calls).

Contributing

All commits must use Conventional Commits and be signed off (git commit -s).

Give us a star!

If this library saves you hours of integration pain, please ⭐ the repository.
It helps other developers discover the project and motivates the team to keep improving it.

ADN contributor distribution

Use Http\\AdnClient for the contributor ADN API. It is intentionally separate from NfseClient: SEFIN handles issuance/query/cancellation, while ADN distributes NFS-e, DPS and event documents by NSU or access key.

XML signature integrity vs certificate trust

XmlSignatureVerifier answers only whether XMLDSig references and the signature are cryptographically consistent with the certificate embedded in KeyInfo. It does not establish ICP-Brasil trust.

Use CertificateTrustValidator separately when consuming signed documents. The caller supplies its trust-anchor files and may inject a bounded CertificateRevocationCheckerInterface implementation. The structured result keeps signature integrity, certificate validity dates, chain trust and revocation status separate. Deterministic tests can therefore use generated certificates without claiming ICP-Brasil trust.