Facturação Electrónica

https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/
Admin
Facturação Electrónica is an API that enables certified billing software to automatically...
Tokens:31,835
Snippets:105
Trust Score:8.9
Update:9 months ago
Show doc for...
Tokens:
Raw
### Exemplo de Requisição com C# HttpClient usando Basic Authentication

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/api

Este exemplo demonstra como configurar Basic Authentication numa requisição GET utilizando a classe HttpClient em C#. As credenciais são convertidas para um array de bytes, codificadas em Base64 e adicionadas ao cabeçalho de autorização.

```csharp
var client = new HttpClient();

var byteArray = Encoding.ASCII.GetBytes("cliente123:s3nh@F0rte!");

client.DefaultRequestHeaders.Authorization =
   new AuthenticationHeaderValue("Basic",Convert.ToBase64String(byteArray));

var response = await client.GetAsync("https://sifphml.minfin.gov.ao/sigt/fe/v1/registarFactura");
var content = await response.Content.ReadAsStringAsync();

```

--------------------------------

### Gerar JWS com Python e Chave Privada RSA

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/estrutura

Este snippet de código demonstra como gerar um JSON Web Signature (JWS) em Python. Ele carrega uma chave privada de um arquivo, define um payload e o assina usando o algoritmo RS256. É necessário ter a biblioteca PyJWT instalada (`pip install pyjwt`).

```python
import jwt

with open("private.pem", "r") as f:
    private_key = f.read()

payload = {
    "softwareName": "ClinicaHub",
    "softwareVersion": "1.0.0",
    "softwareValidationNo": "123456789"
}

token = jwt.encode(payload, private_key, algorithm="RS256")

print(token)
```

--------------------------------

### Registar Factura - Output Payload Example (JSON)

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/registar

This is the expected JSON response after submitting an invoice registration request. It contains a 'requestID' for tracking and an 'errorList' which will be empty if the request is successful.

```json
{
    "requestID": "202500000010689",
    "errorList": []
 }

```

--------------------------------

### Registar Factura - Input Payload Example (JSON)

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/registar

This JSON payload is used to submit a request for registering an electronic invoice. It includes details about the submission, software information, and the invoice document itself. The 'jwsSoftwareSignature' and 'jwsDocumentSignature' fields are crucial for security and validation.

