@veroao/node 1.0.0 → 1.1.0

package/README.md

@@ -130,6 +130,24 @@ await vero.invoices.send(orgId, invoice.id)
 `documentType: 'FR'` fica com `status: 'paid'` imediatamente (já está pago); `'FT'` fica `'issued'`
 até seres tu a marcar como pago via `vero.receipts.create`.
 
+**Retenção na fonte** (Art. 67º do Código do Imposto Industrial, tipicamente 6,5% sobre serviços) -
+opcional, desligada por omissão. Só tem efeito se a organização a tiver activada no dashboard
+(Definições → Perfil → Retenção na fonte):
+
+```typescript
+const invoice = await vero.invoices.create(orgId, {
+  customerId: 'uuid...',
+  items: [{ description: 'Consultoria', quantity: 1, unitPrice: 50000000, taxRate: 14 }],
+  applyWithholdingTax: true,
+})
+
+invoice.withholdingTax // { type: 'II', rate: 650, amount: 3250000, description: '...' } ou null
+```
+
+Não altera `subtotal`/`taxAmount`/`total` (continuam o valor fiscal oficial da factura) - a retenção
+viaja à parte, tanto na resposta como no documento submetido à AGT. O cálculo é sempre feito no
+servidor a partir das definições da organização, nunca a partir de um valor que envies.
+
 ### `vero.proformas`
 
 ```typescript
@@ -148,6 +166,15 @@ await vero.proformas.cancel(orgId, proforma.id)
 
 Proformas não têm valor fiscal - servem só de orçamento até seres convertidas em factura.
 
+Aceitam a mesma **retenção na fonte** que as facturas (`applyWithholdingTax: true`, ver secção
+`vero.invoices` acima) - transporta-se automaticamente para a factura ao converteres, sem precisares
+de a pedir outra vez em `vero.proformas.convert`. Também podes activá-la ou mudá-la numa proforma já
+criada, enquanto estiver em `draft`:
+
+```typescript
+await vero.proformas.update(orgId, proforma.id, { applyWithholdingTax: true })
+```
+
 ### `vero.creditNotes`
 
 ```typescript
@@ -259,6 +286,12 @@ unitPrice: 150_050    // 1 500,50 AOA
 | `VERO_API_KEY`      | Chave secreta da API (recomendado)                                |
 | `VERO_SECRET_KEY`   | Alias legado - usado só se `VERO_API_KEY` não estiver definida    |
 
