codespace-ao / brisa-sdk
SDK oficial da API Brisa (faturação certificada AGT, Angola) para PHP.
Requires
- php: >=8.1
- ext-curl: *
- ext-json: *
Requires (Dev)
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-22 19:03:21 UTC
README
SDK oficial da API Brisa: faturação eletrónica certificada pela AGT (Angola). Emita faturas, recibos e notas de crédito, gira clientes e artigos, exporte o SAF-T e receba webhooks a partir de PHP.
- PHP 8.1 ou mais recente, com
ext-curleext-json. Sem outras dependências. - Repete sozinho os pedidos em
429,502,503e falhas de rede, respeitando oRetry-After. - Gera um
Idempotency-Keynas criações, para que uma repetição nunca emita o mesmo documento duas vezes. - Erros da API (RFC 9457) como exceções com tipo:
RuleException,PlanException,ValidationException...
Instalação
Instale pelo Packagist:
composer require codespace-ao/brisa-sdk
Começar
use Brisa\Brisa; $brisa = new Brisa(['apiKey' => getenv('BRISA_API_KEY')]); $cliente = $brisa->clients->create(['name' => 'Ngola Comercial Lda', 'taxId' => '5000000000', 'email' => 'contas@ngola.ao']); $fatura = $brisa->documents->issue([ 'type' => 'FT', 'clientId' => $cliente['id'], 'lines' => [['productCode' => 'PAR-M8', 'quantity' => 4]], ]); file_put_contents($fatura['number'] . '.pdf', $brisa->documents->pdf($fatura['id']));
A chave escolhe o ambiente: brk_sbx... é a sandbox (nada vai à AGT), brk_... é produção. O endereço é sempre https://api.brisa.ao
(mude-o com baseUrl ou BRISA_API_URL só para testar contra outro ambiente).
Opções
| Opção | Por omissão | |
|---|---|---|
apiKey |
BRISA_API_KEY |
A chave de API. |
baseUrl |
BRISA_API_URL ou https://api.brisa.ao |
|
timeout |
30 |
Segundos de cada tentativa. |
maxRetries |
2 |
Repetições em 429, 502, 503 e falhas de rede. |
maxRetryDelay |
60 |
Espera máxima aceite de um Retry-After; acima disso o erro sobe logo. |
headers |
[] |
Cabeçalhos acrescentados a todos os pedidos. |
transport |
new CurlTransport() |
Outro Brisa\Http\Transport (ex.: sobre Guzzle). new CurlTransport('/caminho/cacert.pem') usa esse ficheiro de CAs. |
Cada método aceita ainda $options com idempotencyKey, timeout, maxRetries e headers para esse pedido.
O que há
$brisa->documents |
issue, list, listAll, get, pdf (a4, a5, thermal80, thermal58), export (JSON ou XML), pay, payGlobal, cancel, rectify, creditNote, credits, history, setDueDate, send |
$brisa->clients |
create, update, get, list (com sort, desc, totals), listAll, setActive, statement, statementPdf, statementCsv |
$brisa->products |
upsert, get, list, listAll, moveStock |
$brisa->catalog |
taxes, exemptionReasons, categories |
$brisa->saft |
request, list, get, file, waitUntilReady |
$brisa->me(), $brisa->company() |
Quem é a chave; os dados da empresa. |
$brisa->bank(), $brisa->setBank($dados) |
Os dados bancários da empresa (o IBAN fica como foi escrito), que as faturas por pagar imprimem. |
$brisa->request($method, $path, ...) |
Qualquer outro endpoint, com autenticação, repetições e erros do SDK. |
$brisa->rateLimit() |
Os limites indicados na última resposta (limit, remaining, reset). |
As respostas são arrays associativos, tal como o JSON da API (ver docs/API.md e docs/openapi.json no repositório da API).
As listas paginadas devolvem ['items' => [...], 'page' => 0, 'size' => 50, 'total' => 123]; listAll() percorre todas as páginas:
foreach ($brisa->documents->listAll(['type' => 'FT', 'from' => '2026-01-01']) as $doc) { echo $doc['number'], PHP_EOL; }
Papel: A4, A5 e rolos térmicos
$a4 = $brisa->documents->pdf($fatura['id']); // A4 (por omissão) $a5 = $brisa->documents->pdf($fatura['id'], ['format' => 'a5']); // o A4 reduzido a meia folha $r80 = $brisa->documents->pdf($fr['id'], ['format' => 'thermal80']); // talão para rolo de 80 mm (FR, TV, RC, RG) $r58 = $brisa->documents->pdf($fr['id'], ['format' => 'thermal58']); // talão para rolo de 58 mm
Venda direta paga com vários meios
Num FR ou TV pode pagar-se parte em numerário, parte no TPA, parte por transferência. O que se paga cobre o total; o troco (o que se pagou a mais) sai do
numerário, por isso os meios que não são numerário não podem somar mais do que o total (RuleException). O talão e a fatura mostram cada meio, o total pago e o troco.
$fr = $brisa->documents->issue([ 'type' => 'FR', 'lines' => [['description' => 'Cimento 50 kg', 'quantity' => 1, 'unitPrice' => 100]], 'payment' => ['payments' => [['method' => 'debit_card', 'amount' => 50], ['method' => 'cash', 'amount' => 100]]], // 114 a pagar: 36 de troco ]); $d = $brisa->documents->get($fr['id']); // $d['paymentMethod'] === 'mixed', $d['payments'], $d['amountReceived']
Dados bancários nas faturas por pagar
$brisa->setBank(['bankName' => 'BAI', 'holder' => 'Ngola Comercial, Lda', 'iban' => 'AO83 0040 0000 6789 1234 5678 9', 'kwikKey' => '923000000']); $brisa->documents->issue(['type' => 'FT', 'clientId' => 42, 'lines' => $linhas]); // leva os dados da empresa $brisa->documents->issue(['type' => 'FT', 'clientId' => 42, 'lines' => $linhas, 'bankDetails' => ['iban' => '...']]); // outros, só nesta fatura $brisa->documents->issue(['type' => 'FT', 'clientId' => 42, 'lines' => $linhas, 'printBankDetails' => false]); // nenhuns
Clientes: ordem, totais e extrato
// por quanto se faturou a cada um (`totals` acrescenta invoiced, amountDue, lastInvoiceDate e documents) $top = $brisa->clients->list(['sort' => 'invoiced:desc', 'totals' => true, 'size' => 10]); // a conta corrente do cliente, e para imprimir (precisa também de `reports.export`) $extrato = $brisa->clients->statement($id, ['from' => '2026-11-01', 'to' => '2026-11-30']); $pdf = $brisa->clients->statementPdf($id); $csv = $brisa->clients->statementCsv($id);
Ordens da lista: name (por omissão), taxId, city, createdAt e, que pedem os totais, invoiced, due, lastInvoice, documents.
SAF-T
$export = $brisa->saft->request('2026-01-01', '2026-01-31'); $brisa->saft->waitUntilReady($export['id']); file_put_contents('saft-2026-01.xml', $brisa->saft->file($export['id']));
Erros
use Brisa\Exception\{RuleException, PlanException, ValidationException, ApiException, ConnectionException}; try { $brisa->documents->issue($pedido); } catch (ValidationException $e) { // 400: $e->errors() = ['campo' => 'mensagem'] } catch (PlanException $e) { // 402: $e->metric(), $e->limit() } catch (RuleException $e) { // 422: regra fiscal; $e->field() diz qual } catch (ApiException $e) { // outros: $e->status(), $e->type() (urn:brisa:...), $e->detail() } catch (ConnectionException $e) { // rede ou tempo esgotado (TimeoutException) }
Programe contra status(), type() e field(), não contra o texto de detail() (em português, pode mudar).
Uma criação que falhou por rede pode ser repetida com o mesmo idempotencyKey: a API devolve o resultado da primeira vez.
Webhooks
use Brisa\Webhook; use Brisa\Exception\WebhookSignatureException; try { $event = Webhook::verify(file_get_contents('php://input'), $_SERVER['HTTP_BRISA_SIGNATURE'] ?? null, getenv('BRISA_WEBHOOK_SECRET')); } catch (WebhookSignatureException $e) { http_response_code(400); exit; } // $event['type'], $event['data']... http_response_code(200);
Use o corpo bruto. Durante a troca do segredo pode passar os dois: Webhook::verify($corpo, $assinatura, [$novo, $anterior]).
Webhook::sign($corpo, $segredo) calcula o cabeçalho, para testar o seu endpoint.
Documentação
O guia completo, com exemplos em cURL, JavaScript e PHP, está em docs/: primeiros passos, autenticação, documentos, pagamentos, impressão, dados bancários, clientes e extrato, SAF-T, webhooks, erros e o guia de atualização. A referência de todos os endpoints está em docs/openapi.json.
Contribuir
Contribuições são bem-vindas: correções, testes, documentação e ideias. Leia o guia de contribuição e o código de conduta. Para falhas de segurança, não abra uma issue: siga a política de segurança.
Desenvolvimento
composer install
composer lint
composer test
BRISA_API_KEY=brk_sbx... BRISA_API_URL=https://... composer test:integration
Licença MIT.