```json
{
    "schemaVersion": "1.2",
    "submissionUUID": "a1b2c3d4-e5f6-7890-g1h2-i23822j2232-3784",
    "taxRegistrationNumber": "5001636863",
    "submissionTimeStamp": "2025-11-04T14:30:00Z",
    "softwareInfo": {
        "softwareInfoDetail": {
            "productId": "Meu ERP CERTO",
            "productVersion": "1.0.1",
            "softwareValidationNumber": "C_134"
        },
        "jwsSoftwareSignature": "eyJ0eXAiOiJKT1NFIiwiYWxnIjoiUlMyNTYifQ.eyJwcm9kdWN0SWQiOiJNZXUgRVJQIENFUlRPIiwicHJvZHVjdFZlcnNpb24iOiIxLjAuMSIsInNvZnR3YXJlVmFsaWRhdGlvbk51bWJlciI6IkNfMTM0In0.VE3zkvOJOpqBfz4wpx4KCgcwOGgzGUP3MSMbaHCDnHhwOaeA6jlccBW9HjgQvg2tYCVVq0imrU_z0grEHNthhG4xD3afSOD1_RzvHs8Tc45dvztHJzB4gF0CAX-yIDwi7XcHiMRY0vkXOETBeHKewg0ktWSnZ7SLf4GxGzE7ry2u_pmhqhCPhxpa0oGQ_rBJUYkEAFg1OwaqjwvzCFgdT11r-XsHmnkcfJX_ktj59RWR_zgbytiCRtwCK9LNUflveS5GzUaCXbPn2deQ3F2hPldLECEa_ahwoapoK1LhkgOAVyPLJf6M1Cm09Le7rkdSaWQSW5BI_sPx5YaUaXkeqg"
    },
    "numberOfEntries": 1,
    "documents": [
        {
            "documentNo": "FT FT6325S2C/10006",
            "documentStatus": "N",
            "jwsDocumentSignature": "eyJ0eXAiOiJKT1NFIiwiYWxnIjoiUlMyNTYifQ.eyJkb2N1bWVudE5vIjoiRlQgRlQ2MzI1UzJDLzEwMDA2IiwidGF4UmVnaXN0cmF0aW9uTnVtYmVyIjoiNTAwMTYzNjg2MyIsImRvY3VtZW50VHlwZSI6IkZUIiwiZG9jdW1lbnREYXRlIjoiMjAyNS0xMS0wNCIsImN1c3RvbWVyVGF4SUQiOiJQVDk4NzY1NDMyMSIsImN1c3RvbWVyQ291bnRyeSI6IlBUIiwiY29tcGFueU5hbWUiOiJDbGllbnRlIEV4ZW1wbG8gTGRhIn0.Sg0jnyksnnXtXUkf5PaoZrRtf3kiNkw3urFaE2D1fHLLLw_hQWc896-cGbRVnJGRHPrcnOnEQqQ-ws5R51erzadVstr9Q1yUd0CIvUhszGO15t6m0H--O9VtNMWEOp2asP4P80LD4m55y5rX2stCCGAmTI2N1cAWAhw1JbRr2Zb378y8ZI8dicfJm1QDzs5YKmXrRqXH9yvaF62SHXXfpv5gzLRAAbRwjvY7roso_PRuue9Ke1w0hojnpBmr_zUg0D3eBa-eUjtVPMQsbl5DXBFhr4Qydr4Q04tvUqLBAeGpQmxTRZGs2OCjQzdz2tYIZSbEiFR9Zo6EwL1s1tsRnA",
            "documentDate": "2025-11-04",
            "documentType": "FT",
            "eacCode": "12345",
            "systemEntryDate": "2025-11-04T11:15:30Z",
            "customerTaxID": "PT987654321",
            "customerCountry": "PT",
            "companyName": "Cliente Exemplo Lda",
            "lines": [
                {
                    "lineNumber": 1,
                    "productCode": "PROD001",
                    "productDescription": "Produto Exemplo 1",
                    "quantity": 2,
                    "unitOfMeasure": "UN",
                    "unitPrice": 250,
                    "unitPriceBase": 250,
                    "debitAmount": 0,
                    "creditAmount": 500,
                    "taxes": [
                        {
                            "taxType": "IVA",
                            "taxCountryRegion": "AO",
                            "taxCode": "NOR",
                            "taxPercentage": 14,
                            "taxContribution": 70
                        }
                    ],
                    "settlementAmount": 0
                }
            ],
            "documentTotals": {
                "taxPayable": 70,
                "netTotal": 500,
                "grossTotal": 570
            },
            "withholdingTaxList": [
                {
                    "withholdingTaxType": "IRT",
                    "withholdingTaxDescription": "Retenção na fonte",
                    "withholdingTaxAmount": 16.5
                }
            ]
        }
    ]
 }

```

--------------------------------

### Introdução à API de Faturação Eletrónica

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/index

Visão geral da API, seu propósito, arquitetura e mecanismos de comunicação.

```APIDOC
## Introdução à API de Faturação Eletrónica

### Descrição
A API de Faturação Eletrónica define interfaces, regras e padrões técnicos para a comunicação automática de documentos fiscais entre softwares de faturação certificados e a Administração Tributária. Visa garantir a integridade, autenticidade e rastreabilidade dos documentos fiscais.

### Propósito da API
Permitir que softwares de faturação comuniquem documentos fiscais à Administração Tributária em tempo real, assegurando integridade e autenticidade via assinatura digital JWS, validação automática, sincronização de sistemas e rastreabilidade completa.

### Arquitetura Geral da API
A arquitetura baseia-se num modelo de comunicação assíncrona:
1. O contribuinte envia o documento JSON.
2. A API devolve um `requestID` confirmando a receção.
3. O documento entra na fila de processamento.
4. O contribuinte deve consultar o estado do documento via polling ou aguardar notificação callback (disponível em versões futuras).

Este modelo suporta grandes volumes, reduz a latência no front-end e isola falhas.

### Mecanismos de Comunicação
- **Polling**: O cliente consulta periodicamente a API para verificar a decisão final sobre o documento.
- **Callback**: (Disponível nas próximas versões) A API notifica o contribuinte através de um POST para um endpoint definido pelo cliente quando o documento é validado.
```