+## A implementar com Claude Code ou outro agente de IA?
+
+Aponta o teu assistente para [vero.ao/vero-skill.md](https://vero.ao/vero-skill.md) - um skill
+com o essencial da API da Vero (autenticação, endpoints, formatos e erros comuns) pronto a
+carregar, sem teres de colar documentação à mão.
+
 ## O teu backend não é Node?
 
 Este pacote é só uma comodidade - por baixo é tudo pedidos HTTPS normais (`Authorization: Bearer

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { VeroConfig, ListResult, Customer, CreateCustomerInput, UpdateCustomerInput, EnsureCustomerInput, ListCustomersParams, Invoice, CreateInvoiceInput, ListInvoicesParams, ProformaInvoice, CreateProformaInput, ListProformasParams, CreditNote, DebitNote, CreateDebitNoteInput, Receipt, CreateReceiptInput, Product, CreateProductInput, UpdateProductInput, Webhook, RegisterWebhookInput } from './types.js';
+import type { VeroConfig, ListResult, Customer, CreateCustomerInput, UpdateCustomerInput, EnsureCustomerInput, ListCustomersParams, Invoice, CreateInvoiceInput, ListInvoicesParams, ProformaInvoice, CreateProformaInput, UpdateProformaInput, ListProformasParams, CreditNote, DebitNote, CreateDebitNoteInput, Receipt, CreateReceiptInput, Product, CreateProductInput, UpdateProductInput, Webhook, RegisterWebhookInput } from './types.js';
 declare class HttpClient {
     readonly baseUrl: string;
     private readonly secretKey;
@@ -58,6 +58,8 @@ declare class ProformasResource {
     create(orgId: string, input: CreateProformaInput): Promise<ProformaInvoice>;
     list(orgId: string, params?: ListProformasParams): Promise<ListResult<ProformaInvoice>>;
     get(orgId: string, proformaId: string): Promise<ProformaInvoice>;
+    /** Actualiza itens, notas, validade ou retenção — só enquanto a proforma estiver em 'draft'. */
+    update(orgId: string, proformaId: string, input: UpdateProformaInput): Promise<ProformaInvoice>;
     /** Converte pró-forma em fatura definitiva certificada — sem corpo, usa os dados já na proforma */
     convert(orgId: string, proformaId: string): Promise<Invoice>;
     /** Anula a proforma (não pode ser desfeito) */

package/dist/client.js

@@ -171,6 +171,10 @@ class ProformasResource {
     get(orgId, proformaId) {
         return this.http.get(`/v1/organisations/${orgId}/proformas/${proformaId}`);
     }
+    /** Actualiza itens, notas, validade ou retenção — só enquanto a proforma estiver em 'draft'. */
+    update(orgId, proformaId, input) {
+        return this.http.patch(`/v1/organisations/${orgId}/proformas/${proformaId}`, input);
+    }
     /** Converte pró-forma em fatura definitiva certificada — sem corpo, usa os dados já na proforma */
     convert(orgId, proformaId) {
         return this.http.post(`/v1/organisations/${orgId}/proformas/${proformaId}/convert`);

package/dist/types.d.ts

@@ -27,9 +27,15 @@ export interface InvoiceItem {
     quantity: number;
     /** Preço unitário em kwanzas × 100 (ex: 10000 = 100 AOA) */
     unitPrice: number;
-    /** Taxa IVA Angola: 0 = isento, 5 = reduzida, 14 = normal (default: 14) */
+    /**
+     * Taxa IVA Angola: 0 = isento, 5 = reduzida, 14 = normal. Opcional - se
+     * omitida, o servidor resolve-a a partir do regime de IVA configurado na
+     * organização (default 14% se a organização não tiver regime configurado).
+     * Organizações em regime isento/simplificado rejeitam (422) qualquer
+     * taxRate enviado que não seja 0.
+     */
     taxRate?: 0 | 5 | 14;
-    /** Obrigatório junto da AGT quando taxRate = 0 (máx. 4 caracteres, ex: "M19") */
+    /** Obrigatório junto da AGT quando taxRate resultar em 0 (máx. 4 caracteres, ex: "M19") */
     taxExemptionCode?: string;
     /** ID do produto do catálogo (opcional) */
     productId?: string;
@@ -86,6 +92,21 @@ export interface AgtError {
     idError?: string;
     descriptionError?: string;
 }
+/**
+ * Retenção na fonte (Art. 67º do Código do Imposto Industrial) declarada nesta
+ * factura — null quando não aplicada. NÃO altera subtotal/taxAmount/total (esses
+ * continuam o valor fiscal oficial); é informação adicional enviada à AGT à parte
+ * (só existe quando a organização activou isto nas definições do Vero).
+ */
+export interface WithholdingTax {
+    /** 'II' = Imposto Industrial, 'IRT' = pessoa singular/ENI */
+    type: 'II' | 'IRT';
+    /** Percentagem × 100 — ex: 650 = 6,50% */
+    rate: number;
+    /** Valor retido, em kwanzas × 100 */
+    amount: number;
+    description: string;
+}
 export interface Invoice {
     id: string;
     orgId: string;
@@ -113,6 +134,8 @@ export interface Invoice {
     /** Estado da validação na AGT — consulta depois de criar, a submissão é assíncrona */
     agtStatus?: AgtStatus;
     agtErrors?: AgtError[] | null;
+    /** Presente só quando a organização tem retenção na fonte activada e pedida nesta factura */
+    withholdingTax?: WithholdingTax | null;
     notes?: string | null;
     issuedAt?: string | null;
     cancelledAt?: string | null;
@@ -127,6 +150,12 @@ export interface CreateInvoiceInput {
     notes?: string;
     /** Chave de idempotência — gerada automaticamente se omitida */
     idempotencyKey?: string;
+    /**
+     * Pede para aplicar a retenção na fonte configurada na organização (Definições
+     * → Retenção na fonte). Sem efeito se a organização não a tiver activada, ou se
+     * o valor da factura não ultrapassar o limiar mínimo configurado.
+     */
+    applyWithholdingTax?: boolean;
 }
 export interface ListInvoicesParams extends ListParams {
     status?: InvoiceStatus;
@@ -151,6 +180,8 @@ export interface ProformaInvoice {
     convertedAt?: string | null;
     notes?: string | null;
     validUntil?: string | null;
+    /** Presente só quando a organização tem retenção na fonte activada e pedida nesta proforma */
+    withholdingTax?: WithholdingTax | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -160,6 +191,22 @@ export interface CreateProformaInput {
     notes?: string;
     /** Data limite de validade (ISO 8601: "2026-12-31") */
     validUntil?: string;
+    /**
+     * Pede para aplicar a retenção na fonte configurada na organização (Definições
+     * → Retenção na fonte). Sem efeito se a organização não a tiver activada, ou se
+     * o valor da proforma não ultrapassar o limiar mínimo configurado. Transportada
+     * para a factura final ao converter (proformas.convert).
+     */
+    applyWithholdingTax?: boolean;
+}
+export interface UpdateProformaInput {
+    customerId?: string;
+    items?: InvoiceItem[];
+    notes?: string;
+    /** Data limite de validade (ISO 8601: "2026-12-31") */
+    validUntil?: string;
+    /** Activa/desliga a retenção na fonte pedida nesta proforma - ver CreateProformaInput. */
+    applyWithholdingTax?: boolean;
 }
 export interface ListProformasParams extends ListParams {
     status?: ProformaStatus;
@@ -263,6 +310,8 @@ export interface Product {
     taxRate: 0 | 5 | 14;
     /** Obrigatório quando taxRate = 0 */
     taxExemptionCode?: string | null;
+    /** 'product' (bem, pode ter stock) ou 'service' (prestação de serviço, nunca tem stock). Default 'product' */
+    type: 'product' | 'service';
     /** Default 'UN' */
     unitOfMeasure: string;
     active: boolean;
@@ -280,6 +329,8 @@ export interface CreateProductInput {
     /** Default 14 */
     taxRate?: 0 | 5 | 14;
     taxExemptionCode?: string;
+    /** 'product' (default) ou 'service'. Um serviço não tem stock: trackStock é ignorado. */
+    type?: 'product' | 'service';
     /** Default 'UN' */
     unitOfMeasure?: string;
     trackStock?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veroao/node",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Vero SDK for Node.js — faturação certificada AGT para Angola",
   "type": "module",
   "main": "./dist/index.js",