Submeter Documentos

A submissão é sempre assíncrona: recebes um requestId de imediato; o resultado (aceite/rejeitado pela AGT) fica disponível depois em Consultar Estado ou via webhook.

Um documento por pedido

O jeito mais simples — um endpoint por tipo de documento:

POST /v1/client/factura/ft
POST /v1/client/factura/fa
POST /v1/client/factura/fr
POST /v1/client/factura/fg
POST /v1/client/factura/gf
POST /v1/client/factura/ac
POST /v1/client/factura/ar
POST /v1/client/factura/tv
POST /v1/client/factura/rc
POST /v1/client/factura/rg
POST /v1/client/factura/re
POST /v1/client/factura/nd
POST /v1/client/factura/nc
POST /v1/client/factura/af
POST /v1/client/factura/rp
POST /v1/client/factura/ra
POST /v1/client/factura/cs
POST /v1/client/factura/ld

Envia apenas os campos do documento (ver “Campos” abaixo). O NIF do emissor é preenchido automaticamente a partir da tua conta.

curl -X POST https://<host>/v1/client/factura/ft \
  -H "X-API-Key: agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "FT",
    "documentDate": "2026-07-27",
    "systemEntryDate": "2026-07-27T10:00:00Z",
    "customerTaxID": "999999999",
    "companyName": "Cliente Final",
    "documentTotals": { "netTotal": 500.0, "taxPayable": 70.0, "grossTotal": 570.0 },
    "lines": [
      {
        "lineNumber": 1,
        "productCode": "SERV001",
        "productDescription": "Serviço de consultoria",
        "quantity": 1,
        "unitOfMeasure": "UN",
        "unitPriceBase": 500.0,
        "unitPrice": 500.0,
        "creditAmount": 500.0,
        "taxes": [{ "taxType": "IVA", "taxPercentage": 14, "taxAmount": 70.0, "taxContribution": 70.0 }]
      }
    ]
  }'

const res = await fetch('https://<host>/v1/client/factura/ft', {
  method: 'POST',
  headers: {
    'X-API-Key': 'agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documentType: 'FT',
    documentDate: '2026-07-27',
    systemEntryDate: '2026-07-27T10:00:00Z',
    customerTaxID: '999999999',
    companyName: 'Cliente Final',
    documentTotals: { netTotal: 500.0, taxPayable: 70.0, grossTotal: 570.0 },
    lines: [
      {
        lineNumber: 1,
        productCode: 'SERV001',
        productDescription: 'Serviço de consultoria',
        quantity: 1,
        unitOfMeasure: 'UN',
        unitPriceBase: 500.0,
        unitPrice: 500.0,
        creditAmount: 500.0,
        taxes: [{ taxType: 'IVA', taxPercentage: 14, taxAmount: 70.0, taxContribution: 70.0 }]
      }
    ]
  })
})
const { requestId } = await res.json()

import requests
 
response = requests.post(
    "https://<host>/v1/client/factura/ft",
    headers={"X-API-Key": "agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "documentType": "FT",
        "documentDate": "2026-07-27",
        "systemEntryDate": "2026-07-27T10:00:00Z",
        "customerTaxID": "999999999",
        "companyName": "Cliente Final",
        "documentTotals": {"netTotal": 500.0, "taxPayable": 70.0, "grossTotal": 570.0},
        "lines": [
            {
                "lineNumber": 1,
                "productCode": "SERV001",
                "productDescription": "Serviço de consultoria",
                "quantity": 1,
                "unitOfMeasure": "UN",
                "unitPriceBase": 500.0,
                "unitPrice": 500.0,
                "creditAmount": 500.0,
                "taxes": [{"taxType": "IVA", "taxPercentage": 14, "taxAmount": 70.0, "taxContribution": 70.0}],
            }
        ],
    },
)
request_id = response.json()["requestId"]

<?php
 
$ch = curl_init('https://<host>/v1/client/factura/ft');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'documentType' => 'FT',
    'documentDate' => '2026-07-27',
    'systemEntryDate' => '2026-07-27T10:00:00Z',
    'customerTaxID' => '999999999',
    'companyName' => 'Cliente Final',
    'documentTotals' => ['netTotal' => 500.0, 'taxPayable' => 70.0, 'grossTotal' => 570.0],
    'lines' => [[
        'lineNumber' => 1,
        'productCode' => 'SERV001',
        'productDescription' => 'Serviço de consultoria',
        'quantity' => 1,
        'unitOfMeasure' => 'UN',
        'unitPriceBase' => 500.0,
        'unitPrice' => 500.0,
        'creditAmount' => 500.0,
        'taxes' => [['taxType' => 'IVA', 'taxPercentage' => 14, 'taxAmount' => 70.0, 'taxContribution' => 70.0]],
    ]],
]));
 
$response = json_decode(curl_exec($ch), true);
echo $response['requestId'];

Resposta:

{ "requestId": "uuid", "agtRequestId": "202500000000118", "documentNo": "FT FT2026/1", "message": "Documento FT processado com sucesso" }

Em lote (até 30 documentos)

POST /v1/client/facturas

Útil para enviar vários documentos (de tipos diferentes entre si) num único pedido. Se só precisas de submeter um documento de cada vez, usa antes os endpoints individuais acima — são mais simples e não exigem o bloco softwareInfo abaixo.

{
  "submissionTimeStamp": "2026-07-27T10:00:00Z",
  "softwareInfo": {
    "softwareInfoDetail": { "productId": "x", "productVersion": "x", "softwareValidationNumber": "x" },
    "jwsSoftwareSignature": "xxxxxxxxxx"
  },
  "numberOfEntries": 1,
  "documents": [ /* 1 a 30 documentos, cada um com o formato acima */ ]
}