--------------------------------

### GET /websites/portaldoparceiro_minfin_gov_ao_doc-agt_faturacao-electronica_1/statusResult

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/consultar

Retrieves the processing status of registered invoicing documents based on a provided request ID.

```APIDOC
## GET /websites/portaldoparceiro_minfin_gov_ao_doc-agt_faturacao-electronica_1/statusResult

### Description
This endpoint allows you to query the status of a previously submitted batch of invoicing documents using its unique request ID.

### Method
GET

### Endpoint
/websites/portaldoparceiro_minfin_gov_ao_doc-agt_faturacao-electronica_1/statusResult

### Parameters
#### Query Parameters
- **requestID** (string) - Required - The identifier of the invoicing document registration request to be consulted.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **requestID** (string) - Identifier of the invoicing document registration request.
- **resultCode** (integer) - Result of the invoice registration request processing. Possible values:
  - 0: Processing complete, no invalid invoices.
  - 1: Processing complete, with valid and invalid invoices.
  - 2: Processing complete, no valid invoices.
  - 7: Request not responded due to prematurity or repetition; wait minimum period before retrying.
  - 8: Processing still in progress.
  - 9: Processing cancelled.
- **documentStatusList** (array) - Optional - Array with the processing results for each invoice in the request. Required when resultCode is not 7, 8, or 9.
  - **documentNo** (string) - Required - Unique identification of the document.
  - **documentStatus** (string) - Required - Processing result for the invoice identified in documentNo. Possible values: 'V' (Valid), 'I' (Invalid).
  - **errorList** (array) - Optional - Array with errors found during document processing. Required when documentStatus is 'I'.
    - **errorCode** (string) - Required - Error code.
    - **errorDescription** (string) - Required - Description of the error.

#### Response Example
```json
{
  "requestID": "REG1234567890",
  "resultCode": 1,
  "documentStatusList": [
    {
      "documentNo": "INV001",
      "documentStatus": "V"
    },
    {
      "documentNo": "INV002",
      "documentStatus": "I",
      "errorList": [
        {
          "errorCode": "E08",
          "errorDescription": "A assinatura do Produtor de Software \"jwsSoftwareSignature\" não está de acordo com a informação transmitida."
        }
      ]
    }
  ]
}
```

### Error Handling
- **FE-RNG-010 (E08)**: The Software Producer's signature \"jwsSoftwareSignature\" does not match the transmitted information.
- **FE-RNG-011 (E39)**: Data in the Software Producer's signature \"jwsSoftwareSignature\" does not match information in the Software Certification process.
- **FE-RNG-032 (E40)**: Data in the service call signature \"jwsSignature\" does not match information in the service call.
```

--------------------------------

### Exemplo de Payload para Consultar Estado da Fatura

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/consultar

Este snippet demonstra o formato do payload esperado para a requisição de consulta do estado da fatura. Inclui informações como versão do schema, identificador único da submissão, número fiscal do contribuinte, timestamp, e detalhes do software emissor com sua assinatura.

```json
{
    "schemaVersion": "1.2",
    "submissionUUID": "a1b2c3d4-e5f6-7890-g1h2-i238j234k5122",
    "taxRegistrationNumber": "5001636863",
    "submissionTimeStamp": "2025-09-02T14:30:00Z",
    "softwareInfo": {
        "softwareInfoDetail": {
            "productId": "Meu ERP CERTO",
            "productVersion": "1.0.1",
            "softwareValidationNumber": "C_134"
        },
        "jwsSoftwareSignature": "eyJ0eXAiOiJKT1NFIiwiYWxnIjoiUlMyNTYifQ.eyJwcm9kdWN0SWQiOiJNZXUgRVJQIENFUlRPIiwicHJvZHVjdFZlcnNpb24iOiIxLjAuMSIsInNvZnR3YXJlVmFsaWRhdGlvbk51bWJlciI6IkNfMTM0In0.VE3zkvOJOpqBfz4wpx4KCgcwOGgzGUP3MSMbaHCDnHhwOaeA6jlccBW9HjgQvg2tYCVVq0imrU_z0grEHNthhG4xD3afSOD1_RzvHs8Tc45dvztHJzB4gF0CAX-yIDwi7XcHiMRY0vkXOETBeHKewg0ktWSnZ7SLf4GxGzE7ry2u_pmhqhCPhxpa0oGQ_rBJUYkEAFg1OwaqjwvzCFgdT11r-XsHmnkcfJX_ktj59RWR_zgbytiCRtwCK9LNUflveS5GzUaCXbPn2deQ3F2hPldLECEa_ahwoapoK1LhkgOAVyPLJf6M1Cm09Le7rkdSaWQSW5BI_sPx5YaUaXkeqg"
    },
    "requestID": "202500000000118"
 }
```

