brisa-sdk 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +24 -0
- package/LICENSE +21 -0
- package/README.md +90 -2
- package/dist/index.cjs +621 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +928 -0
- package/dist/index.d.ts +928 -0
- package/dist/index.js +590 -0
- package/dist/index.js.map +1 -0
- package/docs/01-primeiros-passos.md +106 -0
- package/docs/02-autenticacao.md +55 -0
- package/docs/03-documentos.md +80 -0
- package/docs/04-pagamentos.md +69 -0
- package/docs/05-impressao.md +44 -0
- package/docs/06-dados-bancarios.md +42 -0
- package/docs/07-clientes-e-extrato.md +61 -0
- package/docs/08-artigos-e-stock.md +38 -0
- package/docs/09-saft.md +23 -0
- package/docs/10-webhooks.md +42 -0
- package/docs/11-erros.md +52 -0
- package/docs/12-idempotencia-e-limites.md +29 -0
- package/docs/13-sandbox-e-producao.md +25 -0
- package/docs/README.md +35 -0
- package/docs/openapi.json +16772 -0
- package/docs/upgrade.md +23 -0
- package/package.json +67 -4
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Artigos e stock
|
|
2
|
+
|
|
3
|
+
Um artigo é um produto ou um serviço com preço e impostos. Quando controla o stock, cada venda desconta e cada entrada soma.
|
|
4
|
+
|
|
5
|
+
## Criar ou atualizar um artigo
|
|
6
|
+
|
|
7
|
+
O `upsert` cria o artigo se o código não existe e atualiza-o se existe. Os impostos vêm do catálogo da empresa.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
const [iva] = (await brisa.catalog.taxes()).filter((t) => t.type === 'IVA' && t.code === 'NOR')
|
|
11
|
+
await brisa.products.upsert('PAR-M8', { name: 'Parafuso M8', type: 'product', price: 100, unit: 'un', taxes: [{ taxId: iva.id, order: 1 }], trackStock: true })
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
```php
|
|
15
|
+
$brisa->products->upsert('PAR-M8', ['name' => 'Parafuso M8', 'type' => 'product', 'price' => 100, 'unit' => 'un', 'trackStock' => true]);
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Mover stock
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
await brisa.products.moveStock('PAR-M8', { type: 'in', quantity: 100, reason: 'Stock inicial' })
|
|
22
|
+
const p = await brisa.products.get('PAR-M8') // p.quantity, p.lowStock
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```php
|
|
26
|
+
$brisa->products->moveStock('PAR-M8', ['type' => 'in', 'quantity' => 100, 'reason' => 'Stock inicial']);
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
curl https://api.brisa.ao/api/v1/products/PAR-M8/movements -H "Authorization: Bearer $BRISA_API_KEY" -H "Idempotency-Key: entrada-1" \
|
|
31
|
+
-H "Content-Type: application/json" -d '{"type":"in","quantity":100,"reason":"Stock inicial"}'
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Catálogo
|
|
35
|
+
|
|
36
|
+
* `catalog.taxes()`: os impostos da empresa. Os de uma linha têm de coincidir com um destes.
|
|
37
|
+
* `catalog.exemptionReasons()`: os motivos de isenção `M00`…`M94`, obrigatórios em linhas isentas.
|
|
38
|
+
* `catalog.categories()`.
|
package/docs/09-saft.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# SAF-T
|
|
2
|
+
|
|
3
|
+
O SAF-T (AO) é o ficheiro de auditoria que a AGT pede. A Brisa gera-o em segundo plano para o período que escolher.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
curl https://api.brisa.ao/api/v1/saft/exports -H "Authorization: Bearer $BRISA_API_KEY" -H "Content-Type: application/json" -d '{"from":"2026-10-01","to":"2026-10-31"}'
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
const pedido = await brisa.saft.request({ from: '2026-10-01', to: '2026-10-31' })
|
|
11
|
+
await brisa.saft.waitUntilReady(pedido.id) // espera, com intervalos, até estar pronto
|
|
12
|
+
const xml = await brisa.saft.file(pedido.id)
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
```php
|
|
16
|
+
$pedido = $brisa->saft->request('2026-10-01', '2026-10-31');
|
|
17
|
+
$brisa->saft->waitUntilReady($pedido['id']);
|
|
18
|
+
file_put_contents('saft-2026-10.xml', $brisa->saft->file($pedido['id']));
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
> **Nota:** pedir o ficheiro antes de estar pronto devolve `409`. O `waitUntilReady` evita isso.
|
|
22
|
+
|
|
23
|
+
O período tem de ser do ano corrente, com a data inicial antes da final e sem datas futuras. Precisa da permissão `saft.export`.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Webhooks
|
|
2
|
+
|
|
3
|
+
Em vez de perguntar à API se algo mudou, deixe que a Brisa o avise. Cada evento é um `POST` ao endereço que registar.
|
|
4
|
+
|
|
5
|
+
## Eventos
|
|
6
|
+
|
|
7
|
+
`document.issued`, `document.cancelled`, `document.credited`, `document.rectified`, `document.agt.validated`, `document.agt.rejected` e `document.agt.cancel_rejected`.
|
|
8
|
+
|
|
9
|
+
Os webhooks registam-se na aplicação (não com a chave de API). O segredo (`whsec_...`) é mostrado uma única vez.
|
|
10
|
+
|
|
11
|
+
## Verificar a assinatura
|
|
12
|
+
|
|
13
|
+
> **Atenção:** verifique **sempre** a assinatura, sobre o corpo **bruto** (antes de o converter em JSON). Sem isso qualquer pessoa pode fingir ser a Brisa.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import express from 'express'
|
|
17
|
+
import { BrisaWebhookSignatureError, verifyWebhook } from 'brisa-sdk'
|
|
18
|
+
|
|
19
|
+
app.post('/webhooks/brisa', express.raw({ type: 'application/json' }), async (req, res) => {
|
|
20
|
+
try {
|
|
21
|
+
const event = await verifyWebhook(req.body, req.get('Brisa-Signature'), process.env.BRISA_WEBHOOK_SECRET!)
|
|
22
|
+
res.sendStatus(200) // responda depressa (menos de 10 s)
|
|
23
|
+
} catch (e) {
|
|
24
|
+
if (e instanceof BrisaWebhookSignatureError) return res.sendStatus(400)
|
|
25
|
+
throw e
|
|
26
|
+
}
|
|
27
|
+
})
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```php
|
|
31
|
+
use Brisa\Webhook;
|
|
32
|
+
|
|
33
|
+
$event = Webhook::verify(file_get_contents('php://input'), $_SERVER['HTTP_BRISA_SIGNATURE'] ?? null, getenv('BRISA_WEBHOOK_SECRET'));
|
|
34
|
+
http_response_code(200);
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Boas práticas
|
|
38
|
+
|
|
39
|
+
* **Entrega "pelo menos uma vez".** Guarde o `event.id` e ignore os repetidos.
|
|
40
|
+
* **Responda depressa** e trate o trabalho pesado fora do pedido.
|
|
41
|
+
* **Troca de segredo:** durante a troca chegam duas assinaturas; passe os dois segredos (`[novo, antigo]`) à verificação.
|
|
42
|
+
* **Teste o seu endpoint** com `signWebhookPayload(corpo, segredo)` (JS) ou `Webhook::sign($corpo, $segredo)` (PHP), que geram um cabeçalho válido.
|
package/docs/11-erros.md
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Erros
|
|
2
|
+
|
|
3
|
+
A API responde a falhas com um documento [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (`application/problem+json`): `status`, `type` estável (`urn:brisa:...`), `title`, `detail` em português e, conforme o caso, `field` ou `errors`.
|
|
4
|
+
|
|
5
|
+
```json
|
|
6
|
+
{ "type": "urn:brisa:regra-fiscal", "title": "Regra fiscal", "status": 422, "field": "payment.payments", "detail": "O que se paga não cobre o total." }
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
> **Nota:** programe contra `status`, `type` e `field`. O texto de `detail` pode mudar.
|
|
10
|
+
|
|
11
|
+
## O que cada estado quer dizer
|
|
12
|
+
|
|
13
|
+
| Estado | Classe (JavaScript) | Quando |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| 400 | `BrisaValidationError` | corpo inválido; `errors` = `{ campo: mensagem }` |
|
|
16
|
+
| 401 | `BrisaAuthenticationError` | chave inválida, revogada, expirada ou de outro IP |
|
|
17
|
+
| 402 | `BrisaPlanError` | plano sem API ou limite do plano (`metric`, `limit`) |
|
|
18
|
+
| 403 | `BrisaPermissionError` | a chave não tem a permissão |
|
|
19
|
+
| 404 | `BrisaNotFoundError` | não existe, ou é do outro ambiente |
|
|
20
|
+
| 409 | `BrisaConflictError` | ainda não está pronto (por exemplo, SAF-T) |
|
|
21
|
+
| 422 | `BrisaRuleError` | regra fiscal; `field` diz o campo |
|
|
22
|
+
| 429 | `BrisaRateLimitError` | demasiados pedidos; `retryAfter` em segundos |
|
|
23
|
+
| 5xx | `BrisaServerError` | AGT ou serviço indisponível |
|
|
24
|
+
|
|
25
|
+
## Tratar no código
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import { BrisaApiError, BrisaRuleError } from 'brisa-sdk'
|
|
29
|
+
|
|
30
|
+
try {
|
|
31
|
+
await brisa.documents.issue(body)
|
|
32
|
+
} catch (e) {
|
|
33
|
+
if (e instanceof BrisaRuleError && e.field === 'eventDate') {
|
|
34
|
+
// fora do prazo
|
|
35
|
+
} else if (e instanceof BrisaApiError) {
|
|
36
|
+
console.error(e.status, e.type, e.field, e.errors)
|
|
37
|
+
} else throw e
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```php
|
|
42
|
+
use Brisa\Exception\{RuleException, ValidationException, ApiException};
|
|
43
|
+
|
|
44
|
+
try {
|
|
45
|
+
$brisa->documents->issue($pedido);
|
|
46
|
+
} catch (ValidationException $e) { // 400: $e->errors()
|
|
47
|
+
} catch (RuleException $e) { // 422: $e->field()
|
|
48
|
+
} catch (ApiException $e) { // os outros: $e->status(), $e->type()
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Os `429`, `502` e `503` já foram repetidos pelo SDK antes de o erro chegar até si.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Idempotência e limites
|
|
2
|
+
|
|
3
|
+
## Idempotência
|
|
4
|
+
|
|
5
|
+
Imagine que emite uma fatura e a ligação cai antes de ver a resposta. Repetir sem cuidado emitiria **duas** faturas. O cabeçalho `Idempotency-Key` resolve isso: repetir um pedido com a mesma chave devolve o mesmo resultado.
|
|
6
|
+
|
|
7
|
+
A API exige-o às chaves de API em emitir, pagar, liquidar várias faturas e notas de crédito, e recomenda-o em retificar, criar cliente e mover stock.
|
|
8
|
+
|
|
9
|
+
O SDK gera uma chave sozinho e **reutiliza-a nas repetições automáticas**. Se o seu sistema também repete (uma fila, um *job*), dê uma chave **sua**, estável por operação:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
curl https://api.brisa.ao/api/v1/documents -H "Idempotency-Key: encomenda-77" ...
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
await brisa.documents.issue(body, { idempotencyKey: `encomenda-${encomenda.id}` })
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```php
|
|
20
|
+
$brisa->documents->issue($body, ['idempotencyKey' => 'encomenda-' . $encomenda['id']]);
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
> **Atenção:** reutilizar a chave com **outro** corpo é erro `422` (`field: "idempotency"`).
|
|
24
|
+
|
|
25
|
+
## Limites
|
|
26
|
+
|
|
27
|
+
Por omissão há 600 pedidos por minuto por chave (o PDF e o SAF-T contam como mais de um). Cada resposta traz `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. Num `429`, o SDK espera o tempo de `Retry-After` e repete.
|
|
28
|
+
|
|
29
|
+
Se precisa de mais, fale connosco: geral@codespace.ao.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Sandbox e produção
|
|
2
|
+
|
|
3
|
+
A **sandbox** é uma cópia de brincar: nada é enviado à AGT, os números não contam e pode apagar tudo. A **produção** emite documentos certificados.
|
|
4
|
+
|
|
5
|
+
## O que muda ao passar
|
|
6
|
+
|
|
7
|
+
Só a chave. O endereço é o mesmo, `https://api.brisa.ao`; a chave escolhe o ambiente.
|
|
8
|
+
|
|
9
|
+
| | Sandbox | Produção |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| Chave | `brk_sbx_...` | `brk_...` |
|
|
12
|
+
| AGT | nada é enviado | comunicação em tempo real |
|
|
13
|
+
| Numeração | de teste | fiscal, sem saltos |
|
|
14
|
+
| Plano | qualquer | com acesso à API |
|
|
15
|
+
|
|
16
|
+
## Lista de verificação antes de ir para produção
|
|
17
|
+
|
|
18
|
+
1. **Faturação eletrónica ativa** na empresa (adesão na AGT e chave privada carregada na aplicação).
|
|
19
|
+
2. **Chave de produção** criada, com as permissões mínimas, guardada como segredo.
|
|
20
|
+
3. **Idempotência** em todas as criações: ver [Idempotência](12-idempotencia-e-limites.md).
|
|
21
|
+
4. **Webhooks** registados e com a assinatura verificada: ver [Webhooks](10-webhooks.md).
|
|
22
|
+
5. **Erros e limites** tratados: ver [Erros](11-erros.md).
|
|
23
|
+
6. Fez um **ensaio completo** na sandbox: emitir, pagar, anular, imprimir, SAF-T.
|
|
24
|
+
|
|
25
|
+
> **Nota:** a sandbox usa dados à parte. Clientes e artigos criados nela não existem em produção: crie-os também lá.
|
package/docs/README.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Documentação da API Brisa
|
|
2
|
+
|
|
3
|
+
A Brisa é a faturação eletrónica certificada pela AGT (Angola). Esta documentação ensina a usar a API e os SDKs para emitir faturas, receber pagamentos, imprimir, exportar o SAF-T e reagir a eventos, do primeiro pedido à produção.
|
|
4
|
+
|
|
5
|
+
Cada página começa pelo que precisa de saber, mostra o caminho mais curto com código que pode copiar, e só depois entra nos detalhes. Os exemplos aparecem sempre em **cURL**, **JavaScript** e **PHP**.
|
|
6
|
+
|
|
7
|
+
## Por onde começar
|
|
8
|
+
|
|
9
|
+
| Quero... | Leia |
|
|
10
|
+
|---|---|
|
|
11
|
+
| Emitir a minha primeira fatura em 5 minutos | [Primeiros passos](01-primeiros-passos.md) |
|
|
12
|
+
| Perceber como me autentico e que permissões tenho | [Autenticação](02-autenticacao.md) |
|
|
13
|
+
| Conhecer os tipos de documento e o que se pode fazer com cada um | [Documentos](03-documentos.md) |
|
|
14
|
+
| Receber pagamentos, também com vários meios no mesmo talão | [Pagamentos](04-pagamentos.md) |
|
|
15
|
+
| Imprimir em A4, A5 ou em rolo de 58 e 80 mm | [Impressão](05-impressao.md) |
|
|
16
|
+
| Pôr os dados bancários nas faturas por pagar | [Dados bancários](06-dados-bancarios.md) |
|
|
17
|
+
| Ver o que cada cliente deve e imprimir o extrato | [Clientes e extrato](07-clientes-e-extrato.md) |
|
|
18
|
+
| Gerir artigos e stock | [Artigos e stock](08-artigos-e-stock.md) |
|
|
19
|
+
| Exportar o SAF-T | [SAF-T](09-saft.md) |
|
|
20
|
+
| Ser avisado quando algo acontece | [Webhooks](10-webhooks.md) |
|
|
21
|
+
| Tratar erros, repetições e limites | [Erros](11-erros.md), [Idempotência e limites](12-idempotencia-e-limites.md) |
|
|
22
|
+
| Passar da sandbox para a produção | [Sandbox e produção](13-sandbox-e-producao.md) |
|
|
23
|
+
| Atualizar de uma versão anterior | [Guia de atualização](upgrade.md) |
|
|
24
|
+
|
|
25
|
+
## Como a API pensa
|
|
26
|
+
|
|
27
|
+
* **Uma API, dois ambientes.** O endereço é sempre `https://api.brisa.ao`. É a **chave** que escolhe o ambiente: `brk_sbx_...` é a sandbox (nada vai à AGT), `brk_...` é a produção.
|
|
28
|
+
* **Tudo o que cria é idempotente.** Repetir um pedido com o mesmo `Idempotency-Key` devolve o mesmo resultado, por isso uma falha de rede nunca emite dois documentos.
|
|
29
|
+
* **Erros que se podem programar.** Seguem a norma [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457): um `status`, um `type` estável e, quando é uma regra fiscal, o `field` em causa.
|
|
30
|
+
* **Dinheiro e datas.** Valores em kwanzas (AOA) com duas casas decimais; datas em `AAAA-MM-DD`.
|
|
31
|
+
|
|
32
|
+
## Mais
|
|
33
|
+
|
|
34
|
+
* Referência completa dos endpoints: [`openapi.json`](https://github.com/codespace-ao/brisa-sdk-js/blob/main/docs/openapi.json) (gerado do código da API) ou a página [brisa.ao/developers](https://brisa.ao/developers).
|
|
35
|
+
* Dúvidas e ideias: abra uma [issue](https://github.com/codespace-ao/brisa-sdk-js/issues). Quer contribuir? Leia o [guia de contribuição](../CONTRIBUTING.md).
|