README

Biblioteca PHP production-ready para integração com a API da Declaração Única de Exportação (DU-E) do Portal Único Siscomex.

📋 Índice

Instalação
🚀 Quick Start
Configuração
Uso
Recursos Avançados
Tratamento de Erros
Limites
Segurança e Privacidade
Desenvolvimento
Contribuindo
Documentação
Licença

✨ Funcionalidades

✅ Suporte a certificados digitais ICP-Brasil (e-CPF/e-CNPJ)
✅ Validação de XML contra schema XSD oficial
✅ Retry automático com exponential backoff
✅ Rate limiter para prevenir bloqueios da API
✅ Circuit breaker para resiliência
✅ Validação de lotes (máximo 999 itens)
✅ Cache de consultas (PSR-16)
✅ Logging com sanitização LGPD (PSR-3)
✅ Type hints e strict types (PHP 8.1+)
✅ Cobertura de testes 92% (119 testes)
✅ Análise estática PHPStan nível 8
✅ Padrões PSR-12
✅ 3 ambientes (Produção, Homologação, Treinamento)

📦 Instalação

Via Composer (Repositório Git)

composer config repositories.siscomex-due-sdk vcs https://github.com/Luis17Paiva/siscomex-php-sdk
composer require siscomex/due-sdk:dev-main

Via Clone Manual

git clone https://github.com/Luis17Paiva/siscomex-php-sdk.git
cd siscomex-php-sdk
composer install

Nota: Este pacote será publicado no Packagist em breve. Após a publicação, use: composer require siscomex/due-sdk

🚀 Quick Start

Instalação Rápida

composer config repositories.siscomex-due-sdk vcs https://github.com/Luis17Paiva/siscomex-php-sdk
composer require siscomex/due-sdk:dev-main

Exemplo Completo em 5 Minutos

Este exemplo usa o ambiente de Treinamento com credenciais fictícias:

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Siscomex\Due\DueSdk;
use Siscomex\Due\Config\Config;

// 1. Inicializar SDK em ambiente de treinamento
$sdk = new DueSdk(
    Config::ENV_TREINAMENTO,
    'sua-chave-de-acesso-treinamento'
);

// 2. Registrar uma DU-E simples
try {
    $response = $sdk->registro()->registrarDUeSimples(
        '35210812345678901234567890123456789012345678', // Chave NF-e
        [
            'declarante' => ['cpfCnpj' => '12345678000190'],
            'localDespacho' => '817400',
            'localEmbarque' => '817400',
            'incoterm' => 'FOB',
            'descricao' => 'Produto de exportação',
            'ncm' => '12345678',
            'enquadramento' => '80000',
            'quantidade' => 100,
            'unidadeMedida' => 'KG',
            'valorMercadoria' => 10000.00
        ]
    );
    
    echo "✅ DU-E registrada: " . $response['numero'] . "\n";
    echo "📄 RUC gerado: " . $response['ruc'] . "\n";
    
} catch (\Exception $e) {
    echo "❌ Erro: " . $e->getMessage() . "\n";
}

// 3. Consultar a DU-E criada
$due = $sdk->consulta()->consultarDUe($response['numero']);
echo "📊 Status: " . $due['situacao'] . "\n";

Credenciais de Teste

Para começar rapidamente, você pode usar as seguintes credenciais fictícias no ambiente de Treinamento:

Campo	Valor de Teste
Chave de Acesso	`sua-chave-de-acesso-treinamento`
CPF/CNPJ Declarante	`12345678000190`
Local Despacho	`817400`
Local Embarque	`817400`
Chave NF-e (exemplo)	`35210812345678901234567890123456789012345678`

💡 Dica: Para credenciais reais, acesse o Portal Único Siscomex e faça o cadastro.

Próximos Passos

📖 Veja a documentação completa
🎯 Explore exemplos práticos
🔧 Configure autenticação com certificado digital

⚙️ Configuração

Ambientes Disponíveis

use Siscomex\Due\DueSdk;
use Siscomex\Due\Config\Config;

// Produção (ambiente real)
$sdk = new DueSdk(Config::ENV_PRODUCAO, 'sua-chave-de-acesso');

// Homologação (testes antes de produção)
$sdk = new DueSdk(Config::ENV_HOMOLOGACAO, 'sua-chave-de-acesso');

// Treinamento (aprendizado e desenvolvimento)
$sdk = new DueSdk(Config::ENV_TREINAMENTO, 'sua-chave-de-acesso');

Variáveis de Ambiente (Recomendado)

Crie um arquivo .env:

