README

Pacote Laravel 10/11/12 para integração com o sistema AGT de Angola

Desenvolvedor: Adilson Miguel Email: adilson2012jose@gmail.com Telefone: 2068417074

Instalação

composer require onsoft/agt
php artisan onsoft-agt:instalar

Variáveis de Ambiente (.env)

AGT_AMBIENTE=sandbox          # sandbox | producao
AGT_MULTI_TENANT=true         # true para multi-organização
AGT_NOME_SOFTWARE=MeuSistema
AGT_VERSAO_SOFTWARE=1.0.0
AGT_MOEDA_PADRAO=AOA
AGT_TAXA_IVA_PADRAO=14

Utilização

Criar Fatura (com múltiplos pagamentos e estudantes)

use Onsoft\Agt\Servicos\ServicoFatura;

$fatura = app(ServicoFatura::class)->criar([
    'document_type'  => 'FR',           // FT | FR | FS | NC | ND | RC
    'customer_nif'   => '500123456',    // ou null → Consumidor Final
    'customer_name'  => 'João Silva',
    'encarregadoId'  => 42,

    // Múltiplos itens com diferentes estudantes
    'items' => [
        [
            'description'    => 'Propina — Outubro 2026',
            'quantity'       => 1,
            'unit_price'     => 50000,
            'tax_code'       => 'ISE',   // isento
            'tax_percentage' => 0,
            'alunoId'        => 101,     // estudante A
        ],
        [
            'description'    => 'Material Escolar',
            'quantity'       => 2,
            'unit_price'     => 5000,
            'tax_code'       => 'IVA',
            'tax_percentage' => 14,
            'alunoId'        => 102,     // estudante B
        ],
    ],

    // Múltiplos meios de pagamento
    'payments' => [
        [
            'method_code' => 'NU',       // Numerário
            'amount'      => 40000,
        ],
        [
            'method_code' => 'wallet',   // Carteira do encarregado
            'amount'      => 20000,
        ],
    ],
    // Troco (60000 - 60000 = 0) ou crédito se totalPago > grossTotal
], $organizacaoId);

Gerar PDF em Memória (nunca guardado em disco)

// Stream directo para o browser
Route::get('/faturas/{id}/pdf', function($id, ServicoPdf $pdf) {
    $fatura = Invoice::findOrFail($id);
    return $pdf->gerarStream($fatura); // application/pdf inline
});

// Base-64 para o frontend
Route::get('/faturas/{id}/pdf-base64', function($id, ServicoPdf $pdf) {
    $fatura = Invoice::findOrFail($id);
    return response()->json($pdf->gerarBase64($fatura));
});

No frontend React/Vue:

// Receber base64 e abrir sem guardar
const { base64, nome_ficheiro } = await api.get(`/faturas/${id}/pdf-base64`).then(r => r.data.dados);
const url = `data:application/pdf;base64,${base64}`;
window.open(url); // abre no browser sem guardar
// ou
document.getElementById('visor').src = url; // <embed id="visor" />

Formato do PDF por Configuração

O sistema lê automaticamente a tabela invoice_print_configs:

Tipos de Documento

Regras AGT Implementadas (Decreto Executivo Angola)

✅ Hash RSA-SHA1: InvoiceDate;SystemEntryDate;InvoiceNo;GrossTotal;HashAnterior ✅ Hash Control: posições 1.ª, 11.ª, 21.ª, 31.ª do hash impresso na fatura ✅ Linha impressa: XxXx-Processado por programa validado nº 0000/AGT ✅ RC (Recibo): Emitido por programa validado nº 0000/AGT ✅ Numeração sequencial e contínua por série e ano fiscal ✅ NC usa DebitAmount; FT/FR/FS/ND usam CreditAmount ✅ Documentos sem valor de IVA exibem "Isento" com código de isenção ✅ Consumidor Final impresso quando NIF não fornecido ✅ PDF sem valores negativos (NC com DebitAmount) ✅ Multi-tenant: chaves encriptadas com APP_KEY via Crypt

Comandos Artisan

php artisan onsoft-agt:instalar           # Instalação inicial
php artisan onsoft-agt:estado             # Estado de todas as organizações
php artisan onsoft-agt:sincronizar-series # Sincronizar séries da AGT
php artisan onsoft-agt:retentar-falhas    # Retentar faturas com falha

Rotas Incluídas

Compatibilidade com o Projecto V-TEST

Este pacote é 100% compatível com a estrutura do projecto:

• Usa os modelos existentes: Invoice, InvoiceItem, InvoiceItemTax, InvoicePayment, AgtSeries, OrganizationAgtConfig
• Usa as tabelas existentes (não cria duplicados)
• Mantém a API pública do AgtSeriesService (compatível com ensureFiscalYearSeries, nextDocumentNumber)
• Usa o BelongsToOrganization global scope automaticamente
• Usa o SubmitInvoiceToAgtJob existente
• Lê InvoicePrintConfig da tabela invoice_print_configs

Onsoft AGT v1.0.0 — Adilson Miguel — adilson2012jose@gmail.com