Registrar Fatura (SAFT)
Produção:
POST/api/v1/saft/registrarFatura
Homologação:
POST/api/v1/hml/saft/registrarFatura
Descrição de Todos os Atributos (Draft)
| Campo |
Tipo |
Obrigatório |
Descrição Detalhada |
| companyToken |
String |
Sim |
Token de identificação da empresa cadastrada no sistema.
|
| invoces |
Array (Required) |
Sim |
Objeto principal que contém os dados do documento fiscal.
|
| documentType |
Array |
Sim |
Tipo de documento: (FT, FR, FP, RC, NC), Fatura,
Fatura-Recibo, Proforma, Recibo ou Nota de Crédito.
|
| customerTaxID |
String (Required) |
Sim |
NIF do cliente. Use 999999999 para consumidor final. |
| paymentMethod |
String |
Sim |
Meio de pagamento, (CC, CD, CH, MB, NU, TB, OU), (Ex: NU =
Numerário, TB = Transferência).
|
| documentDate |
Y-m-d H:i:s |
Sim |
Data de emissão. Obrigatória se for enviado um hash
anterior.
|
| systemEntryDate |
DateTime |
Sim |
Data e hora da gravação do documento no sistema de origem.
|
| sales_operator |
String (Required) |
Sim |
Nome do operador ou utilizador que emitiu a fatura. |
| customerName |
String (Required) |
Sim |
Nome ou Razão Social do cliente. |
| customerNumber |
String (Required) |
Sim |
Número identificador do cliente no software de origem.
|
| Campo |
Tipo |
Obrigatório |
Descrição Detalhada |
| documentVersion |
Boolean |
Sim |
Define a versão do layout do documento. |
| withholding_tax |
Numeric (min: 0) |
Sim |
Valor da Retenção na Fonte, caso exista. |
| purchase_order_number |
String (Required) |
Sim |
Referência da Nota de Encomenda do cliente. |
| message |
String (Required) |
Sim |
Observações ou notas de rodapé que aparecerão no documento.
|
| iban |
String (Required) |
Sim |
IBAN da conta bancária para recebimento. |
| account_number |
String (Required) |
Sim |
Número da conta bancária associada. |
| reference.documentNo |
String |
Sim |
Para Notas de Crédito, refere o documento original. Formato:
'FT SERIE/NUMERO'.
|
| hash1 |
String |
|
Assinatura (Hash) do documento anterior na sequência da
série.
|
| hash2 |
String |
|
Chave de controle do encadeamento de segurança. |
| hash3 |
String |
|
Chave de controle do encadeamento de segurança. |
Itens do Documento (invoces.lines)
| Campo da Linha |
Regra |
Obrigatório |
Descrição |
| productCode |
String (Required) |
sim |
Código identificador do produto ou serviço. |
| productDescription |
String (Required) |
sim |
Nome ou descrição detalhada do item. |
| quantity |
Numeric (min: 0.01) |
sim |
Quantidade faturada (não pode ser zero). |
| unitOfMeasure |
String (Required) |
sim |
Unidade de medida (Ex: UN, KG, CX). |
| unitPrice |
Numeric (min: 1) |
sim |
Preço unitário antes de impostos e descontos. |
| taxType |
String |
sim |
Tipo de imposto aplicado à linha (IVA). |
| taxCountryRegion |
AO (Fixed) |
sim |
Região fiscal (Angola). |
| taxCode |
String |
sim |
NOR para Taxa Normal ou ISE para Isenção. |
| taxPercentage |
double |
sim |
Percentagem do imposto aplicado (0 a 14). |
| settlementAmount |
Numeric |
sim |
Valor monetário do desconto aplicado à linha. |
| reason |
String |
|
Motivo da isenção. Obrigatório se taxCode for ISE. |
Resposta
NOTA DE SEGURANÇA:
É CRÍTICO
que a sua aplicação armazene todos os campos abaixo. Eles são
necessários para autenticar a integridade do documento em
consultas futuras e para a geração de relatórios SAFT-AO.
200 OK
404 Requisição não encontrada
{
"companyToken": "7ab54db0-b223-46be-aba9-2a58998af53d",
"invoices": {
"documentDate": "2026-01-31 23:45:10",
"documentType": "FT",
"systemEntryDate": "2026-03-19T22:00:00Z",
"sales_operator": "Nelson M. Zeferino",
"customerTaxID": "999999999",
"customerName": "Desconhecido",
"customerNumber": "999999999",
"documentVersion": true,
"withholding_tax": 0,
"purchase_order_number": "PO nº 2026/001",
"message": "Factura Referente ao Mes de JANEIRO de 2026...",
"iban": "004000004078368915",
"account_number": "1234567891011",
"paymentMethod": "NU",
"lines": [
{
"productCode": "P001",
"productDescription": "Caneta Azul",
"quantity": 2,
"unitOfMeasure": "UN",
"unitPrice": 250.00,
"taxType": "IVA",
"taxCountryRegion": "AO",
"taxCode": "NOR",
"taxPercentage": 14,
"settlementAmount": 100,
"withholding_tax": 6.5
}
]
}
}
{
"status": true,
"documentNo": "FT HSC2026/26",
"documentDate": "2026-03-22 01:31:51",
"documentSatus": "N",
"taxPayable": "126.00",
"netTotal": "15900.00",
"grossTotal": "16026.00",
"hash1": "Qn03+uncpeDbhjcbDSs9bhum5TIgY4Rgp0e2SlBx5qniJTRKB5ew6YMuvuKn56Dh...",
"hash2": "FVEOcK32zBrcCOe/dcVY+qrbzDEy/RoTVQO/AGWvjSd+hX+cT7PrMZU6CI9VEX+RIjXqNOtO80F11qHjGIs2rQyYUZV0KKmlGoK7+mYV2qRree5QbyQUTbmqJPVNdSeo9Q9DhiPssmfU+DYPG0ea4lfm4UqOtiBV8Y9wECW0dxY=",
"hash3": "Fr+o"
}