--------------------------------

### Consultar Factura Response Payload - JSON

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/consultar_fatura

Example of the response payload from the 'Consultar Factura' service. It indicates the status of the document and provides details or error information.

```json
{
    "documentNo": "",
    "documentStatus": "",
    "document": "",
    "documentStatusList": [""],
    "errorList": [
        {
            "idError": "E93",
            "descriptionError": "Documento desconhecido (FT FT6325S2C/1000020)"
        }
    ]
 }
```

--------------------------------

### Exemplo de Resposta da Consulta de Estado da Fatura

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/consultar

Este snippet apresenta o formato esperado para a resposta da consulta do estado de uma fatura. Inclui o identificador da requisição, código de resultado, número fiscal e listas para o estado dos documentos e erros.

```json
{
    "requestID": "202500000000118",
    "resultCode": "2",
    "taxRegistrationNumber": "5001636863",
    "documentStatusList": [],
    "requestErrorList": []
 }
```

--------------------------------

### Consultar Factura Request Payload - JSON

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/consultar_fatura

Example of the request payload for the 'Consultar Factura' service. This JSON object contains all necessary information to query for a specific electronic invoice.

```json
{
    "schemaVersion": "1.2",
    "submissionUUID": "a1b2c3d4-e5f6-7890-g1h2-i238j234k5122",
    "taxRegistrationNumber": "5001636863",
    "submissionTimeStamp": "2025-09-02T14:30:00Z",
    "softwareInfo": {
        "softwareInfoDetail": {
            "productId": "Meu ERP CERTO",
            "productVersion": "1.0.1",
            "softwareValidationNumber": "C_134"
        },
        "jwsSoftwareSignature": "eyJ0eXAiOiJKT1NFIiwiYWxnIjoiUlMyNTYifQ.eyJwcm9kdWN0SWQiOiJNZXUgRVJQIENFUlRPIiwicHJvZHVjdFZlcnNpb24iOiIxLjAuMSIsInNvZnR3YXJlVmFsaWRhdGlvbk51bWJlciI6IkNfMTM0In0.VE3zkvOJOpqBfz4wpx4KCgcwOGgzGUP3MSMbaHCDnHhwOaeA6jlccBW9HjgQvg2tYCVVq0imrU_z0grEHNthhG4xD3afSOD1_RzvHs8Tc45dvztHJzB4gF0CAX-yIDwi7XcHiMRY0vkXOETBeHKewg0ktWSnZ7SLf4GxGzE7ry2u_pmhqhCPhxpa0oGQ_rBJUYkEAFg1OwaqjwvzCFgdT11r-XsHmnkcfJX_ktj59RWR_zgbytiCRtwCK9LNUflveS5GzUaCXbPn2deQ3F2hPldLECEa_ahwoapoK1LhkgOAVyPLJf6M1Cm09Le7rkdSaWQSW5BI_sPx5YaUaXkeqg"
    },
    "jwsSignature": "string",
    "invoiceNo": "FT FT6325S2C/1000020"
 }

```

--------------------------------

### Registar Factura - Signature Payload Example (JSON)

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/registar

This JSON payload is used to sign the invoice registration request. It contains essential invoice details required for signature generation and validation. Note that this payload is a subset of the full input payload.

```json
{
    "documentNo": "...",
    "taxRegistrationNumber": "...",
    "documentType": "...",
    "documentDate": "...",
    "customerTaxID": "...",
    "customerCountry": "...",
    "companyName": "...",
    "documentTotals": {
        "taxPayable": 70,
        "netTotal": 500,
        "grossTotal": 570
    }
 }

```