A assinatura de software é sempre gerada pelo próprio Gateway — o softwareInfo que envias aqui não é usado. Ainda assim, este endpoint exige o campo preenchido (com qualquer texto não-vazio) só para passar a validação do pedido; omiti-lo dá erro 422. numberOfEntries tem de corresponder ao número de itens em documents.

Resposta:

{ "requestId": "uuid", "message": "Solicitação de registo enfileirada" }

Tipos de documento

Código	Documento
`FT`	Factura
`FA`	Factura de Adiantamento
`FR`	Factura/Recibo
`FG`	Factura Global
`GF`	Factura Genérica
`AC`	Aviso de Cobrança
`AR`	Aviso de Cobrança/Recibo
`TV`	Talão de Venda
`RC`	Recibo
`RG`	Recibo Geral
`RE`	Estorno/Devolução
`ND`	Nota de Débito
`NC`	Nota de Crédito
`AF`	Autofacturação
`RP`	Prémio de Seguro
`RA`	Resseguro Aceite
`CS`	Imputação a Co-seguradoras
`LD`	Imputação a Co-seguradora Líder

Campos do documento

Campo	Obrigatório	Notas
`documentDate`	sim	formato `AAAA-MM-DD`
`systemEntryDate`	sim	ISO 8601
`customerTaxID`	sim	NIF do cliente; usa `999999999` para consumidor final
`companyName`	sim	nome do cliente
`documentTotals`	sim	`{netTotal, taxPayable, grossTotal}` — ver validações abaixo
`documentNo`	não	gerado automaticamente a partir da série activa se omitido
`customerCountry`	não	padrão `AO`
`customerAddress`	não
`withholdingTaxList`	não	retenções na fonte, ver Referência
`currency`	não	só se a moeda não for AOA

Sobre o documentNo: Se não for enviado na requisição, o sistema irá gerá-lo automaticamente com base na série activa. No entanto, para que isso funcione, é necessário que o cliente já tenha criado uma Série activa para o tipo de documento correspondente.

Linhas (`lines`) — `FT`, `FA`, `FR`, `FG`, `GF`, `AC`, `TV`, `RE`, `ND`, `NC`, `AF`, `RP`, `RA`, `CS`, `LD`

{
  "lineNumber": 1,
  "productCode": "SERV001",
  "productDescription": "Serviço de consultoria",
  "quantity": 1,
  "unitOfMeasure": "UN",
  "unitPriceBase": 500.0,
  "unitPrice": 500.0,
  "creditAmount": 500.0,
  "taxes": [{ "taxType": "IVA", "taxPercentage": 14, "taxAmount": 70.0, "taxContribution": 70.0 }]
}

Validações:

lineNumber tem de ser sequencial a partir de 1.
creditAmount e debitAmount são mutuamente exclusivos por linha (NC usa debitAmount; os restantes normalmente usam creditAmount).
documentTotals.taxPayable = soma de taxContribution de todas as linhas.
documentTotals.netTotal = soma dos valores das linhas.
documentTotals.grossTotal = netTotal + taxPayable.
taxType = "NS" ou isenção exige taxExemptionCode preenchido.
ND/NC exigem referenceInfo (referência ao documento original) em cada linha.

Recibos sem linhas (`AR`, `RC`, `RG`)

Estes três tipos usam paymentReceipt em vez de lines, referenciando o documento que está a ser pago:

{
  "paymentReceipt": {
    "sourceDocuments": [
      {
        "lineNo": 1,
        "sourceDocumentID": { "originatingON": "FT FT2026/1", "documentDate": "2026-07-20" },
        "creditAmount": 570.0
      }
    ]
  }
}

originatingON é o documentNo exacto do documento a pagar.

Consultar detalhe de um documento

POST /v1/client/factura/consultar

Este endpoint permite consultar o detalhe de uma factura previamente processada na AGT. A consulta é assíncrona, portanto receberás um requestId para acompanhar o resultado da consulta usando o Polling de Status.

curl -X POST https://<host>/v1/client/factura/consultar \
  -H "X-API-Key: agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "documentNo": "FT FT2026/1"
  }'

const res = await fetch('https://<host>/v1/client/factura/consultar', {
  method: 'POST',
  headers: {
    'X-API-Key': 'agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documentNo: 'FT FT2026/1'
  })
})
const { requestId } = await res.json()

import requests
 
response = requests.post(
    "https://<host>/v1/client/factura/consultar",
    headers={"X-API-Key": "agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "documentNo": "FT FT2026/1"
    },
)
request_id = response.json()["requestId"]

<?php
 
$ch = curl_init('https://<host>/v1/client/factura/consultar');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'documentNo' => 'FT FT2026/1'
]));
 
$response = json_decode(curl_exec($ch), true);
echo $response['requestId'];

Resposta imediata:

{
  "requestId": "uuid",
  "documentNo": "FT FT2026/1",
  "status": "RECEIVED",
  "message": "Registration request queued"
}

Após o processamento (visível via GET /v1/client/estado/status/{requestId}), receberás no campo agt_response os detalhes retornados pela AGT, incluindo o estado de validação (validationStatus) e a lista de erros (errorList).

Listar documentos por período

POST /v1/client/facturas/listar

{ "queryStartDate": "2026-07-01", "queryEndDate": "2026-07-31" }

Limites de Uso Consultar Estado