README

Componente PHP reutilizável para rotinas fiscais, com foco atual em DC-e, incluindo:

montagem e normalização de requests
validação de payloads
assinatura XML
transmissão SOAP
autorização, consulta e cancelamento
apoio para geração de DACE

O objetivo deste pacote é extrair a camada fiscal do projeto principal sem alterar o comportamento já existente, permitindo reutilização em múltiplas aplicações.

Instalação

composer require betocampoy/champs-fiscal

Dependências

Além das extensões nativas do PHP, o pacote depende de:

betocampoy/champs-certificate:^1.0
endroid/qr-code:^6.0
picqer/php-barcode-generator:^3.2

Extensões obrigatórias:

ext-dom
ext-libxml
ext-openssl
ext-soap

Namespace

use BetoCampoy\Champs\Fiscal\...;

Configuração de ambiente

Este pacote utiliza variáveis de ambiente no padrão abaixo. No momento, a leitura e a carga dessas variáveis continuam sendo responsabilidade da aplicação consumidora.

Isso funciona bem tanto em projetos Symfony quanto em projetos legados, desde que o carregamento do .env já esteja configurado pela aplicação.

Variáveis esperadas:

CHAMPS_FISCAL_DCE_EMISSION_TYPE='1'
CHAMPS_FISCAL_DCE_AUTHORIZER_SITE_NUMBER='0'
CHAMPS_FISCAL_DCE_ENVIRONMENT='2'
CHAMPS_FISCAL_DCE_APPLICATION_VERSION='MINHA ENCOMENDA'
CHAMPS_DCE_QRCODE_BASE_URL='https://dfe-portal.svrs.rs.gov.br/dce/QRCode'

Recomendação importante

mantenha no .env apenas valores base que podem ser versionados com segurança
quando houver necessidade de sobrescrever valores por ambiente, prefira usar .env.local
em especial, CHAMPS_FISCAL_DCE_ENVIRONMENT costuma ser um bom candidato para ficar em .env.local, evitando subir ajustes locais para o Git

Exemplo:

# .env
CHAMPS_FISCAL_DCE_EMISSION_TYPE='1'
CHAMPS_FISCAL_DCE_AUTHORIZER_SITE_NUMBER='0'
CHAMPS_FISCAL_DCE_APPLICATION_VERSION='MINHA ENCOMENDA'
CHAMPS_DCE_QRCODE_BASE_URL='https://dfe-portal.svrs.rs.gov.br/dce/QRCode'

# .env.local
CHAMPS_FISCAL_DCE_ENVIRONMENT='2'

Hoje o pacote não obriga automaticamente a existência das variáveis, mas já oferece uma classe utilitária para centralizar a leitura delas.

Exemplo de leitura:

use BetoCampoy\Champs\Fiscal\Config\DceEnvironmentDefaults;

$defaults = DceEnvironmentDefaults::fromEnv();

Exemplo de normalização de request

use BetoCampoy\Champs\Fiscal\Config\DceEnvironmentDefaults;
use BetoCampoy\Champs\Fiscal\Dce\Request\Authorization\Normalizer\DceAuthorizationRequestNormalizer;

$normalizer = new DceAuthorizationRequestNormalizer();
$request = $normalizer->normalize($request, DceEnvironmentDefaults::fromEnv());

Exemplo de autorização

use BetoCampoy\Champs\Fiscal\Dce\Authorization\DceAuthorizationService;

$service = new DceAuthorizationService(environment: 'homolog');
$response = $service->authorize($payload, $openedCertificateData);

Estrutura

src/Dce/Authorization: fluxo de autorização
src/Dce/Query: fluxo de consulta
src/Dce/Event/Cancel: fluxo de cancelamento
src/Dce/Dace: apoio para impressão e mapeamento da DACE
src/Transmission: transporte SOAP e DTOs
src/Xml: assinatura XML
src/resources: XSDs e WSDLs locais

Observações

Esta primeira versão foi componentizada sem refatorar regras de negócio existentes.
Em uma próxima versão, pode valer adicionar uma validação explícita das variáveis de ambiente obrigatórias.
O pacote foi preparado para publicação em GitHub e Packagist.

Publicação

Exemplo de fluxo:

git init
git add .
git commit -m "Initial component release"
git tag v1.0.0
git push origin main --tags

Depois disso, basta apontar o repositório no Packagist e sincronizar a nova tag.

Licença

MIT

betocampoy / champs-fiscal

Maintainers

Package info

Statistics

Security