--------------------------------

### Exemplo de Requisição com JavaScript Fetch API usando Basic Authentication

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/api

Este snippet ilustra como implementar Basic Authentication numa requisição POST usando a Fetch API em JavaScript. As credenciais são manualmente codificadas em Base64 usando btoa() antes de serem incluídas no cabeçalho 'Authorization'.

```javascript
const auth = btoa("cliente123:s3nh@F0rte!");

fetch("https://sifphml.minfin.gov.ao/sigt/fe/v1/registarFactura ",{

    method: "POST",
    headers:{
        "Authorization": `Basic ${"auth"}`,
        "Content-Type": "application/json",
        "Accept": "application/json"
    }

 }).then(res => res.json()).then(console.log);

```

--------------------------------

### Geração de JWS com RS256 em C# (.NET)

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/estrutura

Exemplo de como criar uma assinatura JWS com RS256 em C# utilizando o .NET. Depende das bibliotecas System.IdentityModel.Tokens.Jwt e Microsoft.IdentityModel.Tokens. O payload é um Dictionary e a chave privada é importada de um ficheiro PEM.

```csharp
using System.IdentityModel.Tokens.Jwt;
using Microsoft.IdentityModel.Tokens;
using System.Security.Cryptography;

var payload = new Dictionary<string, object>

{
    { "softwareName", "ClinicaHub" },
    { "softwareVersion", "1.0.0" },
    { "softwareValidationNo", "123456789" }
};

var privateKey = RSA.Create();
privateKey.ImportFromPem(File.ReadAllText("private.pem"));
var credentials = new SigningCredentials(
    new RsaSecurityKey(privateKey),
    SecurityAlgorithms.RsaSha256
) ;

var token = new JwtSecurityToken(
    claims: payload.Select(kv => new Claim(kv.Key, kv.Value.ToString())), signingCredentials: credentials
);

var jwt = new JwtSecurityTokenHandler().WriteToken(token);

Console.WriteLine(jwt);
```

--------------------------------

### Exemplo de Payload de Assinatura para Consultar Estado

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/consultar

Este snippet mostra a estrutura mínima necessária para a assinatura do payload ao consultar o estado de uma fatura. Requer o número fiscal do contribuinte e o identificador da requisição.

```json
{
    "taxRegistrationNumber": "...",
    "requestID": "..."
 }
```

--------------------------------

### Exemplo de Requisição com cURL usando Basic Authentication

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/api

Este exemplo mostra como realizar uma requisição POST para a API utilizando a ferramenta cURL. O cURL simplifica o processo de Basic Authentication ao codificar automaticamente as credenciais fornecidas com a flag -u.

```curl
curl -X POST "https://sifphml.minfin.gov.ao/sigt/fe/v1/registarFactura" \
 -u cliente123:"s3nh@F0rte!" \
 -H "Accept: application/json"

```

--------------------------------

### Exemplo de Cabeçalho HTTP Completo para Requisição POST

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/api

Este snippet demonstra a estrutura de um cabeçalho HTTP completo para uma requisição POST protegida por Basic Authentication, incluindo o host, o token de autorização e os tipos de conteúdo aceitos e enviados.

```http
POST /sigt/fe/v1/registarFactura HTTP/1.1
Host: https://sifphml.minfin.gov.ao
Authorization: Basic Y2xpZW50ZTEyMzpzM25oQEYwcnRlIQ==
Content-Type: application/json
Accept: application/json
Content-Length: 524

```

--------------------------------

### Geração de JWS com RS256 em Go

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/estrutura

Este snippet demonstra a criação de uma assinatura JWS com RS256 na linguagem Go. Utiliza a biblioteca 'github.com/golang-jwt/jwt/v5' e lê a chave privada de um ficheiro PEM. O payload é um MapClaims.

```go
package main

import ("fmt" "os"
jwt "github.com/golang-jwt/jwt/v5"
)

func main(){

keyData, _ := os.ReadFile("private.pem")
privateKey, _ := jwt.ParseRSAPrivateKeyFromPEM(keyData)

payload := jwt.MapClaims
 {
    "softwareName": "ClinicaHub",
    "softwareVersion": "1.0.0",
    "softwareValidationNo": "123456789",
 }

token := jwt.NewWithClaims(jwt.SigningMethodRS256, payload)
signed, _ := token.SignedString(privateKey)
fmt.Println(signed)
}
```