SISCOMEX_ENV=treinamento
SISCOMEX_CHAVE_ACESSO=sua-chave-de-acesso
SISCOMEX_CERT_PATH=/path/to/certificate.pfx
SISCOMEX_CERT_PASSWORD=senha123

Carregue no PHP:

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$sdk = new DueSdk(
    $_ENV['SISCOMEX_ENV'],
    $_ENV['SISCOMEX_CHAVE_ACESSO']
);

🚀 Uso

Registro de DU-E

DU-E Simples (1 NF-e, 1 item)

$response = $sdk->registro()->registrarDUeSimples(
    '35210812345678901234567890123456789012345678',
    [
        'declarante' => ['cpfCnpj' => '12345678000190'],
        'localDespacho' => '817400',
        'localEmbarque' => '817400',
        'incoterm' => 'FOB',
        'descricao' => 'Produto de exportação',
        'ncm' => '12345678',
        'enquadramento' => '80000'
    ]
);

DU-E com Múltiplas NF-e

$response = $sdk->registro()->registrarDUeMultiplasNfe([
    [
        'chaveNfe' => '35210812345678901234567890123456789012345678',
        'item' => [
            'declarante' => ['cpfCnpj' => '12345678000190'],
            'localDespacho' => '817400',
            'localEmbarque' => '817400',
            'incoterm' => 'FOB',
            'descricao' => 'Produto 1',
            'ncm' => '12345678'
        ]
    ],
    [
        'chaveNfe' => '35210812345678901234567890123456789012345679',
        'item' => [
            'descricao' => 'Produto 2',
            'ncm' => '87654321'
        ]
    ]
]);

DU-E com 1 NF-e e Múltiplos Itens

$response = $sdk->registro()->registrarDUeNfeMultiplosItens(
    '35210812345678901234567890123456789012345678',
    [
        [
            'declarante' => ['cpfCnpj' => '12345678000190'],
            'localDespacho' => '817400',
            'localEmbarque' => '817400',
            'incoterm' => 'FOB',
            'descricao' => 'Item 1 da NF-e',
            'ncm' => '12345678'
        ],
        [
            'descricao' => 'Item 2 da NF-e',
            'ncm' => '87654321'
        ]
    ]
);

DU-E Embarque Antecipado (sem NF-e)

$response = $sdk->registro()->registrarDUeEmbarqueAntecipado([
    [
        'declarante' => ['cpfCnpj' => '12345678000190'],
        'localDespacho' => '817400',
        'localEmbarque' => '817400',
        'incoterm' => 'FOB',
        'descricao' => 'Produto',
        'ncm' => '12345678'
    ]
]);

DU-E Sem Nota Simplificada

$response = $sdk->registro()->registrarDUeSemNotaSimplificada([
    'declarante' => ['cpfCnpj' => '12345678000190'],
    'localDespacho' => '817400',
    'localEmbarque' => '817400',
    'incoterm' => 'FOB',
    'descricao' => 'Serviço de exportação',
    'ncm' => '12345678',
    'justificativaDispensa' => 'Exportação de serviço sem emissão de nota fiscal'
]);

Retificação de DU-E

Retificação Pré-ACD

$response = $sdk->retificacao()->retificarDUePreACD(
    'BR12345678901234',
    [
        'condicaoVenda' => 'CIF',
        'items' => [
            ['descricao' => 'Nova descrição do produto']
        ]
    ]
);

Retificação Pós-ACD

$response = $sdk->retificacao()->retificarDUePosACD(
    'BR12345678901234',
    [
        'items' => [
            ['descricao' => 'Descrição corrigida']
        ]
    ],
    'Correção de erro material na descrição do produto'
);

Vincular Drawback Isenção

$response = $sdk->retificacao()->vincularDrawbackIsencao(
    'BR12345678901234',
    [
        'numero' => '12345678901',
        'ncm' => '12345678',
        'cnpjBeneficiario' => '12345678000190'
    ]
);

Consultas

Consultar DU-E

$response = $sdk->consulta()->consultarDUe('19BR0000056196');

Consultar DU-E Resumida

$response = $sdk->consulta()->consultarDUeResumida('19BR0000056196');
// ou por RUC
$response = $sdk->consulta()->consultarDUeResumida('9BR00000000100000000000000000023366');

Consultar por Nota Fiscal

$response = $sdk->consulta()->consultarPorNotaFiscal('35210812345678901234567890123456789012345678');

Consultar RUC

$response = $sdk->consulta()->consultarRUC('9BR00000000100000000000000000023366');

Consultar Atos Concessórios

// Drawback Isenção
$response = $sdk->consulta()->consultarAtosConcessoriosIsencao('19BR0000056196');