--------------------------------

### Registo de Documentos de Faturação

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/registar

Permite o registo de documentos de faturação. Retorna um ID de confirmação para pedidos bem-sucedidos ou uma lista de erros em caso de falha.

```APIDOC
## POST /websites/portaldoparceiro_minfin_gov_ao_doc-agt_faturacao-electronica_1

### Description
Este endpoint permite o registo de documentos de faturação. Em caso de sucesso, retorna um `requestID` para confirmação do pedido, que será validado posteriormente. Mesmo em caso de erros de requisição duplicada, o `requestID` da primeira requisição é fornecido.

### Method
POST

### Endpoint
/websites/portaldoparceiro_minfin_gov_ao_doc-agt_faturacao-electronica_1

### Parameters
#### Request Body
(Detalhes do corpo da requisição não fornecidos no texto de entrada, mas seriam esperados aqui, incluindo o `array documents` mencionado na descrição de erro.)

### Request Example
```json
{
  "example": "(Corpo da requisição não especificado no texto de entrada)"
}
```

### Response
#### Success Response (200)
- **requestID** (string) - ID de confirmação do registo do pedido. Atributos: `maxlength: 15`.

#### Response Example
```json
{
  "requestID": "1234567890ABCDE"
}
```

#### Error Response (400)
- **errorList** (array) - Lista de erros ocorridos durante o registo do pedido.
  - **idError** (string) - Código do erro.
  - **descriptionError** (string) - Descrição do erro.
  - **documentNo** (string) - Número do documento de faturação ao qual o erro se refere. Obrigatório se o erro ocorrer num dos parâmetros incluídos no `array documents`.

#### Response Example
```json
{
  "errorList": [
    {
      "idError": "ERR001",
      "descriptionError": "Documento inválido",
      "documentNo": "FACT001"
    }
  ]
}
```
```

--------------------------------

### Geração de JWS com RS256 em Node.js

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/estrutura

Exemplo de como gerar uma assinatura JWS utilizando o algoritmo RS256 em Node.js. Requer a biblioteca 'jsonwebtoken' e um ficheiro de chave privada (private.pem). O payload é um objeto JavaScript que representa os dados a serem assinados.

```javascript
const fs = require("fs");
const jwt = require("jsonwebtoken");
const privateKey = fs.readFileSync("private.pem", "utf8");
const payload = {
    softwareName: "ClinicaHub",
    softwareVersion: "1.0.0",
    softwareValidationNo: "123456789"
};

const token = jwt.sign(payload, privateKey, { algorithm: "RS256" });

console.log(token);
```

--------------------------------

### Reference Information Object (`referenceInfo`)

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/registar

Defines the structure for the `referenceInfo` object, used to link an invoice line item to a preceding document.

```APIDOC
## Reference Information Object (`referenceInfo`)

### Description
This object provides details to reference a base invoice document, typically used when issuing credit notes or other related documents to link back to the original transaction.

### Method
N/A (This is a data structure definition)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
##### `reference` (string)
- **Required**: Yes
- **Description**: The reference identifier of the original invoice document to which this item relates.
- **Attributes**: `minlength`: 1, `maxlength`: 60

##### `reason` (string)
- **Required**: No
- **Description**: The reason for the modification or reference being made to the original document.
- **Attributes**: `maxlength`: 60

### Request Example
```json
{
  "reference": "INV-2023-001",
  "reason": "Return of goods"
}
```

### Response
#### Success Response (200)
- **`reference`** (string) - The reference of the source invoice document.
- **`reason`** (string) - The reason for the intervention on the source document.

#### Response Example
```json
{
  "reference": "INV-2023-001",
  "reason": "Return of goods"
}
```
```

--------------------------------

### currency Object Composition

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/registar

Details the fields within the 'currency' object, used for specifying non-AOA currency details for payments.

```APIDOC
## currency Object Composition

### Description
This section describes the composition of the `currency` object, used when the payment is made in a currency other than AOA.

### Fields

- **currencyCode** (string) - Required - "minlength": 3, "maxlength": 3 - Currency code according to ISO 4217 standard (excluding AOA).
- **currencyAmount** (number) - Required - "exclusiveMinimum": 0 - Total amount in the foreign currency.
- **exchangeRate** (number) - Required - "exclusiveMinimum": 0 - Exchange rate to AOA.
```

--------------------------------

### Geração de JWS com RS256 em Java

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/estrutura

Demonstração da geração de uma assinatura JWS usando o algoritmo RS256 em Java. Utiliza a biblioteca io.jsonwebtoken e requer um ficheiro de chave privada (private.pem). O payload é um Map contendo os dados a serem assinados.

```java
import java.nio.file.*;
import java.security.*;
import java.security.spec.*;
import io.jsonwebtoken.*;

String key = Files.readString(Path.of("private.pem"));
PrivateKey privateKey = Keys.privateKeyFromPem(key);
Map<String, Object> payload = Map.of(
    "softwareName", "ClinicaHub",
    "softwareVersion", "1.0.0",
    "softwareValidationNo", "123456789"
);

String jws = Jwts.builder()

.setClaims(payload)

.signWith(privateKey, SignatureAlgorithm.RS256)

.compact();

System.out.println(jws);
```

--------------------------------

### Payment Receipt Object

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/registar

Details the structure of the 'paymentReceipt' object, including source documents.

```APIDOC
## Payment Receipt Object Structure

### Description
This object defines the structure for payment receipt information, including details of the source documents being paid.

### Properties

#### `sourceDocuments`
- **Type**: array
- **Required**: Yes
- **Description**: Contains data related to the paid billing document(s).
```

--------------------------------

### Tax Composition

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/registar

Defines the properties for the 'taxes' array, detailing various tax-related fields.

```APIDOC
## Tax Object Structure

### Description
This object represents the composition of an array of taxes, detailing various tax-related fields and their attributes.

### Properties

#### `taxType`
- **Type**: string
- **Attributes**: `minlength`: 2, `maxlength`: 4
- **Required**: Yes
- **Description**: The tax system type. Possible values include:
  * `IVA` - Value Added Tax
  * `IS` - Stamp Duty
  * `IEC` - Special Consumption Tax
  * `CEOC` - Special Consumption Contribution
  * `NS` - Not subject to VAT, IS, IEC, or CEOC

#### `taxCountryRegion`
- **Type**: string
- **Attributes**: `minlength`: 2, `maxlength`: 6
- **Required**: Yes
- **Description**: The Tax Country or Region code. Uses ISO 3166-1-alpha-2 for countries, or `AO-CAB` for the Cabinda region.

#### `taxCode`
- **Type**: string
- **Attributes**: `minlength`: 2, `maxlength`: 10
- **Required**: No
- **Description**: The tax code. Its requirement depends on `taxType`. Possible values:
  * If `taxType` is `IVA`: `NOR` (Normal Rate), `INT` (Intermediate Rate), `RED` (Reduced Rate), `ISE` (Exempt), `OUT` (Other).
  * If `taxType` is `IS`: Optionally filled with IS amounts (see Annex 6.3), or `ISE` (Exempt).
  * If `taxType` is `IEC`: Optionally filled with the customs code for IEC application (see Annex 6.2), or `ISE` (Exempt).
  * If `taxType` is `CEOC`: `NOR` (Normal Rate - 10% for collective entities), `RED` (Reduced Rate - 2.5% for individuals).

#### `taxBase`
- **Type**: number
- **Attributes**: `minimum`: 0
- **Required**: No
- **Description**: The unit taxable base amount. Generated when the amount in the line refers solely to tax, and the underlying taxable base is not part of the taxpayer's revenue. Examples include rectifying invoices due to incorrect tax rates or calculating Stamp Duty on granted credit where the base is not revenue.

#### `taxPercentage`
- **Type**: number
- **Attributes**: `minimum`: 0
- **Required**: No
- **Description**: The tax rate applied as a percentage (e.g., 14 for 14%). Should be 0 for exemptions or non-subject taxes.

#### `taxAmount`
- **Type**: number
- **Attributes**: `minimum`: 0
- **Required**: No
- **Description**: The fixed amount for Stamp Duty. When multiplied by quantity, it contributes to the total tax amount for the billing document line.

#### `taxContribution`
- **Type**: number
- **Attributes**: `minimum`: 0
- **Required**: No
- **Description**: The calculated tax amount for this tax line, contributing to the document's total tax. This value should be rounded up to the next cent. Examples:
  * 23.144 rounds to 23.15
  * 0.001844 rounds to 0.01
  * 5.9999999 rounds to 6.00

#### `taxExemptionCode`
- **Type**: string
- **Attributes**: `minlength`: 3, `maxlength`: 3
- **Required**: No
- **Description**: The tax exemption reason code. Mandatory when `taxCode` is `ISE` (exempt), or when `taxType` is `NS` (Not Subject). Must be one of the codes specified in Annex 6.4 (VAT), 6.5 (IS), or 6.6 (IEC).

```