// Drawback Suspensão
$response = $sdk->consulta()->consultarAtosConcessoriosSuspensao('19BR0000056196');

Consultar Exigências Fiscais

$response = $sdk->consulta()->consultarExigenciasFiscais('19BR0000056196');

Consultar Estoque

// Estoque Pré-ACD
$response = $sdk->consulta()->consultarEstoque('817400', 'PRE');

// Estoque Pós-ACD
$response = $sdk->consulta()->consultarEstoque('817400', 'POS');

Consultar Mensagens da DU-E

$mensagens = $sdk->consulta()->consultarMensagensDUe('BR12345678901234');

// Retorna array com:
// ['erros' => [...], 'alertas' => [...], 'informativas' => [...]]

🏗️ Builder Pattern

Use o builder pattern para criar payloads complexos de forma mais legível:

use Siscomex\Due\Builders\DueBuilder;

$builder = new DueBuilder();

$due = $builder
    ->declarante('12345678000190', 'Empresa Exportadora Ltda')
    ->locais('817400', '817400')
    ->incoterm('FOB')
    ->notFiscal('35210812345678901234567890123456789012345678')
    ->item('Produto', '12345678', 100.0)
        ->unidadeMedida('KG')
        ->valor(100.00, 10000.00)
        ->enquadramento('80000')
        ->addAtributoNcm('MARCA', 'Marca XYZ')
        ->addLpco('LI123456789')
        ->build()
    ->toArray();

$response = $sdk->registro()->registrarDUeSimples(
    $due['chaveNfe'],
    $due
);

Vantagens do Builder:

✅ API fluente e legível
✅ Validação automática
✅ Prevenção de erros comuns
✅ Suporte a itens complexos

🔧 Recursos Avançados

Atributos de NCM

$item = [
    'ncm' => '12345678',
    'atributos' => [
        ['codigo' => 'MARCA', 'valor' => 'Marca XYZ'],
        ['codigo' => 'MODELO', 'valor' => 'Modelo ABC']
    ]
];

LPCO

$item = [
    'ncm' => '12345678',
    'lpcos' => ['LI123456789', 'LI987654321']
];

Drawback Devolução

$item = [
    'ncm' => '12345678',
    'enquadramento' => '81195',
    'drawbackDevolucao' => [
        'atoConcessorio' => '12345678901',
        'di' => '12/1234567-8'
    ]
];

Certificado Mercosul

$item = [
    'ncm' => '12345678',
    'certificadoMercosul' => [
        'tipo' => '1', // 1=CCPTC, 2=CCROM
        'quantidade' => 100
    ]
];

⚠️ Tratamento de Erros

use Siscomex\Due\Exceptions\ValidationException;
use Siscomex\Due\Exceptions\ApiException;

try {
    $response = $sdk->registro()->registrarDUeSimples(...);
} catch (ValidationException $e) {
    echo "Erro de validação: " . $e->getMessage();
} catch (ApiException $e) {
    echo "Erro na API: " . $e->getMessage();
}

📊 Limites

Máximo de 999 itens por DU-E via webservice (validado automaticamente)
Máximo de 500 itens por DU-E via tela
Justificativa de dispensa de NF: máximo 1000 caracteres
Rate limit: 60 segundos entre autenticações

🔒 Segurança e Privacidade

Este SDK está em conformidade com a LGPD (Lei Geral de Proteção de Dados). Consulte PRIVACY.md para detalhes sobre:

Tratamento de dados pessoais
Sanitização de logs
Retenção de dados
Direitos dos titulares

🛠️ Desenvolvimento

Testes

composer test

Análise Estática

composer phpstan

Docker

docker build -t siscomex-due-sdk .
docker run -it siscomex-due-sdk

📖 Documentação

Documentação completa disponível no diretório docs:

📚 Índice da Documentação
🔐 Autenticação - Chaves de acesso e certificados
📝 Registro de DU-E - Registrar declarações
🔍 Consultas - Consultar DU-E e informações
🔄 Retificação - Corrigir dados de DU-E
🛡️ Segurança - Política de segurança e privacidade
🎯 Exemplos Práticos

📝 Contribuindo

Contribuições são bem-vindas! Por favor, leia CONTRIBUTING.md para detalhes sobre nosso código de conduta e processo de submissão de pull requests.

📋 Changelog

Consulte CHANGELOG.md para histórico de versões.

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

👤 Autor

Luis Paiva

GitHub: @Luis17Paiva
Email: luis25dev@gmail.com

🙏 Agradecimentos

Portal Único Siscomex pela API DU-E
Comunidade PHP Brasil

⭐ Se este projeto foi útil para você, considere dar uma estrela!

siscomex / due-sdk

Maintainers

Details