--------------------------------

### POST /services/v1/series/create

Source: https://portaldoparceiro.minfin.gov.ao/doc-agt/faturacao-electronica/1/servicos/solicitar

This endpoint is used to create a new series for electronic invoicing. It requires detailed information about the submission, including tax registration, timestamps, software details, and signature information.

```APIDOC
## POST /services/v1/series/create

### Description
This endpoint is used to create a new series for electronic invoicing. It requires detailed information about the submission, including tax registration, timestamps, software details, and signature information.

### Method
POST

### Endpoint
/services/v1/series/create

### Parameters
#### Request Body
- **schemaVersion** (string) - Required - Version of the service schema, example "1.0".
- **submissionUUID** (string) - Required - Unique identifier for the request, provided by the software in standard UUID format.
- **taxRegistrationNumber** (string) - Required - Taxpayer's fiscal number (max 15 characters).
- **submissionTimeStamp** (string) - Required - Submission timestamp in ISO 8601 format.
- **softwareInfo** (object) - Required - Object with the details of the Invoicing Software.
- **jwsSignature** (string) - Required - Digital signature of the series creation request, using the issuer's private key (Base64URL encoded).
- **seriesYear** (integer) - Required - Year associated with the invoice numbering series.
- **documentType** (string) - Required - Type of electronic invoicing document (e.g., FA, FT, FR) (2 characters).
- **establishmentNumber** (string) - Required - Identifies the establishment requesting invoice issuance (min 1, max 200 characters).
- **seriesContingencyIndicator** (string) - Required - Indicator for contingency issuance (N for normal, C for contingency) (1 character).

#### Request Body - softwareInfo Object
- **softwareInfoDetail** (object) - Required - Object with the details of the Invoicing Software.
- **jwsSoftwareSignature** (string) - Required - Digital signature of the Invoicing Software (min 256, max 256 characters).

#### Request Body - softwareInfoDetail Object
- **productId** (string) - Required - Name of the Invoicing Software.
- **productVersion** (string) - Required - Version of the Invoicing Software.
- **softwareValidationNumber** (string) - Required - Certification Number of the Invoicing Software.

### Request Example
```json
{
  "schemaVersion": "1.0",
  "submissionUUID": "550e8400-e29b-41d4-a716-446655440000",
  "taxRegistrationNumber": "123456789",
  "submissionTimeStamp": "2025-05-27T14:30:00Z",
  "softwareInfo": {
    "softwareInfoDetail": {
      "productId": "SoftwareX",
      "productVersion": "2.1.0",
      "softwareValidationNumber": "SW12345"
    },
    "jwsSoftwareSignature": "a.b.c"
  },
  "jwsSignature": "d.e.f",
  "seriesYear": 2024,
  "documentType": "FT",
  "establishmentNumber": "EST001",
  "seriesContingencyIndicator": "N"
}
```

### Response
#### Success Response (200)
- **seriesFEResult** (object) - Details of the authorized invoice series, including quantity and first/last authorized invoices.

#### Response Example (Success)
```json
{
  "seriesFEResult": {
    "authorizedQuantity": 1000,
    "firstAuthorized": 1,
    "lastAuthorized": 1000
  }
}
```

#### Error Response (400)
- **errorList** (array) - A list of errors encountered during request processing.

#### Response Example (Error)
```json
{
  "errorList": [
    {
      "code": "ERR-001",
      "message": "Invalid tax registration number."
    }
  ]
}
```
```
Tokens:
Raw