API v1 DOCUMENTAÇÃO PARA PROGRAMADORES

Da primeira chamada
à confirmação do pagamento.

Crie cobranças por referência, acompanhe os pagamentos e integre documentos fiscais no seu produto. Comece localmente e mantenha o mesmo contrato em Sandbox e Produção.

Criar a primeira cobrança Consultar OpenAPI

1 · CRIARPOST /paymentsObtenha a referência

2 · ACOMPANHARGET /payments/{id}Consulte o estado

3 · CONFIRMARpayment.paidReceba o evento

https://nexo.seruvo.vitorperez.dev.br/api/v1

O endereço acompanha o domínio e a porta da instalação. Em homologação e produção, utilize a origem HTTPS publicada. Os exemplos não executam pedidos a partir desta página.

Antes da primeira chamada

Prepare a conta no portal

O registo e a configuração fazem-se uma vez, no portal. A partir daí, o dia-a-dia corre pela API com a chave do projecto: cobranças, renovações, cancelamentos, documentos fiscais, catálogo e eventos. Uma plataforma com muitas empresas pode também criá-las e configurá-las pela API.

Crie a conta
Em Criar conta, indique o nome, o email, a palavra-passe e a organização. Confirme o email recebido. O registo cria a organização, um primeiro projecto e o acesso ao ambiente Sandbox. O acesso a Produção é concedido depois pela administração da plataforma.
Adicione a empresa
Em Empresas → Adicionar empresa, registe cada empresa que vai cobrar. A empresa fica autorizada ao projecto e aparece em GET /merchants.
Configure a conta de pagamentos
Na empresa, abra Conta de pagamentos e indique a entidade e a chave da ProxyPay para o ambiente em uso. Use Testar ligação antes da primeira cobrança. Sem credenciais, pode usar o simulador local.
Configure a facturação, se for emitir documentos
Em Empresas, preencha os dados do emitente em Configuração fiscal e registe em Séries fiscais uma série da AGT por tipo de documento que vai emitir (FR, FT, RG, NC) no ano. O mesmo ecrã mostra os tipos que ainda não estão prontos. Só é necessário para factura-recibo, factura, nota de crédito e recibo.
Crie a chave e o webhook
Em Integrações → Criar chave, escolha os scopes de que precisa e guarde a chave no servidor da sua aplicação. Configure também o destino dos webhooks para receber as confirmações.

Acesso

Uma chave por projecto e ambiente

Entre no portal, seleccione o projecto e o ambiente e abra Integrações → Criar chave. Guarde o valor completo no servidor da aplicação consumidora; é mostrado uma única vez. Todas as chamadas abaixo usam Authorization: Bearer SUA_CHAVE e Accept: application/json.

Há duas credenciais diferentes. A chave pao_test_… ou pao_live_… autentica o seu produto nesta API. A chave da ProxyPay pertence à conta da empresa, é configurada em Empresas e nunca é usada como Bearer no Nexo.

O projecto e o ambiente vêm da chave. A API não aceita escolhê-los no corpo da cobrança. Recursos de outro projecto ou ambiente devolvem 404. O portal usa sessão e CSRF; os endpoints /portal/api são administrativos e não aceitam esta autenticação Bearer.

Ligar a chave a uma empresa e desligar a integração

Ao criar a chave em Integrações → Criar chave, pode escolher uma empresa (ou merchant_id em POST /portal/api/api-keys; tem de estar concedida ao projecto). Uma chave ligada só acede a essa empresa, em todas as rotas, e não cria empresas (403 merchant_bound_credential). A ligação não se altera: para mudar, crie outra chave. Uma chave sem empresa acede a todas as empresas do projecto, como antes. Uma empresa com chaves ligadas activas não pode ser apagada.

Operação	O que faz
`GET /connection`	Confirma a chave em uso, sem scope: `credential_id`, `key_prefix`, `environment`, `scopes`, `expires_at`, `status` e `merchant` (`null` se a chave não for ligada; `slug` e `name` só com `merchants:read`). Nunca devolve o segredo. Para a prontidão fiscal use `GET /merchants/{merchant_id}/fiscal/readiness`. Uma chave inválida, revogada ou expirada recebe `401`.
`POST /connection/disconnect`	A própria chave termina a ligação, mesmo expirada, com `Idempotency-Key` obrigatório. Revoga só essa chave, liberta a empresa e devolve um recibo (`receipt_id`, `status: revoked`, `credential_id`, `merchant_id`, `revoked_at`). As concessões do projecto e as outras chaves não mudam.

Se a resposta se perder, repita o pedido com a mesma chave e o mesmo Idempotency-Key: depois da revogação só esta rota ainda aceita a chave e devolve o mesmo recibo (200). Outro Idempotency-Key, ou qualquer outra rota, dá 401; uma chave revogada no portal não tem recibo.

Exclusividade. A chave é um segredo Bearer: o NEXO não sabe que aplicação a usa, e last_used_at, o IP, o Origin ou outros cabeçalhos não provam que só o seu produto a usa. Ligar a uma empresa limita o dano de uma chave copiada, mas não o impede. Garantir uso exclusivo exige identidade do consumidor verificada pelo NEXO (por exemplo, pedidos assinados com uma chave pública registada ao ligar, ou TLS com certificado de cliente).

Permissões da chave e rotação

Scope	Permite
`merchants:read`	Listar empresas autorizadas ao projecto e consultar a conta, o perfil fiscal e as séries de cada uma.
`merchants:write`	Criar empresas e configurar a conta ProxyPay, o perfil fiscal e as séries. Nunca é atribuído por omissão.
`payments:read`	Consultar cobranças e cancelamentos.
`payments:write`	Criar e renovar cobranças, corrigir a factura rejeitada, pedir FR após o pagamento, pedir cancelamentos e simular quando permitido.
`documents:read`	Consultar documentos, PDFs, rascunhos, saldos e motivos de isenção de IVA.
`documents:write`	Criar rascunhos, emitir e associar ou alocar pagamentos.
`catalogue:read` / `catalogue:write`	Consultar / guardar clientes e artigos.
`reports:read`	Criar e descarregar relatórios.

As chaves antigas sem scopes explícitos conservam apenas merchants:read, payments:read, payments:write e documents:read. A escrita fiscal, o catálogo e os relatórios precisam de scopes atribuídos explicitamente. Cada operação na referência indica o scope necessário.

O administrador pode emitir uma chave para um projecto existente pela consola com php artisan payments:project SLUG --environment=sandbox --scope=merchants:read --scope=payments:write --scope=payments:read. Cada execução emite uma chave nova; inclua todos os scopes de que precisa. A validade é opcional, com --expires-at.

A rotação administrativa usa POST /portal/api/api-keys/{id}/rotate, com reason e revoke_previous opcional (falso por omissão). Instale a nova chave no consumidor antes de revogar a anterior. Revogar uma chave impede novas chamadas; faça-o em Integrações → Revogar, por exemplo quando a chave for exposta.

Plataformas

Criar e configurar empresas pela API

Uma plataforma que gere muitas empresas, por exemplo uma por escola, pode fazer pela API o que o portal faz em Empresas. Crie uma chave com o scope merchants:write, que nunca é atribuído por omissão. Esta chave recebe as credenciais ProxyPay e a chave fiscal de cada empresa: use-a só no servidor e separada da chave das cobranças.

Crie a empresa
Envie o seu identificador em slug e o nome. O NIF, a denominação e a morada são opcionais e criam já o perfil fiscal no ambiente da chave. Repetir o pedido com o mesmo slug e nome devolve 200 com a mesma empresa; outro nome devolve 409 merchant_slug_conflict. Um slug de outra empresa devolve 409 merchant_slug_taken.
Criar empresa cURL
```
curl --fail-with-body --silent --show-error "$BASE_URL/merchants" \
  -H "Authorization: Bearer $MERCHANTS_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"slug":"escola-a","name":"Escola A","tax_id":"5000000001","legal_name":"Escola A, Lda","address":"Rua Exemplo 1, Luanda"}'
```

Configure a conta ProxyPay

Indique a entidade, a chave ProxyPay e o motivo. A chave nunca é devolvida: a resposta só indica has_api_key. Teste a ligação com POST /merchants/{id}/account/test.

curl --fail-with-body --silent --show-error -X PUT "$BASE_URL/merchants/$MERCHANT_ID/account" \
  -H "Authorization: Bearer $MERCHANTS_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"provider":"proxypay","entity":"12345","api_key":"CHAVE_PROXYPAY_DA_ESCOLA","reason":"Conta ProxyPay da escola"}'

Configure o perfil fiscal e as séries

Envie os dados do emitente e a chave privada PEM em issuer_private_key, que também nunca é devolvida. Depois registe uma série da AGT por tipo de documento e ano em POST /merchants/{id}/fiscal/series/import. GET /merchants/{id}/fiscal/readiness mostra os tipos de documento já prontos e o que falta.

curl --fail-with-body --silent --show-error -X PUT "$BASE_URL/merchants/$MERCHANT_ID/fiscal" \
  -H "Authorization: Bearer $MERCHANTS_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data "$(jq -n --rawfile key emitente.pem '{tax_id:"5000000001",legal_name:"Escola A, Lda",address:"Rua Exemplo 1, Luanda",enabled:true,issuer_private_key:$key}')"

curl --fail-with-body --silent --show-error "$BASE_URL/merchants/$MERCHANT_ID/fiscal/series/import" \
  -H "Authorization: Bearer $MERCHANTS_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"document_type":"FR","year":2026,"series_code":"FR2026A","first_number":1,"last_number":99999,"next_number":1,"establishment":"SEDE","registered":true,"reason":"Série registada na AGT"}'

Só o projecto dono pode configurar a empresa. Uma empresa que outro projecto partilhou consigo pode ser consultada e usada nas cobranças, mas a configuração devolve 403 merchant_owner_required. Cada alteração fica registada com o projecto e o motivo, tal como no portal.

Primeira integração

Crie a sua primeira cobrança

Este percurso começa com uma cobrança sem facturação. Os comandos usam Bash e cURL com --fail-with-body; execute-os no terminal do seu backend. Os UUIDs, referências e datas apresentados nas respostas são ilustrativos.

Prepare a empresa e a chave
Em Empresas, cadastre a empresa e configure uma conta no mesmo ambiente da chave. Pode usar o simulador local enquanto não tem credenciais ProxyPay. Guarde as variáveis nesta sessão do terminal, substituindo o valor da chave.
Variáveis da integração BASH
```
export BASE_URL='https://nexo.seruvo.vitorperez.dev.br/api/v1'
export API_KEY='SUA_CHAVE_SANDBOX_DO_PROJECTO'
```
Obtenha o identificador da empresa
Copie o id da empresa desejada em data[]. A listagem contém apenas as empresas autorizadas ao projecto; não cria uma conta na ProxyPay.
Listar empresas cURL
```
curl --fail-with-body --silent --show-error "$BASE_URL/merchants" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"
```

Guarde o pedido e envie-o

Crie um ficheiro cobranca.json com o conteúdo abaixo e substitua merchant_id pelo UUID obtido. 125000 representa 1.250,00 Kz. Grave a intenção e a chave de idempotência no seu sistema antes do pedido.

{
  "merchant_id": "019a0000-0000-7000-8000-000000000001",
  "external_id": "pedido-dev-0001",
  "amount_minor": 125000,
  "currency": "AOA",
  "description": "Primeira cobrança de desenvolvimento",
  "metadata": {
    "pedido": "pedido-dev-0001"
  }
}

curl --fail-with-body --silent --show-error "$BASE_URL/payments" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-dev-0001" \
  --data-binary @cobranca.json

Guarde a resposta e acompanhe o estado

A primeira criação devolve 201; repetir uma cobrança já criada com a mesma chave e corpo devolve 200. Guarde data.id, data.reference.entity e data.reference.number. O exemplo abaixo representa o simulador local.

Resposta de criação · 201

{
  "data": {
    "id": "019a0000-0000-7000-8000-000000000002",
    "merchant_id": "019a0000-0000-7000-8000-000000000001",
    "external_id": "pedido-dev-0001",
    "environment": "sandbox",
    "amount_minor": 125000,
    "currency": "AOA",
    "description": "Primeira cobrança de desenvolvimento",
    "status": "pending",
    "method": "reference",
    "provider": "mock",
    "simulated": true,
    "reference": {
      "entity": "SIMULATED",
      "number": "SIM-EXEMPLO"
    },
    "expires_at": "2026-10-17T10:00:00+00:00",
    "paid_at": null,
    "created_at": "2026-10-16T10:00:00+00:00",
    "metadata": { "pedido": "pedido-dev-0001" },
    "invoice_requested": false,
    "fiscal_document": null
  }
}

export PAYMENT_ID='ID_DEVOLVIDO_EM_DATA_ID'

curl --fail-with-body --silent --show-error "$BASE_URL/payments/$PAYMENT_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Com uma conta ProxyPay, provider será proxypay, simulated será falso e a entidade e referência virão da conta e do provedor. Uma referência pendente ainda não é um pagamento confirmado.

Repetir com segurança. Depois de um timeout ou falha do provedor, consulte a cobrança ou repita exactamente a mesma Idempotency-Key e corpo. Nunca gere uma chave nova para resolver um timeout. external_id ajuda a procurar, mas não impede duplicados.

Campos, limites e paginação de cobranças

Campo	Regra
`merchant_id`	UUID de uma empresa autorizada, com conta activa neste ambiente.
`external_id`	Obrigatório, até 150 caracteres. O filtro da listagem faz correspondência exacta.
`amount_minor`	Inteiro JSON entre 1 e 9.999.999.999, em cêntimos. Não envie string nem decimal.
`currency`	`AOA`.
`description`	Obrigatória, até 255 caracteres.
`expires_at`	Opcional. ISO 8601 com segundos e fuso, futura e até 90 dias. Omissão: 24 horas.
`metadata`	Até 20 valores string, cada um com até 500 caracteres. Não use como única prova do pedido.
`document_type`	Opcional. Documento fiscal da cobrança: `FR` (factura-recibo após o pagamento) ou `FT` (factura antes da referência e recibo após o pagamento). Omitido, não há documento. Veja facturação.
`invoice_data`	Obrigatório com `document_type` e só com ele. Cliente e artigos do documento.
`order_data`	Opcional e exclusivo com `invoice_data`. Mesmo formato e mesmas regras, mas regista o cliente e os artigos sem documento. Veja cobrança com artigos.

A Idempotency-Key tem 1–150 letras, números ou ._:-. É exclusiva por projecto e ambiente. Reutilização com outro corpo devolve 409 idempotency_conflict.

GET /payments aceita merchant_id, external_id e page. Tem 50 resultados por página e devolve {data: […], meta: {current_page, last_page, total}}. Use ?external_id=pedido-dev-0001 para recuperar o pedido; confirme empresa, valor e moeda antes de o associar.

Cobrança

Cobrança com cliente e artigos, sem factura

Pode identificar o cliente e os artigos de uma cobrança sem emitir factura-recibo. Envie order_data em POST /payments, com o mesmo formato de invoice_data. Os dois campos não podem ir no mesmo pedido.

{
  "merchant_id": "019a0000-0000-7000-8000-000000000001",
  "external_id": "pedido-dev-0002",
  "amount_minor": 125400,
  "currency": "AOA",
  "description": "Encomenda com artigos, sem factura",
  "order_data": {
    "customer": {
      "name": "Cliente Exemplo, Lda",
      "tax_id": "5000000000",
      "address": "Rua Exemplo 1, Luanda",
      "country": "AO"
    },
    "items": [
      { "code": "SERV-01", "description": "Serviço tributado", "quantity": 1, "unit_amount_minor": 100000, "vat_rate": 14, "operation_type": "SG" },
      { "code": "LIVRO-01", "description": "Livro escolar", "quantity": 1, "unit_amount_minor": 11400, "vat_rate": 0, "operation_type": "SG", "exemption_code": "M13" }
    ],
    "payment_method": "reference"
  }
}

O total dos artigos com IVA tem de ser igual a amount_minor: 1 000,00 Kz + 140,00 Kz de IVA + 114,00 Kz isentos = 1 254,00 Kz (125400). As taxas e os motivos de isenção seguem as regras do IVA. Não é preciso configuração fiscal da empresa.

Os artigos ficam guardados na cobrança, mas não são devolvidos na resposta nem nos webhooks; guarde-os também no seu sistema. Para ter documento fiscal, envie document_type e invoice_data em vez de order_data. Depois do pagamento ainda pode pedir uma factura-recibo com os mesmos artigos.

Dados enviados à ProxyPay. Para identificar a cobrança no back-office do provedor, a referência é registada com o ID da cobrança, external_id, a descrição, o nome e o NIF do cliente (de invoice_data ou order_data), o nome da empresa e do projecto. Estes dados aparecem nas notificações de pagamento da ProxyPay. Não coloque nesses campos informação que não deva ser partilhada com o provedor.

Sem credenciais do provedor

Teste o ciclo com dados persistentes

O simulador permite criar e confirmar cobranças na base da sua instalação. Entre no portal normal, cadastre uma empresa de desenvolvimento separada e escolha Simulador local na conta Sandbox. A demonstração em /app?demo=1 usa apenas dados temporários do navegador.

Condições do simulador: aplicação em local ou testing, PAYMENTS_ALLOW_MOCK=true, chave Sandbox e conta da empresa com provedor mock. O endpoint abaixo não confirma referências ProxyPay e devolve 404 quando estas condições não se verificam.

Depois de criar a cobrança do passo anterior, execute:

curl --fail-with-body --silent --show-error \
  -X POST "$BASE_URL/payments/$PAYMENT_ID/simulate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

O resultado esperado é data.status = paid, data.simulated = true e data.paid_at preenchido. Consulte novamente a cobrança para confirmar a persistência. O simulador não movimenta dinheiro e não valida a ligação bancária.

Mantenha php artisan schedule:work activo noutro terminal para processar notificações, documentos e cancelamentos. Apenas iniciar queue:work não executa estas tarefas. Para receber webhooks no seu consumidor, use um endpoint acessível à instalação e a configuração indicada em Webhooks.

Quando receber as credenciais ProxyPay, configure outra empresa de teste ou uma conta ainda sem histórico. Depois da primeira cobrança, não é permitido trocar o provedor nem a entidade da conta. A chave pode ser rodada. O botão Testar ligação autentica na ProxyPay, mas não valida a entidade nem um pagamento completo.

Testar com o Sandbox oficial da ProxyPay

Com a conta ProxyPay Sandbox configurada, crie uma cobrança e abra Cobranças → Detalhes → Testar pagamento na ProxyPay. Indique o motivo e envie o pagamento de teste. Esta acção exige a permissão de criar cobranças e está indisponível em Produção.

O estado Simulação enviada à ProxyPay confirma a aceitação do pedido de teste. A cobrança só passa a paga quando chegar a confirmação do provedor. Configure o callback HTTPS público indicado na conta ou active a reconciliação automática com o scheduler em execução, quando esta aplicação for responsável pela fila.

É permitido um envio por cobrança. Um resultado incerto fica visível e não é repetido automaticamente. Consulte Empresas → Operação de pagamentos para verificar a reconciliação e os recebimentos em revisão.

Ciclo de cobrança

Cancelar e acompanhar o resultado

O pedido exige payments:write, uma Idempotency-Key e reason com 5–500 caracteres. Use uma cobrança pendente ou expirada que ainda não foi paga. Uma cobrança com factura ainda sem referência também pode ser cancelada e fica cancelled de imediato; a factura validada é anulada com uma nota de crédito. A resposta 202 confirma apenas que o pedido de cancelamento foi registado.

Se seguiu o passo de simulação, a cobrança anterior já está paga. Crie outra cobrança com novo external_id e nova Idempotency-Key, e actualize PAYMENT_ID antes de testar o cancelamento.

curl --fail-with-body --silent --show-error \
  "$BASE_URL/payments/$PAYMENT_ID/cancellation" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancelamento-pedido-dev-0001" \
  --data '{"reason":"Pedido cancelado pelo cliente."}'

curl --fail-with-body --silent --show-error \
  "$BASE_URL/payments/$PAYMENT_ID/cancellation" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

A consulta exige payments:read e devolve o pedido dentro de data. Sem pedido registado, devolve 404. Os estados incluem requested, sending, cancelled, paid, unknown e failed. O pagamento e o pedido de cancelamento têm estados independentes.

Resultado incerto e nova tentativa

Se receber unknown, investigue o resultado no provedor antes de voltar a pedir o cancelamento. Um timeout não prova que a referência foi eliminada. Uma confirmação bancária tardia conserva o pagamento como paid.

curl --fail-with-body --silent --show-error \
  "$BASE_URL/payments/$PAYMENT_ID/cancellation/retry" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"reason":"Resultado investigado; autorizada nova tentativa."}'

Retry aceita apenas pedidos unknown ou failed, com pagamento ainda não pago, até três novas tentativas. O motivo é obrigatório; esta operação não usa uma nova chave de idempotência. Tem limite adicional de 10 pedidos por minuto. Cancelar uma referência não é um reembolso; reembolsos automáticos não estão disponíveis nesta versão.

Ciclo de cobrança

Renovar uma cobrança expirada

Quando a validade termina sem pagamento, a cobrança passa a expired. Para voltar a aceitar pagamentos com a mesma referência Multicaixa, envie a nova validade. O pedido exige payments:write e expires_at em ISO 8601 com segundos e fuso, futura e até 90 dias.

curl --fail-with-body --silent --show-error   "$BASE_URL/payments/$PAYMENT_ID/renewal"   -H "Authorization: Bearer $API_KEY"   -H "Accept: application/json"   -H "Content-Type: application/json"   --data '{"expires_at":"2026-10-30T23:59:00+01:00"}'

A resposta 200 devolve a cobrança com status pending e o novo expires_at. A referência é registada de novo no provedor antes da resposta; se o provedor falhar, recebe 502 e a cobrança continua expired. Repetir o pedido com a mesma validade devolve a cobrança sem novo envio. A aplicação recebe o evento payment.renewed, com a validade anterior em data.previous_expires_at.

Regras da renovação

A renovação muda apenas a validade. O valor, o cliente, os artigos e a factura-recibo pedida mantêm-se; para os alterar, crie uma cobrança nova. Uma cobrança com factura que expirou antes de ter referência recebe só a nova validade e volta a awaiting_invoice; a referência é gerada após a validação da AGT. Só uma cobrança expired e não paga pode ser renovada: paid, cancelled, uma cobrança ainda dentro da validade ou com pedido de cancelamento devolvem 409 payment_not_renewable. Nada é renovado automaticamente. O pedido tem limite adicional de 10 pedidos por minuto e fica registado com a credencial que o fez.

Facturação

Da cobrança à factura. Ou da factura à cobrança.

Escolha o documento ao criar a cobrança, em document_type, e envie o cliente e os artigos em invoice_data. Sem document_type não há documento: para identificar o cliente e os artigos sem documento, use a cobrança com artigos.

`document_type`	O que o Nexo faz
omitido	Gera a referência. Nenhum documento fiscal. Depois do pagamento, pode ainda pedir uma FR.
`FR`	Gera a referência. Depois do pagamento emite a factura-recibo e envia-a à AGT.
`FT`	Emite a factura e envia-a à AGT. Só depois de a AGT a validar gera a referência. Depois do pagamento emite o recibo (RG) e envia-o à AGT. Veja cobrança com factura.

A factura é sempre anterior ao pagamento: depois de pago só é possível pedir uma FR. Também pode emitir uma FT independente, sem cobrança, e associar-lhe pagamentos parciais, cada um com o seu RG.

Configure o perfil fiscal da empresa no mesmo ambiente da chave. Os UUIDs, clientes, datas e classificações abaixo são exemplos: substitua-os pelos dados da operação. O servidor obtém a identidade do emitente da configuração autorizada.

FR: emitir depois da confirmação do pagamento

Envie POST /payments com o scope payments:write, Idempotency-Key: pedido-fr-001, "document_type": "FR" e invoice_data. invoice_data sem document_type devolve 422.

{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "external_id": "pedido-fr-001",
  "amount_minor": 114000,
  "currency": "AOA",
  "description": "Serviço de demonstração",
  "document_type": "FR",
  "invoice_data": {
    "customer": {
      "tax_id": "999999999",
      "name": "Consumidor final",
      "address": "Luanda",
      "country": "AO"
    },
    "items": [{
      "code": "SERV-01",
      "description": "Serviço de demonstração",
      "quantity": 1,
      "unit_amount_minor": 100000,
      "vat_rate": 14,
      "tax_code": "NOR",
      "operation_type": "SG"
    }],
    "payment_method": "reference"
  }
}

O exemplo representa 1 000,00 Kz sem IVA + 140,00 Kz de IVA = 1 140,00 Kz (114000 cêntimos). Neste fluxo, quantity e vat_rate são inteiros JSON. As taxas, o código do imposto e as isenções seguem as regras do IVA. São aceites até 100 linhas; payment_method é reference.

A emissão começa depois de paid. Consulte GET /documents?payment_id={payment_id} ou acompanhe os eventos fiscais. Uma falha fiscal não desfaz a confirmação do pagamento.

FT na cobrança: factura antes da referência, recibo após o pagamento

Envie POST /payments com "document_type": "FT", o scope payments:write e Idempotency-Key: pedido-ft-001. O total dos artigos com IVA tem de coincidir com amount_minor.

{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "external_id": "pedido-ft-001",
  "amount_minor": 114000,
  "currency": "AOA",
  "description": "Serviço de demonstração",
  "expires_at": "2026-11-30T23:59:59+01:00",
  "document_type": "FT",
  "invoice_data": {
    "customer": {
      "tax_id": "5000000000",
      "name": "Cliente Lda",
      "address": "Rua 1, Luanda",
      "country": "AO"
    },
    "items": [{
      "code": "SERV-01",
      "description": "Serviço de demonstração",
      "quantity": 1,
      "unit_amount_minor": 100000,
      "vat_rate": 14,
      "operation_type": "SG"
    }],
    "payment_method": "reference"
  }
}

A resposta 201 traz status awaiting_invoice, reference null e a factura em fiscal_document (type FT). O Nexo envia-a à AGT.
Quando a AGT a valida, o Nexo gera a referência com a validade de expires_at e envia o evento payment.reference_ready. A cobrança passa a pending e a referência está em data.payment.reference. Mostre-a ao cliente só a partir deste momento.
Depois do pagamento (payment.paid), o Nexo emite o recibo e envia-o à AGT. O recibo aparece em receipt da cobrança e nos eventos invoice.*.

Factura rejeitada. A cobrança passa a invoice_rejected, sem referência, e recebe payment.invoice_rejected com o código da AGT em data.error_code. Corrija com PUT /payments/{payment_id}/invoice, enviando invoice_data corrigido com o mesmo total. O Nexo envia uma factura de correcção à AGT e a cobrança volta a awaiting_invoice. No portal, a mesma correcção faz-se no detalhe da cobrança, em Corrigir factura.

Validade. Se expires_at passar antes da validação, a cobrança passa a expired e recebe payment.expired. Envie uma nova data com POST /payments/{payment_id}/renewal: a cobrança volta a awaiting_invoice e a referência é gerada após a validação. Uma referência já gerada é renovada como nas outras cobranças. A factura mantém-se.

Cancelamento. POST /payments/{payment_id}/cancellation anula a referência, quando existe. Sem referência, a cobrança fica cancelled de imediato. Se a factura estiver (ou vier a ficar) validada, o Nexo emite uma nota de crédito total com o motivo do cancelamento (até 60 caracteres) e envia payment.invoice_credited com data.credit_note_id.

Um pagamento com valor diferente do da cobrança não é aceite nem gera recibo; fica para revisão.

FR depois do pagamento de uma cobrança sem documento

Para uma cobrança paid criada sem document_type, envie PUT /payments/{payment_id}/invoice com invoice_data. Se a cobrança tiver order_data, pode enviar o corpo vazio {}: os mesmos artigos são usados. A cobrança passa a document_type FR e a factura-recibo segue para a AGT. Repetir o pedido devolve a cobrança sem novo documento. Noutros estados devolve 409 invoice_not_attachable.

FR rejeitada. Se a AGT rejeitar a factura-recibo de uma cobrança paid, envie o mesmo PUT /payments/{payment_id}/invoice com invoice_data corrigido e o mesmo total. O Nexo emite uma nova FR ligada à rejeitada (corrects_document_id) e a cobrança mantém-se paga; fiscal_document passa a mostrar a FR mais recente. No portal, use Corrigir factura no detalhe da cobrança.

Pagamento recebido fora da ProxyPay (numerário, transferência, TPA)

Se o cliente pagou por outro meio, registe o pagamento com POST /payments, o scope payments:write e method igual a cash (numerário), bank_transfer (transferência), card (TPA) ou other. Indique quando recebeu em paid_at, no passado e até 365 dias, e, se quiser, o talão ou a transferência em method_reference. A empresa não precisa de conta ProxyPay.

{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "external_id": "venda-balcao-001",
  "amount_minor": 114000,
  "currency": "AOA",
  "description": "Venda ao balcão",
  "method": "cash",
  "paid_at": "2026-10-27T10:30:00+01:00",
  "method_reference": "Talão 0042",
  "document_type": "FR",
  "invoice_data": {
    "customer": {
      "tax_id": "999999999",
      "name": "Consumidor final",
      "address": "Desconhecido",
      "country": "AO"
    },
    "items": [{
      "code": "SERV-001",
      "description": "Serviço de demonstração",
      "quantity": 1,
      "unit_amount_minor": 100000,
      "vat_rate": 14,
      "operation_type": "SG"
    }],
    "payment_method": "cash"
  }
}

O pagamento nasce paid, sem referência nem validade (reference e provider a null), e emite payment.paid. Com "document_type": "FR" a factura-recibo segue logo para a AGT; sem document_type pode pedi-la depois com PUT /payments/{payment_id}/invoice. FT e expires_at não são aceites. O payment_method de invoice_data fica sempre igual a method.

Factura paga depois. Emita a FT com um rascunho. Quando receber, registe o pagamento sem invoice_data e liquide a factura com POST /documents/{document_id}/allocations: o Nexo emite o recibo (RG). Pode liquidar em várias parcelas, até ao saldo de GET /documents/{document_id}/balance.

Cada pagamento registado conta para a facturação do Nexo como um pagamento recebido pela ProxyPay. No portal, escolha Pagamento já recebido ou Só a factura em Nova cobrança, e registe o pagamento de uma FT na página da factura.

IVA: taxas, código do imposto e isenções

Cada linha de invoice_data, order_data, FT ou NC usa uma das taxas de IVA de Angola. O código do imposto é deduzido da taxa; se o enviar, tem de coincidir.

`vat_rate`	`tax_code`	`exemption_code`
14	`NOR`	Não enviar.
7, 5 ou 1	`RED`	Não enviar.
0	`ISE`	Obrigatório: um código activo da lista oficial da AGT.

Consulte os motivos aceites com GET /fiscal/exemption-reasons e o scope documents:read. Cada motivo traz code (por exemplo M13), document_mention, legal_basis, description e exemption_type. A menção legal é impressa no documento e incluída no SAF-T; não precisa de a enviar.

curl --fail-with-body --silent --show-error "$BASE_URL/fiscal/exemption-reasons"   -H "Authorization: Bearer $API_KEY"   -H "Accept: application/json"

Uma taxa fora da lista, um tax_code que não corresponde à taxa, uma linha a 0% sem motivo, um motivo desconhecido ou inactivo, ou um motivo numa linha tributada devolvem 422 validation_failed com o erro no campo da linha, por exemplo items.0.exemption_code.

Consulta e validação de NIF

Com a consulta de NIF ligada pelo super admin da plataforma, GET /fiscal/taxpayer?tax_id=… (scope documents:read) devolve o nome e o estado do contribuinte na AGT. Responde 404 quando o NIF não existe e 503 quando a consulta está desligada ou a AGT não responde.

curl --fail-with-body --silent --show-error "$BASE_URL/fiscal/taxpayer?tax_id=5417000123"   -H "Authorization: Bearer $API_KEY"   -H "Accept: application/json"

Se a plataforma também activou Rejeitar NIF inválido, uma cobrança com documento, um pedido de factura-recibo ou um rascunho de FT cujo cliente tenha um NIF que a AGT não conhece devolve 422 validation_failed em customer.tax_id (invoice_data.customer.tax_id numa cobrança) e nada é criado. Se a AGT não responder, a emissão segue sem validar. O consumidor final 999999999 não é consultado.

Código CNBS em cada linha

A AGT anunciou que, a partir de Janeiro de 2027, cada linha da factura electrónica leva o código CNBS (Classificação Nacional de Bens e Serviços, do INE). Envie-o em cnbs_code, com 8 algarismos sem pontos nem espaços, nas linhas de invoice_data, FT e catálogo. O Nexo envia-o à AGT como productCode; uma linha sem CNBS continua a usar o seu code.

Pesquise os códigos aceites com GET /fiscal/cnbs-codes?search=… e o scope documents:read. A pesquisa procura no início do código (8510 ou 85.10) e nas palavras da designação; a resposta traz code, description e required_from, a data a partir da qual o código é obrigatório.

curl --fail-with-body --silent --show-error "$BASE_URL/fiscal/cnbs-codes?search=ensino%20prim%C3%A1rio"   -H "Authorization: Bearer $API_KEY"   -H "Accept: application/json"

Situação	Resultado
Antes de `required_from`, sem `cnbs_code`	Aceite; a linha segue com o seu `code`.
Desde `required_from`, FT ou FR sem `cnbs_code` numa linha	`422 validation_failed` em `items.N.cnbs_code`. A cobrança ou o documento não são criados.
Código que não tem 8 algarismos, desconhecido ou inactivo	`422 validation_failed` em `items.N.cnbs_code`, em qualquer data.

A nota de crédito repete as linhas da factura original, incluindo o CNBS. Uma cobrança sem documento fiscal (order_data) não exige CNBS. A lista começa com a CNBS-Rev.1 do INE (2014) e é substituída pelo ficheiro oficial quando a AGT o publicar; um código retirado fica inactivo e deixa de ser aceite em documentos novos.

FT: criar, rever e emitir um rascunho

Crie o rascunho com POST /fiscal/drafts, scope documents:write e Idempotency-Key: factura-ft-001. Guarde data.id e data.revision.
Se precisar de alterar o conteúdo, envie PUT /fiscal/drafts/{draft_id} com os dados completos e a revisão actual. A resposta devolve a revisão seguinte.
Emita com POST /fiscal/drafts/{draft_id}/issue e a revisão devolvida. A resposta 202 contém data.id do documento, cujo processamento continua em segundo plano.

{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "type": "FT",
  "due_date": "2026-10-31",
  "customer": {
    "tax_id": "999999999",
    "name": "Consumidor final",
    "address": "Luanda",
    "country": "AO"
  },
  "items": [{
    "code": "SERV-01",
    "description": "Serviço de demonstração",
    "quantity": "1",
    "unit_amount_minor": 100000,
    "vat_rate": "14",
    "tax_code": "NOR",
    "operation_type": "SG",
    "discount_bps": 0,
    "unit_of_measure": "UN"
  }]
}

O rascunho começa em revision: 1. Este exemplo altera o vencimento; PUT exige novamente cliente e linhas, não é uma alteração parcial. A empresa e o tipo mantêm-se.

{
  "revision": 1,
  "due_date": "2026-11-15",
  "customer": {
    "tax_id": "999999999",
    "name": "Consumidor final",
    "address": "Luanda",
    "country": "AO"
  },
  "items": [{
    "code": "SERV-01",
    "description": "Serviço de demonstração",
    "quantity": "1",
    "unit_amount_minor": 100000,
    "vat_rate": "14",
    "tax_code": "NOR",
    "operation_type": "SG",
    "discount_bps": 0,
    "unit_of_measure": "UN"
  }]
}

{
  "revision": 2
}

Sem a revisão intermédia, emita com {"revision":1}. Uma revisão desactualizada devolve 422; recupere a versão em GET /fiscal/drafts antes de editar. Um rascunho emitido não pode ser alterado. Repetir a emissão devolve o documento já associado.

Campo das linhas FT/NC	Formato
`quantity`	Inteiro ou string decimal positiva, até 4 casas: `"1.2345"`. Não envie um número JSON fraccionário.
`unit_amount_minor`	Inteiro JSON em cêntimos, antes de IVA.
`vat_rate`	14, 7, 5, 1 ou 0, como inteiro ou string decimal: `"14.00"`. Veja as regras do IVA.
`discount_bps`	Inteiro opcional de 0 a 10000. `1250` representa 12,5% de desconto na linha.
`operation_type`	Classificação explícita da operação.
`tax_code`, `exemption_code`	`tax_code` é opcional e deduzido da taxa. IVA 0% exige `exemption_code`; a aplicação não escolhe a isenção.
`cnbs_code`	Código CNBS de 8 algarismos. Obrigatório nas FT a partir de Janeiro de 2027; veja Código CNBS.

O cálculo conserva cêntimos inteiros: FT trunca o valor líquido da linha, NC arredonda-o para cima e o imposto arredonda para cima. O âmbito implementado é IVA doméstico em AOA, com até 100 linhas; retenções, descontos globais e moeda estrangeira não são suportados.

Nenhuma linha a zero. A AGT recusa linhas sem valor, mesmo quando o total do documento é positivo. Cada linha tem de valer pelo menos 0,01 Kz depois do desconto: um preço 0 ou discount_bps de 10000 devolve 422 em items.N, com a mensagem «A AGT não aceita linhas com valor zero…». Retire a linha em vez de a enviar a zero. A regra vale para FT, FR, NC e cobranças com factura.

Ligar uma cobrança à FT e acompanhar o saldo

Depois de a FT chegar a valid (ou simulated no teste local), crie uma cobrança sem invoice_data, no mesmo projecto, empresa e ambiente. Associe o pagamento à factura com o scope documents:write e Idempotency-Key: ft-001-parcela-01.

{
  "payment_id": "22222222-2222-4222-8222-222222222222",
  "amount_minor": 57000
}

O vínculo reserva 57000 cêntimos. Quando o pagamento for confirmado, o worker regista a alocação uma única vez e prepara o RG. Isto também funciona se a confirmação chegar antes da associação.

Consulte GET /documents/{document_id}/payment-links com documents:read: os vínculos estão em data.data e a paginação em data.current_page, data.last_page e data.total. Os estados são pending, complete e needs_review.

Para um pagamento já confirmado, incluindo um pagamento registado em numerário, transferência ou TPA, pode optar por POST /documents/{document_id}/allocations, com o mesmo formato de corpo e uma chave própria, por exemplo Idempotency-Key: ft-001-liquidacao-01. A resposta 201 inclui data.receipt_document_id para acompanhar o recibo. Use apenas um destes caminhos para cada liquidação.

{
  "data": {
    "gross_minor": 114000,
    "credit_reserved_minor": 0,
    "allocated_minor": 0,
    "available_minor": 114000,
    "overpaid_minor": 0
  },
  "allocations": []
}

O saldo mostra o valor original, créditos reservados por NC, alocações, montante disponível e excesso pago. available_minor não desconta vínculos ainda pendentes; consulte-os também antes de propor uma nova cobrança. O servidor verifica os limites na associação.

Se um vínculo ficar em needs_review, resolva a causa e envie POST /documents/{document_id}/payment-links/{link_id}/retry com {"reason":"Saldo e associação revistos pelo operador"}. Exige documents:write, devolve 202 e mantém a confirmação bancária.

Notas de crédito e correcções de documentos rejeitados

Uma NC usa o mesmo ciclo de rascunho e emissão. Envie POST /fiscal/drafts com documents:write e uma nova chave, por exemplo Idempotency-Key: nota-credito-001. A factura original deve estar validada ou simulada no mesmo âmbito.

{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "type": "NC",
  "original_document_id": "33333333-3333-4333-8333-333333333333",
  "reason": "Rectificação parcial do serviço",
  "customer": {
    "tax_id": "999999999",
    "name": "Consumidor final",
    "address": "Luanda",
    "country": "AO"
  },
  "items": [{
    "original_line": 1,
    "code": "SERV-01",
    "description": "Serviço de demonstração",
    "quantity": "0.5",
    "unit_amount_minor": 100000,
    "vat_rate": "14",
    "tax_code": "NOR",
    "operation_type": "SG",
    "discount_bps": 0,
    "unit_of_measure": "UN"
  }]
}

Conserve os dados do cliente, preço, imposto, classificação e desconto da linha original. original_line começa em 1; o motivo tem entre 5 e 60 caracteres. As NC pendentes reservam valor, e a soma dos créditos não pode ultrapassar a factura. Uma NC sobre uma factura liquidada pode produzir overpaid_minor; não executa uma devolução bancária.

Rectificar o documento inteiro. Para anular uma FT ou FR validada por completo, envie POST /documents/{document_id}/rectification com documents:write e {"reason": "Preço errado"} (5 a 60 caracteres). O Nexo emite a NC de todas as linhas e responde 201 com ela; repetir devolve a mesma NC com 200. Uma FT já liquidada por recibo (RG) ou com cobrança associada pendente devolve 422 em document. GET /documents/{document_id} traz rectification.allowed, rectification.blocked_reason e a rectification.credit_note que já o rectificou. No portal, é o botão Rectificar da página do documento.

Para corrigir um documento rejected que já possui número, crie outro rascunho do mesmo tipo com os dados completos e corrects_document_id igual ao UUID rejeitado. Use uma nova Idempotency-Key e emita o rascunho. O original permanece rejeitado; o substituto recebe identidade própria. Numa NC, conserve também original_document_id. Uma FR independente só é aceite neste caso de correcção, conservando o total do pagamento original.

Sandbox e simulação local não conferem validade fiscal. A emissão real depende das credenciais, séries e homologação do próprio produto. FT, NC, RG e correcções têm habilitação live separada, desactivada por defeito.

Consultar documentos e descarregar o PDF

Estas rotas exigem o scope documents:read. A autorização continua a aplicar-se ao PDF: o endereço devolvido não é um link público.

Pedido	Resultado
`GET /documents?payment_id={payment_id}`	Documentos directamente associados à cobrança. Para FT independente, guarde o ID devolvido na emissão.
`GET /documents?merchant_id={merchant_id}&status=blocked&page=1`	Filtrar por empresa e estado fiscal.
`GET /documents/{document_id}`	Estado, tipo, número, dados emitidos em `snapshot`, datas, `last_error_code` e `last_error_message` (a explicação dada pela AGT, quando existe).
`GET /documents/{document_id}/pdf`	Ficheiro PDF quando o estado é `valid` ou `simulated`; antes disso devolve `409 document_not_ready`.
`GET /documents/{document_id}/balance`	Saldo e alocações da factura, incluindo os IDs dos recibos.
`GET /documents` e `GET /documents/{document_id}`	Em `settlements`, os recibos que liquidaram a FT (ou a FT que o RG liquida), com o valor de cada um; em `payment`, a cobrança que pagou. `GET /payments/{payment_id}` traz `documents` (factura, recibos e notas de crédito) e `items` (os artigos da factura).

A listagem de documentos devolve até 50 entradas em data, com meta.current_page, meta.last_page e meta.total. Recursos de outro projecto ou ambiente devolvem 404.

Exemplo de resposta e interpretação da validade

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "environment": "sandbox",
    "type": "FT",
    "number": null,
    "status": "simulated",
    "simulated": true,
    "fiscal_valid": false,
    "last_error_code": null,
    "last_error_message": null,
    "pdf_url": "/api/v1/documents/33333333-3333-4333-8333-333333333333/pdf"
  }
}

Um documento local simulado não recebe número fiscal e o PDF indica SEM VALIDADE FISCAL. Mesmo uma resposta valid da AGT em sandbox mantém fiscal_valid: false; este campo só é verdadeiro para um documento validado em live, sem simulação.

Receber 202 na emissão ou chegar a submitted não significa validação. Acompanhe o estado por consulta ou webhook; em unknown, use o processo de reconciliação e preserve o documento existente.

Reutilizar clientes e artigos

O catálogo pertence ao projecto, empresa e ambiente da chave. GET /merchants/{merchant_id}/catalogue/customers e /items exigem catalogue:read. Para guardar, use PUT na mesma rota com catalogue:write.

Guardar um cliente, um artigo e usá-los num rascunho

{
  "code": "CLI-001",
  "active": true,
  "data": {
    "tax_id": "999999999",
    "name": "Consumidor final",
    "address": "Luanda",
    "country": "AO"
  }
}

{
  "code": "SERV-01",
  "active": true,
  "data": {
    "description": "Serviço de demonstração",
    "quantity": "1",
    "unit_amount_minor": 100000,
    "vat_rate": "14",
    "tax_code": "NOR",
    "operation_type": "SG",
    "discount_bps": 0,
    "unit_of_measure": "UN"
  }
}

O code identifica o registo no catálogo. Repetir PUT com o mesmo código actualiza-o; não exige Idempotency-Key. Guarde o UUID devolvido em data.id, tanto para o cliente como para o artigo.

{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "type": "FT",
  "customer_id": "44444444-4444-4444-8444-444444444444",
  "items": [{
    "catalogue_item_id": "55555555-5555-4555-8555-555555555555",
    "quantity": "2",
    "unit_amount_minor": 100000
  }]
}

Este pedido exige documents:write e uma nova Idempotency-Key. Substitua customer_id e catalogue_item_id pelos IDs guardados. Quantidade e preço explícitos substituem os valores do artigo.

As listagens têm 50 entradas por página, em data, e campos current_page, last_page e total no topo da resposta. Envie active: false para desactivar um registo. Apenas registos activos podem ser referenciados num rascunho; alterações posteriores ao catálogo não reescrevem os dados já copiados.

Exportar um relatório do projecto

Use o scope reports:read para criar e consultar relatórios JSON. A empresa precisa de um perfil fiscal no ambiente. Envie POST /fiscal/exports com Idempotency-Key: relatorio-2026-10-001.

{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "format": "json_report",
  "start_date": "2026-10-01",
  "end_date": "2026-10-31"
}

A resposta 202 devolve data.id e o estado inicial pending. O intervalo inclui as datas inicial e final em Angola, deve estar no mesmo ano e admite até 5 000 documentos e 5 000 cobranças por pedido.

Pedido	Uso
`GET /fiscal/exports`	Listar exportações; paginação em `current_page`, `last_page` e `total`, no topo.
`GET /fiscal/exports/{export_id}`	Acompanhar `data.status`: `pending`, `processing`, `complete`, `failed` ou `expired`. Em falha, consultar `data.error_code`.
`GET /fiscal/exports/{export_id}/download`	Descarregar quando `complete`. Inclui `X-Content-SHA256`; indisponível antes da conclusão (`409`) ou após expiração (`410`).

Conteúdo, processamento e limites do SAF-T

O relatório JSON inclui cobranças criadas no período, documentos emitidos (ou criados, quando ainda não têm data de emissão), estados e totais. É uma cópia dos dados no momento do pedido. Para incluir operações posteriores, crie outra exportação com nova chave. O ficheiro fica disponível durante sete dias após a conclusão.

O scheduler processa as exportações. Num ambiente local, o operador pode executar php artisan payments:fiscal:exports --limit=20 --prune. Repetir o pedido com a mesma chave e corpo devolve a exportação existente.

format: saft é exclusivo do portal, com sessão de um utilizador autorizado a administrar o emitente. Uma chave de API não permite exportar SAF-T. O relatório JSON não é um ficheiro SAF-T.

O SAF-T abrange a empresa inteira, incluindo os seus outros projectos. Requer os dados explícitos de cabeçalho: company_id, city, tax_entity, product_company_tax_id, software_validation_number, product_id e product_version. A pré-visualização sandbox não tem validade fiscal; live permanece condicionado à habilitação, assinaturas próprias e confirmação de compatibilidade com a AGT.

Notificações

Receber e confirmar eventos

O Nexo envia um pedido POST ao seu servidor quando um pagamento ou documento muda de estado. Configure um destino para cada projecto e ambiente; o segredo do webhook é independente da chave Bearer da API.

Configurar o destino

No portal, seleccione o projecto e o ambiente e configure uma URL HTTPS pública. A resposta inicial devolve signing_secret uma única vez e data.signing_key_id, que identifica a versão. Guarde ambos no servidor consumidor. Consultas posteriores devolvem a configuração, sem o segredo.

As rotas /portal/api/… abaixo são administrativas: exigem sessão do portal, pertença ao projecto e CSRF nas alterações. A gestão do destino exige credentials.manage; em organizações, também email verificado e confirmação recente de identidade. Chaves Bearer dos consumidores autenticam os pedidos a /api/v1 e não substituem a sessão nestas rotas.

PUT /portal/api/webhook-endpoint
Content-Type: application/json

{
  "url": "https://integracao.example.com/webhooks/pagamentos-ao",
  "reason": "Activar notificações para a integração de cobranças."
}

Operação no portal	Comportamento
`GET /portal/api/webhook-endpoint`	Consulta a URL, o ambiente e a versão do segredo.
`PUT /portal/api/webhook-endpoint`	Exige `url` e `reason` com 5–500 caracteres. Enviar `url: null` desactiva novas entregas; as já agendadas continuam.
`POST /portal/api/webhook-endpoint/rotate`	Exige `reason`. Devolve o novo segredo uma única vez e a respectiva versão.

O ambiente vem do contexto seleccionado no portal. HTTP para localhost ou loopback só é aceite no desenvolvimento/testes com PAYMENTS_ALLOW_LOCAL_WEBHOOKS=true. O endereço de callback da ProxyPay é outra integração: os eventos desta secção são enviados pelo Nexo ao seu sistema.

Eventos e formato

O envelope conserva id, type, created_at e data. O id identifica o evento; o data.id identifica o pagamento ou documento. Os exemplos seguintes usam dados fictícios em sandbox.

Evento	Significado e conteúdo de `data`
`payment.paid`	Recebimento confirmado. `data` contém o recurso de pagamento, incluindo empresa, ambiente, montante e referência.
`payment.expired`	Validade da referência terminada. Uma confirmação bancária tardia ainda pode produzir `payment.paid`.
`payment.renewed`	A referência expirada foi renovada com nova validade e voltou a `pending`. `data.payment` contém o pagamento e `data.previous_expires_at` a validade anterior.
`payment.reference_ready`	Cobrança com factura: a AGT validou a factura e a referência foi gerada. `data.payment.reference` contém a entidade e a referência a mostrar ao cliente.
`payment.invoice_rejected`	A AGT rejeitou a factura da cobrança; não há referência. `data.error_code` traz o código da AGT. Corrija com `PUT /payments/{payment}/invoice`.
`payment.invoice_credited`	A cobrança com factura validada foi cancelada e o Nexo emitiu a nota de crédito total. `data.credit_note_id` identifica o documento.
`payment.cancel_requested`, `payment.cancelled`, `payment.cancel_uncertain`	Acompanham o cancelamento. `data.payment` contém o pagamento; a revisão permite identificar a evolução da operação.
`invoice.valid`	Documento validado no ambiente indicado. Só `data.fiscal_valid: true` indica validação fiscal real em live.
`invoice.rejected`	Documento rejeitado. Consulte `data.last_error_code` e o documento; o pagamento mantém o seu estado.
`invoice.simulated`	Documento de simulação, sem validade fiscal. `data.simulated` é verdadeiro e `data.fiscal_valid` é falso.

{
  "id": "7c23abe1-0935-4715-85bd-b8ea818508ce",
  "type": "payment.paid",
  "created_at": "2026-10-16T10:00:00+00:00",
  "data": {
    "id": "c1350b62-0692-486c-a36c-89bfa878c362",
    "merchant_id": "be0ef2ee-e0f0-479f-848c-9a28a35090a7",
    "external_id": "pedido-2026-0001",
    "environment": "sandbox",
    "amount_minor": 114000,
    "currency": "AOA",
    "description": "Prestação de serviço",
    "status": "paid",
    "method": "reference",
    "provider": "proxypay",
    "simulated": false,
    "reference": {"entity": "12345", "number": "123456789"},
    "expires_at": "2026-10-17T10:00:00+00:00",
    "paid_at": "2026-10-16T10:00:00+00:00",
    "created_at": "2026-10-16T09:00:00+00:00",
    "metadata": {},
    "invoice_requested": true,
    "fiscal_document": null
  }
}

A confirmação de pagamento pode chegar antes da preparação do documento, por isso fiscal_document pode ser nulo. Nos eventos invoice.*, data é o recurso fiscal: inclui status, number, snapshot, fiscal_valid e last_error_code. Documentos independentes podem ter payment_id: null.

Ver exemplo de invoice.simulated

{
  "id": "4362a53b-004d-466b-bf79-f99e96dc2148",
  "type": "invoice.simulated",
  "created_at": "2026-10-16T10:01:00+00:00",
  "data": {
    "id": "a0717bb2-b327-4c76-b45f-908aff0557d2",
    "payment_id": "c1350b62-0692-486c-a36c-89bfa878c362",
    "merchant_id": "be0ef2ee-e0f0-479f-848c-9a28a35090a7",
    "environment": "sandbox",
    "type": "FR",
    "number": null,
    "status": "simulated",
    "simulated": true,
    "fiscal_valid": false,
    "snapshot": {
      "customer": {
        "tax_id": "999999999",
        "name": "Cliente de exemplo",
        "address": "Luanda",
        "country": "AO"
      },
      "items": [{
        "code": "SERV-01",
        "description": "Prestação de serviço",
        "quantity": 1,
        "unit_amount_minor": 100000,
        "vat_rate": 14,
        "tax_code": "NOR",
        "operation_type": "SG",
        "exemption_code": null
      }],
      "payment_method": "reference",
      "totals": {"net_minor": 100000, "tax_minor": 14000, "gross_minor": 114000},
      "issuer": {
        "profile_id": "5fd44094-296a-4392-88eb-54da8e1bda4b",
        "tax_id": "5000000000",
        "legal_name": "Empresa de exemplo",
        "address": "Luanda",
        "country": "AO",
        "eac_code": null
      }
    },
    "issued_at": null,
    "validated_at": null,
    "last_error_code": null,
    "created_at": "2026-10-16T10:00:00+00:00",
    "original_document_id": null,
    "corrects_document_id": null,
    "due_date": null,
    "calculation_version": "integer-v1"
  }
}

Autenticar antes de processar

Calcule a assinatura sobre os bytes originais do corpo, antes de interpretar JSON. Use o segredo exactamente como foi entregue, sem o converter de hexadecimal para bytes. O timestamp refere-se à tentativa de entrega, não à criação do evento.

X-Pagamentos-Event-Id: 7c23abe1-0935-4715-85bd-b8ea818508ce
X-Pagamentos-Timestamp: 1792144800
X-Pagamentos-Signature: HMAC_SHA256_HEXADECIMAL
X-Pagamentos-Key-Id: 9db33cce-e132-4e8e-aafc-801698cbe66e
Content-Type: application/json

HMAC-SHA256(segredo_webhook, timestamp + "." + corpo_bruto)

Seleccione o segredo pelo X-Pagamentos-Key-Id, compare assinaturas com hash_equals, aceite apenas timestamps a até 300 segundos do relógio do servidor e confirme que X-Pagamentos-Event-Id coincide com o id do corpo. Mantenha o relógio do receptor sincronizado.

Receptor PHP: verificar, deduplicar e persistir antes de responder

Este exemplo executável usa PHP 8.2+ e PDO SQLite para uma inbox local. Configure as três variáveis indicadas, crie a pasta do banco fora da pasta pública e permita escrita apenas ao serviço. Os segredos pertencem exclusivamente ao projecto e ambiente deste endpoint. No seu sistema, adapte a inbox ao banco e ao worker existentes.

<?php
declare(strict_types=1);

// PHP 8.2+ com PDO SQLite. Configure no servidor, nunca no navegador:
// PAGAMENTOS_WEBHOOK_KEYS: JSON {"UUID_DA_VERSAO":"SEGREDO_LITERAL"}
// PAGAMENTOS_WEBHOOK_SCOPE: identificador fixo do projecto e ambiente
// PAGAMENTOS_WEBHOOK_INBOX: caminho absoluto do SQLite fora da pasta pública

function rejectWebhook(int $status): never
{
    http_response_code($status);
    exit;
}

if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
    header('Allow: POST');
    rejectWebhook(405);
}

try {
    $keys = json_decode(getenv('PAGAMENTOS_WEBHOOK_KEYS') ?: '{}', true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException) {
    rejectWebhook(500);
}
$scope = getenv('PAGAMENTOS_WEBHOOK_SCOPE');
$inboxPath = getenv('PAGAMENTOS_WEBHOOK_INBOX');
if (!is_array($keys) || !$scope || !$inboxPath || !str_starts_with($inboxPath, '/')) {
    rejectWebhook(500);
}

$raw = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_PAGAMENTOS_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_PAGAMENTOS_SIGNATURE'] ?? '';
$eventId = $_SERVER['HTTP_X_PAGAMENTOS_EVENT_ID'] ?? '';
$keyId = $_SERVER['HTTP_X_PAGAMENTOS_KEY_ID'] ?? '';
// Compatibilidade legada apenas se o operador configurar a chave "legacy".
$secret = $keys[$keyId === '' ? 'legacy' : $keyId] ?? null;
$uuid = '/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i';

if (!is_string($raw) || !is_string($secret) || $secret === ''
    || !preg_match('/\A[0-9]{1,11}\z/', $timestamp)
    || abs(time() - (int) $timestamp) > 300
    || !preg_match('/\A[0-9a-f]{64}\z/', $signature)
    || ($keyId !== '' && !preg_match($uuid, $keyId))
    || !preg_match($uuid, $eventId)) {
    rejectWebhook(401);
}
$expected = hash_hmac('sha256', $timestamp.'.'.$raw, $secret);
if (!hash_equals($expected, $signature)) {
    rejectWebhook(401);
}

// Só interpretar JSON depois de autenticar os bytes recebidos.
try {
    $event = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException) {
    rejectWebhook(400);
}
if (!is_array($event) || !is_string($event['id'] ?? null)
    || !hash_equals($eventId, $event['id'])
    || !is_string($event['type'] ?? null)
    || !is_string($event['created_at'] ?? null)
    || !is_array($event['data'] ?? null)) {
    rejectWebhook(400);
}

// Inbox durável: apenas um registo por evento neste projecto/ambiente.
// Num serviço existente, crie esta tabela por migration no seu banco.
$db = null;
try {
    $db = new PDO('sqlite:'.$inboxPath, null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
    $db->exec('PRAGMA busy_timeout = 5000');
    $db->exec('CREATE TABLE IF NOT EXISTS webhook_inbox (
        scope TEXT NOT NULL, event_id TEXT NOT NULL, body TEXT NOT NULL,
        body_hash TEXT NOT NULL, received_at TEXT NOT NULL, processed_at TEXT,
        PRIMARY KEY (scope, event_id)
    )');
    $db->beginTransaction();
    $hash = hash('sha256', $raw);
    $insert = $db->prepare('INSERT INTO webhook_inbox
        (scope, event_id, body, body_hash, received_at) VALUES (?, ?, ?, ?, ?)
        ON CONFLICT (scope, event_id) DO NOTHING');
    $insert->execute([$scope, $eventId, $raw, $hash, gmdate('c')]);
    $read = $db->prepare('SELECT body_hash FROM webhook_inbox WHERE scope = ? AND event_id = ?');
    $read->execute([$scope, $eventId]);
    if (!hash_equals((string) $read->fetchColumn(), $hash)) {
        $db->rollBack();
        rejectWebhook(409);
    }
    $db->commit();
} catch (PDOException) {
    if ($db instanceof PDO && $db->inTransaction()) {
        $db->rollBack();
    }
    rejectWebhook(503); // Sem persistência, permitir nova tentativa de entrega.
}

// Um worker da sua aplicação processa a inbox e marca processed_at.
// Também responder 204 a um evento repetido que já foi persistido.
http_response_code(204);

A resposta 204 confirma que o evento foi guardado. O exemplo não altera encomendas: um worker da aplicação deve ler os registos com processed_at nulo, conferir empresa, ambiente, moeda e montante contra a encomenda local e aplicar cada efeito de negócio uma única vez, numa transacção. Marque o registo como processado na mesma transacção.

Se também consultar o pagamento pela API, encaminhe a confirmação para a mesma operação idempotente. Uma restrição única por projecto, ambiente, ID do pagamento e efeito de negócio impede liquidar ou entregar a mesma encomenda duas vezes quando a consulta e o webhook confirmam o mesmo recebimento.

Eventos podem repetir-se e chegar fora de ordem. Evite duplicações pelo id do evento com uma restrição única persistente, inclusive após reenvios manuais. Um evento repetido já guardado deve receber 2xx. Não substitua um pagamento confirmado por um estado antigo recebido depois; consulte o recurso na API quando precisar de reconciliar a sequência.

Na rotação, configure a nova versão no receptor e aceite também a anterior durante a transição das entregas em trânsito. Novas tentativas usam a versão corrente. Entregas legadas podem não incluir X-Pagamentos-Key-Id; o exemplo só as aceita se configurar explicitamente uma entrada legacy com o segredo legado. Uma versão desconhecida é recusada, sem tentar outros segredos.

Tentativas e recuperação

Responda 2xx depois de persistir o evento. Erros HTTP, falhas de ligação ou timeout podem provocar nova entrega; redireccionamentos não são seguidos. Cada ciclo permite até oito tentativas, com intervalos de 1 minuto, 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas e 12 horas após as falhas sucessivas. O envio tem timeout de 10 segundos e depende do worker/scheduler activo.

Operação administrativa	Consulta ou recuperação
`GET /portal/api/webhooks`	Lista 50 entregas por página. Filtros: `status=pending\|sending\|failed\|delivered`, `event_type`, `payment_id` e `page`.
`GET /portal/api/webhooks/{id}`	Estado, tentativas e histórico dos reenvios.
`POST /portal/api/webhooks/{id}/retry`	Reagenda uma entrega falhada, sem worker activo. Exige `operations.manage` e `reason`; devolve 202. Até três reenvios manuais, cada um com até oito tentativas. Repetir enquanto já está agendada devolve 409.
`GET /portal/api/events`	Consulta eventos do projecto e ambiente, com `type` e `page` opcionais.
`POST /portal/api/webhook-endpoint/backfill`	Agenda eventos dos últimos 30 dias: de 1 a 100 UUIDs distintos por pedido e `reason`. Exige destino activo e `operations.manage`; devolve 202. Não reinicia entregas existentes.

POST /portal/api/webhooks/UUID_DA_ENTREGA/retry
Content-Type: application/json

{"reason":"Serviço consumidor recuperado e causa da falha corrigida."}

POST /portal/api/webhook-endpoint/backfill
Content-Type: application/json

{
  "event_ids": ["7c23abe1-0935-4715-85bd-b8ea818508ce"],
  "reason": "Entregar evento anterior à activação do destino."
}

Os motivos têm 5–500 caracteres e ficam auditados. Configuração, rotação, backfill e reenvio têm limite adicional de 10 pedidos por minuto. Activar um destino não envia automaticamente eventos antigos. Alterar ou desactivar a URL também não modifica o destino já guardado nas entregas anteriores.

Diagnóstico

Estados, erros e limites

Trate o pagamento e a emissão fiscal separadamente. Um pagamento confirmado mantém-se pago mesmo que a emissão falhe. Guarde o X-Request-ID da resposta para localizar a chamada nos registos da instalação.

Recurso	Como interpretar
Pagamento	`creating` → `pending` → `paid`. Com factura (`document_type` `FT`) começa em `awaiting_invoice`, sem referência, até a AGT validar a factura; se a AGT a rejeitar, fica `invoice_rejected` até ser corrigida. Pode expirar (`expired`), ser renovado de volta a `pending` ou ser cancelado (`cancelled`). Uma confirmação bancária tardia pode produzir `paid` mesmo após expiração ou cancelamento.
Documento	`queued`, `submitting`, `submitted`, `checking`, `valid`, `rejected`, `blocked`, `unknown` ou `simulated`. Em `blocked`, inspeccione `last_error_code` e corrija a causa; `unknown` exige reconciliação. Depois de corrigir, retome o envio no portal, no detalhe do documento, em Repetir envio.
Simulação	Pagamentos usam `simulated: true` e os estados normais de cobrança. Documentos locais podem ter `status: simulated`, sem validade fiscal. Sandbox real também não deve ser tratado como produção.

A recepção de um documento pela AGT, incluindo um requestID, não equivale à aprovação. Consulte o estado final e fiscal_valid; em Sandbox este indicador continua falso.

Formato de erros de domínio e validação

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Esta chave já foi usada com outros dados."
  }
}

{
  "message": "amount_minor deve ser um inteiro JSON em cêntimos.",
  "errors": {
    "amount_minor": ["amount_minor deve ser um inteiro JSON em cêntimos."]
  },
  "error": {
    "code": "validation_failed",
    "message": "amount_minor deve ser um inteiro JSON em cêntimos."
  }
}

Use error.code para decidir o comportamento do consumidor. As mensagens podem variar. A validação também conserva message e errors, com erros por campo.

HTTP / código	Próxima acção
`401 unauthenticated`	Confira a chave do projecto, validade e revogação. Não use a chave ProxyPay como Bearer.
`403 permission_denied`	Atribua à chave o scope exigido pela operação.
`404 not_found` `merchant_not_found`	Confira UUID, projecto, ambiente e concessão de acesso à empresa. `/simulate` também devolve 404 quando o simulador não está autorizado.
`409 idempotency_conflict`	O corpo ou motivo mudou para a mesma chave. Recupere a intenção original; não altere a chave para repetir a mesma venda.
`409 payment_processing`	A criação ainda está em curso. Aguarde e repita com a mesma chave e corpo.
`409 creation_expired`	A validade terminou durante a criação. Consulte a cobrança antes de decidir criar uma nova intenção.
`409 payment_not_renewable`	Só uma cobrança expirada, não paga e sem pedido de cancelamento pode ser renovada. Para mudar valor ou artigos, crie uma cobrança nova.
`409 invoice_not_attachable`	`PUT /payments/{payment}/invoice` só corrige uma factura rejeitada (`invoice_rejected`), corrige a factura-recibo rejeitada de uma cobrança `paid`, ou pede FR para uma cobrança paga sem documento.
`422 validation_failed` em `document_type` ou `invoice_data`	Envie os dois juntos, ou nenhum. `document_type` aceita `FR` ou `FT`.
`422 validation_failed` em `paid_at`, `method`, `expires_at` ou `document_type` de um pagamento registado	Com `method` diferente de `reference`, envie `paid_at` no passado (até 365 dias), não envie `expires_at` e use `FR` ou nenhum documento. Sem `method`, não envie `paid_at` nem `method_reference`.
`422 validation_failed` em `capability`	Factura, recibo, nota de crédito ou correcção ainda não estão habilitados em produção. Use o Sandbox ou contacte o suporte.
`409 payment_not_cancellable` `cancellation_not_retryable`	Consulte pagamento e cancelamento; confira o estado e os limites de repetição.
`422 validation_failed` `invalid_idempotency_key` `invalid_expiration`	Corrija os campos indicados. Datas precisam de fuso e validade futura; montantes devem ser inteiros JSON.
`422 validation_failed` em `items.N.vat_rate`, `tax_code` ou `exemption_code`	Use 14, 7, 5, 1 ou 0%. Omita `tax_code` ou envie o que corresponde à taxa. Em 0%, indique um motivo activo de `GET /fiscal/exemption-reasons`; nas outras taxas, não envie motivo.
`422 validation_failed` em `items.N.cnbs_code`	Envie um código activo de `GET /fiscal/cnbs-codes`, com 8 algarismos. Desde a data `required_from`, cada linha de FT e FR tem de o trazer.
`422 validation_failed` em `customer.tax_id`	Com a validação de NIF activa, a AGT não conhece este NIF. Confirme o NIF do cliente; nada foi criado.
`422 merchant_account_unavailable`	Configure e active a conta da empresa no mesmo ambiente da chave.
`423 new_operations_suspended`	A administração da plataforma suspendeu a criação de cobranças e documentos desta empresa neste ambiente. O que já foi criado, incluindo confirmações de pagamento, continua a ser processado. Contacte o suporte antes de repetir.
`429 rate_limited`	Respeite `Retry-After`. Use espera progressiva e preserve a identidade do pedido.
`502 provider_unavailable`	O resultado do provedor pode ser incerto. Consulte a cobrança ou repita a criação com a chave original.

Limites de utilização

120 pedidos por minuto por projecto e ambiente na API autenticada. Chaves do mesmo projecto e ambiente partilham este limite.
Renovações, correcções de factura, retries de cancelamento, retries de associação fiscal e criação de exportações têm ainda um limite de 10 pedidos por minuto aplicado pela rota.
Cobranças e documentos devolvem 50 resultados por página, em data, com meta.current_page, meta.last_page e meta.total. Rascunhos, catálogos e exportações usam paginação no topo; associações fiscais têm a paginação dentro de data.

Campos adicionais podem ser introduzidos em v1. Ignore campos desconhecidos e não dependa da ordem das propriedades JSON. Mudanças incompatíveis exigem outra versão. A referência OpenAPI contém os tipos e parâmetros de cada operação.

Contrato completo · 1.1.0

Referência da API

Operações, scopes e schemas abaixo vêm do mesmo contrato OpenAPI disponível para download. Os caminhos são relativos a https://nexo.seruvo.vitorperez.dev.br/api/v1. Expanda uma operação para consultar parâmetros e respostas.

Procurar operação Descarregar OpenAPI

Disponibilidade

GET/health

Process health; use /health/ready for dependency readiness.

Sem autenticação de projecto. Verifica o processo; use /health/ready, na raiz do domínio e fora de /api/v1, para a disponibilidade da base e da cache.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "service": {
            "type": "string"
        },
        "status": {
            "type": "string"
        }
    }
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

Ligação da chave

GET/connection

Confirm the key in use: its id, prefix, environment, scopes, validity and the merchant it is bound to, never the secret. Any valid key may call it, without a scope. A revoked, expired or unknown key gets 401. Use GET /merchants/{merchant}/fiscal/readiness for the fiscal readiness of the merchant.

Sem autenticação de projecto. Verifica o processo; use /health/ready, na raiz do domínio e fora de /api/v1, para a disponibilidade da base e da cache.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "credential_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "key_prefix": {
                    "type": "string"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "active"
                    ]
                },
                "merchant": {
                    "type": "object",
                    "properties": {
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "slug": {
                            "type": "string"
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "id"
                    ],
                    "description": "The merchant this key is bound to, or null when the key reaches every merchant of the project. slug and name only with merchants:read.",
                    "nullable": true
                }
            },
            "required": [
                "credential_id",
                "key_prefix",
                "environment",
                "scopes",
                "expires_at",
                "status",
                "merchant"
            ],
            "$ref": "#/components/schemas/Connection"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/connection/disconnect

End the connection of the key in use: revokes this key only and frees its merchant. Project grants and the other keys of the project are untouched. Idempotency-Key is required and the answer is a persistent receipt. If the answer is lost, repeat the request with the same key and the same Idempotency-Key: after the revocation this route alone still accepts that key for that Idempotency-Key and returns the same receipt (200). Any other request with the revoked key, or another Idempotency-Key, gets 401. An expired key may call this route (and only this one) to disconnect. No scope is required.

Sem autenticação de projecto. Verifica o processo; use /health/ready, na raiz do domínio e fora de /api/v1, para a disponibilidade da base e da cache.

Parâmetros

Nome	Local / tipo	Regra
`Idempotency-Key`	header · string	Obrigatório. Reuse the same key and body on retries. Scope is project and environment.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "receipt_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "revoked"
                    ]
                },
                "credential_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "revoked_at": {
                    "type": "string",
                    "format": "date-time"
                }
            },
            "required": [
                "receipt_id",
                "status",
                "credential_id",
                "environment",
                "merchant_id",
                "revoked_at"
            ],
            "$ref": "#/components/schemas/Disconnection"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

Empresas e catálogos

GET/merchants

List merchants explicitly granted to this project.

Bearer do projecto · merchants:read

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "slug",
                    "name"
                ],
                "$ref": "#/components/schemas/Merchant"
            }
        },
        "environment": {
            "type": "string"
        }
    },
    "required": [
        "data",
        "environment"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/merchants

Create a merchant owned by this project, optionally with its fiscal identity. For platforms onboarding many merchants; requires the explicit merchants:write scope.

Bearer do projecto · merchants:write

Corpo JSON

Campo	Tipo	Obrigatório
`slug`	string	Sim
`name`	string	Sim
`tax_id`	string	Não
`legal_name`	string	Não
`address`	string	Não

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,79}$",
            "description": "Your identifier for the merchant. Repeating the same slug and name returns the existing merchant (200)."
        },
        "name": {
            "type": "string",
            "maxLength": 160
        },
        "tax_id": {
            "type": "string",
            "pattern": "^[A-Z0-9]{9,15}$",
            "description": "Optional fiscal identity for the key environment; requires legal_name and address."
        },
        "legal_name": {
            "type": "string",
            "maxLength": 160
        },
        "address": {
            "type": "string",
            "maxLength": 500
        }
    },
    "required": [
        "slug",
        "name"
    ],
    "$ref": "#/components/schemas/CreateMerchant"
}

Respostas

201 401 403 404 409 422 423 429 502 200

201 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "slug": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                },
                "account": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "merchant_id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "environment": {
                                    "type": "string",
                                    "enum": [
                                        "sandbox",
                                        "live"
                                    ]
                                },
                                "provider": {
                                    "type": "string",
                                    "enum": [
                                        "mock",
                                        "proxypay"
                                    ]
                                },
                                "entity": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "active": {
                                    "type": "boolean"
                                },
                                "reconciliation_enabled": {
                                    "type": "boolean"
                                },
                                "has_api_key": {
                                    "type": "boolean",
                                    "description": "The ProxyPay key is never returned."
                                }
                            },
                            "required": [
                                "id",
                                "merchant_id",
                                "environment",
                                "provider",
                                "active",
                                "has_api_key"
                            ],
                            "$ref": "#/components/schemas/MerchantAccount"
                        }
                    ],
                    "nullable": true
                },
                "fiscal_profile": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "merchant_id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "environment": {
                                    "type": "string",
                                    "enum": [
                                        "sandbox",
                                        "live"
                                    ]
                                },
                                "tax_id": {
                                    "type": "string"
                                },
                                "legal_name": {
                                    "type": "string"
                                },
                                "address": {
                                    "type": "string"
                                },
                                "eac_code": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "commercial_registry": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "tax_entity": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "city": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "enabled": {
                                    "type": "boolean"
                                },
                                "simulated": {
                                    "type": "boolean"
                                },
                                "has_private_key": {
                                    "type": "boolean",
                                    "description": "The private key is never returned."
                                },
                                "created_at": {
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "updated_at": {
                                    "type": "string",
                                    "format": "date-time"
                                }
                            },
                            "required": [
                                "id",
                                "merchant_id",
                                "environment",
                                "tax_id",
                                "legal_name",
                                "address",
                                "enabled",
                                "simulated",
                                "has_private_key"
                            ],
                            "$ref": "#/components/schemas/FiscalProfile"
                        }
                    ],
                    "nullable": true
                }
            },
            "required": [
                "id",
                "slug",
                "name",
                "account",
                "fiscal_profile"
            ],
            "$ref": "#/components/schemas/ManagedMerchant"
        },
        "environment": {
            "type": "string"
        }
    },
    "required": [
        "data",
        "environment"
    ]
}

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "slug": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                },
                "account": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "merchant_id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "environment": {
                                    "type": "string",
                                    "enum": [
                                        "sandbox",
                                        "live"
                                    ]
                                },
                                "provider": {
                                    "type": "string",
                                    "enum": [
                                        "mock",
                                        "proxypay"
                                    ]
                                },
                                "entity": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "active": {
                                    "type": "boolean"
                                },
                                "reconciliation_enabled": {
                                    "type": "boolean"
                                },
                                "has_api_key": {
                                    "type": "boolean",
                                    "description": "The ProxyPay key is never returned."
                                }
                            },
                            "required": [
                                "id",
                                "merchant_id",
                                "environment",
                                "provider",
                                "active",
                                "has_api_key"
                            ],
                            "$ref": "#/components/schemas/MerchantAccount"
                        }
                    ],
                    "nullable": true
                },
                "fiscal_profile": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "merchant_id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "environment": {
                                    "type": "string",
                                    "enum": [
                                        "sandbox",
                                        "live"
                                    ]
                                },
                                "tax_id": {
                                    "type": "string"
                                },
                                "legal_name": {
                                    "type": "string"
                                },
                                "address": {
                                    "type": "string"
                                },
                                "eac_code": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "commercial_registry": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "tax_entity": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "city": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "enabled": {
                                    "type": "boolean"
                                },
                                "simulated": {
                                    "type": "boolean"
                                },
                                "has_private_key": {
                                    "type": "boolean",
                                    "description": "The private key is never returned."
                                },
                                "created_at": {
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "updated_at": {
                                    "type": "string",
                                    "format": "date-time"
                                }
                            },
                            "required": [
                                "id",
                                "merchant_id",
                                "environment",
                                "tax_id",
                                "legal_name",
                                "address",
                                "enabled",
                                "simulated",
                                "has_private_key"
                            ],
                            "$ref": "#/components/schemas/FiscalProfile"
                        }
                    ],
                    "nullable": true
                }
            },
            "required": [
                "id",
                "slug",
                "name",
                "account",
                "fiscal_profile"
            ],
            "$ref": "#/components/schemas/ManagedMerchant"
        },
        "environment": {
            "type": "string"
        }
    },
    "required": [
        "data",
        "environment"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/merchants/{merchant}

Read a merchant with its payment account and fiscal profile in the key environment. Secrets are never returned.

Bearer do projecto · merchants:read

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "slug": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                },
                "account": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "merchant_id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "environment": {
                                    "type": "string",
                                    "enum": [
                                        "sandbox",
                                        "live"
                                    ]
                                },
                                "provider": {
                                    "type": "string",
                                    "enum": [
                                        "mock",
                                        "proxypay"
                                    ]
                                },
                                "entity": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "active": {
                                    "type": "boolean"
                                },
                                "reconciliation_enabled": {
                                    "type": "boolean"
                                },
                                "has_api_key": {
                                    "type": "boolean",
                                    "description": "The ProxyPay key is never returned."
                                }
                            },
                            "required": [
                                "id",
                                "merchant_id",
                                "environment",
                                "provider",
                                "active",
                                "has_api_key"
                            ],
                            "$ref": "#/components/schemas/MerchantAccount"
                        }
                    ],
                    "nullable": true
                },
                "fiscal_profile": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "merchant_id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "environment": {
                                    "type": "string",
                                    "enum": [
                                        "sandbox",
                                        "live"
                                    ]
                                },
                                "tax_id": {
                                    "type": "string"
                                },
                                "legal_name": {
                                    "type": "string"
                                },
                                "address": {
                                    "type": "string"
                                },
                                "eac_code": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "commercial_registry": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "tax_entity": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "city": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "enabled": {
                                    "type": "boolean"
                                },
                                "simulated": {
                                    "type": "boolean"
                                },
                                "has_private_key": {
                                    "type": "boolean",
                                    "description": "The private key is never returned."
                                },
                                "created_at": {
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "updated_at": {
                                    "type": "string",
                                    "format": "date-time"
                                }
                            },
                            "required": [
                                "id",
                                "merchant_id",
                                "environment",
                                "tax_id",
                                "legal_name",
                                "address",
                                "enabled",
                                "simulated",
                                "has_private_key"
                            ],
                            "$ref": "#/components/schemas/FiscalProfile"
                        }
                    ],
                    "nullable": true
                }
            },
            "required": [
                "id",
                "slug",
                "name",
                "account",
                "fiscal_profile"
            ],
            "$ref": "#/components/schemas/ManagedMerchant"
        },
        "environment": {
            "type": "string"
        }
    },
    "required": [
        "data",
        "environment"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

PUT/merchants/{merchant}/account

Configure the ProxyPay account in the key environment. Owner only; audited with the reason.

Bearer do projecto · merchants:write

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`provider`	string	Sim
`entity`	string	Não
`api_key`	string	Não
`reconciliation_enabled`	boolean	Não
`reason`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "provider": {
            "type": "string",
            "enum": [
                "proxypay",
                "mock"
            ],
            "description": "mock only in local/testing sandbox."
        },
        "entity": {
            "type": "string",
            "pattern": "^[0-9]{1,5}$"
        },
        "api_key": {
            "type": "string",
            "maxLength": 4096,
            "description": "ProxyPay key. Omit to keep the stored key; it is never returned."
        },
        "reconciliation_enabled": {
            "type": "boolean"
        },
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 500
        }
    },
    "required": [
        "provider",
        "reason"
    ],
    "$ref": "#/components/schemas/MerchantAccountInput"
}

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "provider": {
                    "type": "string",
                    "enum": [
                        "mock",
                        "proxypay"
                    ]
                },
                "entity": {
                    "type": "string",
                    "nullable": true
                },
                "active": {
                    "type": "boolean"
                },
                "reconciliation_enabled": {
                    "type": "boolean"
                },
                "has_api_key": {
                    "type": "boolean",
                    "description": "The ProxyPay key is never returned."
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "provider",
                "active",
                "has_api_key"
            ],
            "$ref": "#/components/schemas/MerchantAccount"
        },
        "environment": {
            "type": "string"
        }
    },
    "required": [
        "data",
        "environment"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/merchants/{merchant}/account/test

Test the ProxyPay connection of the configured account.

Bearer do projecto · merchants:write

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object"
        },
        "environment": {
            "type": "string"
        }
    },
    "required": [
        "data",
        "environment"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

PUT/merchants/{merchant}/fiscal

Create or change the fiscal profile in the key environment. Owner only; audited.

Bearer do projecto · merchants:write

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`tax_id`	string	Sim
`legal_name`	string	Sim
`address`	string	Sim
`eac_code`	string \| null	Não
`commercial_registry`	string \| null	Não
`tax_entity`	string \| null	Não
`city`	string \| null	Não
`enabled`	boolean	Não
`simulated`	boolean	Não
`issuer_private_key`	string \| null	Não

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "tax_id": {
            "type": "string",
            "pattern": "^[A-Z0-9]{9,15}$"
        },
        "legal_name": {
            "type": "string",
            "maxLength": 160
        },
        "address": {
            "type": "string",
            "maxLength": 500
        },
        "eac_code": {
            "type": "string",
            "pattern": "^[0-9]{5}$",
            "nullable": true
        },
        "commercial_registry": {
            "type": "string",
            "maxLength": 50,
            "description": "Commercial registry number, written as CompanyID in the SAF-T header.",
            "nullable": true
        },
        "tax_entity": {
            "type": "string",
            "maxLength": 20,
            "description": "TaxEntity of the SAF-T header. Empty means Global.",
            "nullable": true
        },
        "city": {
            "type": "string",
            "maxLength": 50,
            "description": "City of the fiscal address, for the SAF-T header.",
            "nullable": true
        },
        "enabled": {
            "type": "boolean",
            "description": "Requires the private key unless simulated."
        },
        "simulated": {
            "type": "boolean",
            "description": "Local sandbox only."
        },
        "issuer_private_key": {
            "type": "string",
            "maxLength": 16384,
            "description": "PEM RSA key, at least 2048 bits. Omit to keep the stored key; it is never returned.",
            "nullable": true
        }
    },
    "required": [
        "tax_id",
        "legal_name",
        "address"
    ],
    "$ref": "#/components/schemas/FiscalProfileInput"
}

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "tax_id": {
                    "type": "string"
                },
                "legal_name": {
                    "type": "string"
                },
                "address": {
                    "type": "string"
                },
                "eac_code": {
                    "type": "string",
                    "nullable": true
                },
                "commercial_registry": {
                    "type": "string",
                    "nullable": true
                },
                "tax_entity": {
                    "type": "string",
                    "nullable": true
                },
                "city": {
                    "type": "string",
                    "nullable": true
                },
                "enabled": {
                    "type": "boolean"
                },
                "simulated": {
                    "type": "boolean"
                },
                "has_private_key": {
                    "type": "boolean",
                    "description": "The private key is never returned."
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "updated_at": {
                    "type": "string",
                    "format": "date-time"
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "tax_id",
                "legal_name",
                "address",
                "enabled",
                "simulated",
                "has_private_key"
            ],
            "$ref": "#/components/schemas/FiscalProfile"
        },
        "environment": {
            "type": "string"
        }
    },
    "required": [
        "data",
        "environment"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/merchants/{merchant}/fiscal/readiness

Which document types (FR, FT, RG, NC) can be issued and what is missing.

Bearer do projecto · merchants:read

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/merchants/{merchant}/fiscal/series

List registered fiscal series and series requests.

Bearer do projecto · merchants:read

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "document_type": {
                        "type": "string",
                        "enum": [
                            "FR",
                            "FT",
                            "RG",
                            "NC"
                        ]
                    },
                    "series_code": {
                        "type": "string"
                    },
                    "year": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "establishment": {
                        "type": "string"
                    },
                    "first_number": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "last_number": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "next_number": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "active": {
                        "type": "boolean"
                    },
                    "origin": {
                        "type": "string",
                        "enum": [
                            "agt",
                            "internal"
                        ],
                        "description": "agt: communicated to the AGT one by one. internal: kept in Nexo and delivered in the SAF-T file. It never changes once the series has documents."
                    }
                },
                "required": [
                    "id",
                    "document_type",
                    "series_code",
                    "year",
                    "next_number",
                    "active",
                    "origin"
                ],
                "$ref": "#/components/schemas/FiscalSeries"
            }
        },
        "requests": {
            "type": "array",
            "items": {
                "type": "object"
            }
        }
    },
    "required": [
        "data",
        "requests"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/merchants/{merchant}/fiscal/series/internal

Create a series kept in Nexo (origin internal): no AGT registration, its documents are delivered in the SAF-T file. Repeating the same series returns it; a type and year can have only one active series.

Bearer do projecto · merchants:write

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`document_type`	string	Sim
`year`	integer	Sim
`series_code`	string \| null	Não
`establishment`	string \| null	Não
`first_number`	integer	Não
`last_number`	integer	Não
`reason`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "document_type": {
            "type": "string",
            "enum": [
                "FR",
                "FT",
                "RG",
                "NC"
            ]
        },
        "year": {
            "type": "integer",
            "format": "int64",
            "minimum": 2000,
            "maximum": 2099
        },
        "series_code": {
            "type": "string",
            "minLength": 3,
            "maxLength": 46,
            "description": "Defaults to the type followed by the year.",
            "nullable": true
        },
        "establishment": {
            "type": "string",
            "maxLength": 200,
            "description": "Defaults to SEDE.",
            "nullable": true
        },
        "first_number": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "description": "Defaults to 1."
        },
        "last_number": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "description": "Defaults to 999999999999."
        },
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 500
        }
    },
    "required": [
        "document_type",
        "year",
        "reason"
    ],
    "$ref": "#/components/schemas/FiscalSeriesInternal"
}

Respostas

201 401 403 404 409 422 423 429 502

201 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT",
                        "RG",
                        "NC"
                    ]
                },
                "series_code": {
                    "type": "string"
                },
                "year": {
                    "type": "integer",
                    "format": "int64"
                },
                "establishment": {
                    "type": "string"
                },
                "first_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "last_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "next_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "active": {
                    "type": "boolean"
                },
                "origin": {
                    "type": "string",
                    "enum": [
                        "agt",
                        "internal"
                    ],
                    "description": "agt: communicated to the AGT one by one. internal: kept in Nexo and delivered in the SAF-T file. It never changes once the series has documents."
                }
            },
            "required": [
                "id",
                "document_type",
                "series_code",
                "year",
                "next_number",
                "active",
                "origin"
            ],
            "$ref": "#/components/schemas/FiscalSeries"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/merchants/{merchant}/fiscal/series/import

Bearer do projecto · merchants:write

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`document_type`	string	Sim
`year`	integer	Sim
`series_code`	string	Sim
`first_number`	integer	Sim
`last_number`	integer	Sim
`next_number`	integer	Sim
`establishment`	string	Sim
`registered`	boolean	Sim
`reason`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "document_type": {
            "type": "string",
            "enum": [
                "FR",
                "FT",
                "RG",
                "NC"
            ]
        },
        "year": {
            "type": "integer",
            "format": "int64",
            "minimum": 2000,
            "maximum": 2099
        },
        "series_code": {
            "type": "string",
            "minLength": 2,
            "maxLength": 46
        },
        "first_number": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
        },
        "last_number": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
        },
        "next_number": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
        },
        "establishment": {
            "type": "string",
            "maxLength": 200
        },
        "registered": {
            "type": "boolean",
            "enum": [
                true
            ],
            "description": "Confirms the series is already registered at AGT. Nexo does not create it."
        },
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 500
        }
    },
    "required": [
        "document_type",
        "year",
        "series_code",
        "first_number",
        "last_number",
        "next_number",
        "establishment",
        "registered",
        "reason"
    ],
    "$ref": "#/components/schemas/FiscalSeriesImport"
}

Respostas

201 401 403 404 409 422 423 429 502

201 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT",
                        "RG",
                        "NC"
                    ]
                },
                "series_code": {
                    "type": "string"
                },
                "year": {
                    "type": "integer",
                    "format": "int64"
                },
                "establishment": {
                    "type": "string"
                },
                "first_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "last_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "next_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "active": {
                    "type": "boolean"
                },
                "origin": {
                    "type": "string",
                    "enum": [
                        "agt",
                        "internal"
                    ],
                    "description": "agt: communicated to the AGT one by one. internal: kept in Nexo and delivered in the SAF-T file. It never changes once the series has documents."
                }
            },
            "required": [
                "id",
                "document_type",
                "series_code",
                "year",
                "next_number",
                "active",
                "origin"
            ],
            "$ref": "#/components/schemas/FiscalSeries"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/merchants/{merchant}/fiscal/series/{seriesId}/deactivate

Stop using a series. Issued numbering is kept; the series is never reactivated.

Bearer do projecto · merchants:write

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.
`seriesId`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`reason`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 500
        }
    },
    "required": [
        "reason"
    ],
    "$ref": "#/components/schemas/Reason"
}

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT",
                        "RG",
                        "NC"
                    ]
                },
                "series_code": {
                    "type": "string"
                },
                "year": {
                    "type": "integer",
                    "format": "int64"
                },
                "establishment": {
                    "type": "string"
                },
                "first_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "last_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "next_number": {
                    "type": "integer",
                    "format": "int64"
                },
                "active": {
                    "type": "boolean"
                },
                "origin": {
                    "type": "string",
                    "enum": [
                        "agt",
                        "internal"
                    ],
                    "description": "agt: communicated to the AGT one by one. internal: kept in Nexo and delivered in the SAF-T file. It never changes once the series has documents."
                }
            },
            "required": [
                "id",
                "document_type",
                "series_code",
                "year",
                "next_number",
                "active",
                "origin"
            ],
            "$ref": "#/components/schemas/FiscalSeries"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/merchants/{merchant}/catalogue/{kind}

List project catalogue for merchant and environment.

Bearer do projecto · catalogue:read

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.
`kind`	path · string	Obrigatório. `customers \| items`
`page`	query · integer	Opcional. Pages of 50 records.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object"
            }
        },
        "current_page": {
            "type": "integer",
            "format": "int64"
        },
        "last_page": {
            "type": "integer",
            "format": "int64"
        },
        "total": {
            "type": "integer",
            "format": "int64"
        }
    },
    "required": [
        "data",
        "current_page",
        "last_page",
        "total"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

PUT/merchants/{merchant}/catalogue/{kind}

Save a customer or item. Previously issued documents remain unchanged.

Bearer do projecto · catalogue:write

Parâmetros

Nome	Local / tipo	Regra
`merchant`	path · string	Obrigatório.
`kind`	path · string	Obrigatório. `customers \| items`

Corpo JSON

Campo	Tipo	Obrigatório
`code`	string	Sim
`data`	object	Sim
`active`	boolean	Não

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "code": {
            "type": "string",
            "maxLength": 60
        },
        "data": {
            "oneOf": [
                {
                    "type": "object",
                    "properties": {
                        "tax_id": {
                            "type": "string",
                            "pattern": "^[A-Z0-9]{9,15}$"
                        },
                        "name": {
                            "type": "string",
                            "maxLength": 160
                        },
                        "address": {
                            "type": "string",
                            "maxLength": 500
                        },
                        "country": {
                            "type": "string",
                            "enum": [
                                "AO"
                            ]
                        }
                    },
                    "required": [
                        "tax_id",
                        "name",
                        "address",
                        "country"
                    ],
                    "$ref": "#/components/schemas/Customer"
                },
                {
                    "type": "object",
                    "properties": {
                        "code": {
                            "type": "string",
                            "maxLength": 60
                        },
                        "description": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "quantity": {
                            "oneOf": [
                                {
                                    "type": "integer",
                                    "format": "int64",
                                    "minimum": 1,
                                    "maximum": 99999
                                },
                                {
                                    "type": "string",
                                    "pattern": "^(?:0|[1-9][0-9]{0,4})(?:\\.[0-9]{1,4})?$"
                                }
                            ]
                        },
                        "unit_amount_minor": {
                            "type": "integer",
                            "format": "int64",
                            "minimum": 0,
                            "maximum": 9999999999
                        },
                        "vat_rate": {
                            "oneOf": [
                                {
                                    "type": "integer",
                                    "format": "int64",
                                    "enum": [
                                        14,
                                        7,
                                        5,
                                        1,
                                        0
                                    ]
                                },
                                {
                                    "type": "string",
                                    "pattern": "^(?:14|7|5|1|0)(?:\\.0{1,2})?$"
                                }
                            ],
                            "description": "Angolan VAT rate: 14, 7, 5, 1 or 0."
                        },
                        "tax_code": {
                            "type": "string",
                            "enum": [
                                "NOR",
                                "RED",
                                "ISE"
                            ],
                            "description": "Optional. Derived from vat_rate (0 ISE, 14 NOR, 7/5/1 RED); when sent it must match."
                        },
                        "operation_type": {
                            "type": "string",
                            "enum": [
                                "SE",
                                "SS",
                                "STP",
                                "SR",
                                "SIF",
                                "SHS",
                                "ST",
                                "SG",
                                "TB",
                                "AS",
                                "QT",
                                "RD"
                            ]
                        },
                        "exemption_code": {
                            "type": "string",
                            "pattern": "^M[0-9]{2}$",
                            "description": "Required for 0% and forbidden otherwise: an active code from GET /fiscal/exemption-reasons.",
                            "nullable": true
                        },
                        "discount_bps": {
                            "type": "integer",
                            "format": "int64",
                            "minimum": 0,
                            "maximum": 10000
                        },
                        "unit_of_measure": {
                            "type": "string",
                            "maxLength": 20
                        },
                        "original_line": {
                            "type": "integer",
                            "format": "int64",
                            "minimum": 1,
                            "description": "Required for NC: one-based line in the original document."
                        },
                        "catalogue_item_id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "cnbs_code": {
                            "type": "string",
                            "pattern": "^[0-9]{8}$",
                            "description": "CNBS code (INE classification of goods and services) from GET /fiscal/cnbs-codes, sent to the AGT as productCode instead of code. Optional until fiscal.cnbs_required_from (2027-01-01); from that date every FT and FR line must carry an active code.",
                            "nullable": true
                        }
                    },
                    "required": [
                        "code",
                        "description",
                        "quantity",
                        "unit_amount_minor",
                        "vat_rate",
                        "operation_type"
                    ],
                    "$ref": "#/components/schemas/DecimalItem"
                }
            ]
        },
        "active": {
            "type": "boolean"
        }
    },
    "required": [
        "code",
        "data"
    ],
    "$ref": "#/components/schemas/CatalogueInput"
}

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

Pagamentos

POST/payments

Create a reference. No fee until an eligible live payment is confirmed.

Bearer do projecto · payments:write

Parâmetros

Nome	Local / tipo	Regra
`Idempotency-Key`	header · string	Obrigatório. Reuse the same key and body on retries. Scope is project and environment.

Corpo JSON

Campo	Tipo	Obrigatório
`merchant_id`	string	Sim
`external_id`	string	Sim
`amount_minor`	integer	Sim
`currency`	string	Sim
`description`	string	Sim
`expires_at`	string	Não
`metadata`	object	Não
`document_type`	string	Não
`invoice_data`	object	Não
`order_data`	object	Não
`paid_at`	string	Não
`method`	string	Não
`method_reference`	string \| null	Não

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "merchant_id": {
            "type": "string",
            "format": "uuid"
        },
        "external_id": {
            "type": "string",
            "maxLength": 150
        },
        "amount_minor": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "maximum": 9999999999
        },
        "currency": {
            "type": "string",
            "enum": [
                "AOA"
            ]
        },
        "description": {
            "type": "string",
            "maxLength": 255
        },
        "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Future ISO-8601 instant, maximum 90 days. Defaults to 24 hours. Not accepted with a recorded method."
        },
        "metadata": {
            "type": "object",
            "maxProperties": 20,
            "additionalProperties": {
                "type": "string",
                "maxLength": 500
            }
        },
        "document_type": {
            "type": "string",
            "enum": [
                "FR",
                "FT"
            ],
            "description": "Fiscal document of the charge; required with invoice_data. Omit both for no document. FR: reference now, factura-recibo after payment. FT: invoice sent to AGT now, reference only after validation (status awaiting_invoice), receipt (RG) after payment."
        },
        "invoice_data": {
            "allOf": [
                {
                    "type": "object",
                    "properties": {
                        "customer": {
                            "type": "object",
                            "properties": {
                                "tax_id": {
                                    "type": "string",
                                    "pattern": "^[A-Z0-9]{9,15}$"
                                },
                                "name": {
                                    "type": "string",
                                    "maxLength": 160
                                },
                                "address": {
                                    "type": "string",
                                    "maxLength": 500
                                },
                                "country": {
                                    "type": "string",
                                    "enum": [
                                        "AO"
                                    ]
                                }
                            },
                            "required": [
                                "tax_id",
                                "name",
                                "address",
                                "country"
                            ],
                            "$ref": "#/components/schemas/Customer"
                        },
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "format": "int64",
                                        "minimum": 1,
                                        "maximum": 100000
                                    },
                                    "unit_amount_minor": {
                                        "type": "integer",
                                        "format": "int64",
                                        "minimum": 0,
                                        "maximum": 9999999999
                                    },
                                    "vat_rate": {
                                        "type": "integer",
                                        "format": "int64",
                                        "enum": [
                                            14,
                                            7,
                                            5,
                                            1,
                                            0
                                        ],
                                        "description": "Angolan VAT rate."
                                    },
                                    "tax_code": {
                                        "type": "string",
                                        "enum": [
                                            "NOR",
                                            "RED",
                                            "ISE"
                                        ],
                                        "description": "Optional. Derived from vat_rate (0 ISE, 14 NOR, 7/5/1 RED); when sent it must match."
                                    },
                                    "operation_type": {
                                        "type": "string",
                                        "enum": [
                                            "SE",
                                            "SS",
                                            "STP",
                                            "SR",
                                            "SIF",
                                            "SHS",
                                            "ST",
                                            "SG",
                                            "TB",
                                            "AS",
                                            "QT",
                                            "RD"
                                        ]
                                    },
                                    "exemption_code": {
                                        "type": "string",
                                        "pattern": "^M[0-9]{2}$",
                                        "description": "Required for 0% and forbidden otherwise: an active code from GET /fiscal/exemption-reasons.",
                                        "nullable": true
                                    },
                                    "cnbs_code": {
                                        "type": "string",
                                        "pattern": "^[0-9]{8}$",
                                        "description": "CNBS code (INE classification of goods and services) from GET /fiscal/cnbs-codes, sent to the AGT as productCode instead of code. Optional until fiscal.cnbs_required_from (2027-01-01); from that date every FT and FR line must carry an active code.",
                                        "nullable": true
                                    }
                                },
                                "required": [
                                    "code",
                                    "description",
                                    "quantity",
                                    "unit_amount_minor",
                                    "vat_rate",
                                    "operation_type"
                                ],
                                "$ref": "#/components/schemas/InvoiceItem"
                            },
                            "minItems": 1,
                            "maxItems": 100
                        },
                        "payment_method": {
                            "type": "string",
                            "enum": [
                                "reference"
                            ]
                        }
                    },
                    "required": [
                        "customer",
                        "items",
                        "payment_method"
                    ],
                    "$ref": "#/components/schemas/InvoiceRequest"
                }
            ],
            "description": "Customer and items of the document; required with document_type."
        },
        "order_data": {
            "allOf": [
                {
                    "type": "object",
                    "properties": {
                        "customer": {
                            "type": "object",
                            "properties": {
                                "tax_id": {
                                    "type": "string",
                                    "pattern": "^[A-Z0-9]{9,15}$"
                                },
                                "name": {
                                    "type": "string",
                                    "maxLength": 160
                                },
                                "address": {
                                    "type": "string",
                                    "maxLength": 500
                                },
                                "country": {
                                    "type": "string",
                                    "enum": [
                                        "AO"
                                    ]
                                }
                            },
                            "required": [
                                "tax_id",
                                "name",
                                "address",
                                "country"
                            ],
                            "$ref": "#/components/schemas/Customer"
                        },
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "format": "int64",
                                        "minimum": 1,
                                        "maximum": 100000
                                    },
                                    "unit_amount_minor": {
                                        "type": "integer",
                                        "format": "int64",
                                        "minimum": 0,
                                        "maximum": 9999999999
                                    },
                                    "vat_rate": {
                                        "type": "integer",
                                        "format": "int64",
                                        "enum": [
                                            14,
                                            7,
                                            5,
                                            1,
                                            0
                                        ],
                                        "description": "Angolan VAT rate."
                                    },
                                    "tax_code": {
                                        "type": "string",
                                        "enum": [
                                            "NOR",
                                            "RED",
                                            "ISE"
                                        ],
                                        "description": "Optional. Derived from vat_rate (0 ISE, 14 NOR, 7/5/1 RED); when sent it must match."
                                    },
                                    "operation_type": {
                                        "type": "string",
                                        "enum": [
                                            "SE",
                                            "SS",
                                            "STP",
                                            "SR",
                                            "SIF",
                                            "SHS",
                                            "ST",
                                            "SG",
                                            "TB",
                                            "AS",
                                            "QT",
                                            "RD"
                                        ]
                                    },
                                    "exemption_code": {
                                        "type": "string",
                                        "pattern": "^M[0-9]{2}$",
                                        "description": "Required for 0% and forbidden otherwise: an active code from GET /fiscal/exemption-reasons.",
                                        "nullable": true
                                    },
                                    "cnbs_code": {
                                        "type": "string",
                                        "pattern": "^[0-9]{8}$",
                                        "description": "CNBS code (INE classification of goods and services) from GET /fiscal/cnbs-codes, sent to the AGT as productCode instead of code. Optional until fiscal.cnbs_required_from (2027-01-01); from that date every FT and FR line must carry an active code.",
                                        "nullable": true
                                    }
                                },
                                "required": [
                                    "code",
                                    "description",
                                    "quantity",
                                    "unit_amount_minor",
                                    "vat_rate",
                                    "operation_type"
                                ],
                                "$ref": "#/components/schemas/InvoiceItem"
                            },
                            "minItems": 1,
                            "maxItems": 100
                        },
                        "payment_method": {
                            "type": "string",
                            "enum": [
                                "reference"
                            ]
                        }
                    },
                    "required": [
                        "customer",
                        "items",
                        "payment_method"
                    ],
                    "$ref": "#/components/schemas/InvoiceRequest"
                }
            ],
            "description": "Same customer and items as invoice_data, recorded without issuing a factura-recibo. Mutually exclusive with invoice_data."
        },
        "paid_at": {
            "type": "string",
            "format": "date-time",
            "description": "Required with a recorded method and forbidden otherwise: when the money was received, with seconds and offset, in the past and within 365 days."
        },
        "method": {
            "type": "string",
            "enum": [
                "reference",
                "cash",
                "bank_transfer",
                "card",
                "other"
            ],
            "default": "reference",
            "description": "reference creates a ProxyPay reference. cash, bank_transfer, card (card terminal) and other record money the merchant already received: the payment is created paid, with no reference and no expiry, and needs no ProxyPay account. document_type may then be FR or absent, never FT; an FT is settled by allocating the payment with POST /documents/{document}/allocations."
        },
        "method_reference": {
            "type": "string",
            "maxLength": 100,
            "nullable": true,
            "description": "Optional, recorded methods only: receipt, transfer or terminal reference."
        }
    },
    "required": [
        "merchant_id",
        "external_id",
        "amount_minor",
        "currency",
        "description"
    ],
    "$ref": "#/components/schemas/CreatePayment"
}

Respostas

201 401 403 404 409 422 423 429 502 200

201 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "external_id": {
                    "type": "string"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "amount_minor": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 1,
                    "maximum": 9999999999
                },
                "currency": {
                    "type": "string",
                    "enum": [
                        "AOA"
                    ]
                },
                "description": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "awaiting_invoice",
                        "invoice_rejected",
                        "creating",
                        "pending",
                        "expired",
                        "paid",
                        "cancelled"
                    ],
                    "description": "awaiting_invoice: FT sent to AGT, no reference yet. invoice_rejected: AGT rejected the FT; correct it with PUT /payments/{payment}/invoice."
                },
                "method": {
                    "type": "string",
                    "enum": [
                        "reference",
                        "cash",
                        "bank_transfer",
                        "card",
                        "other"
                    ],
                    "description": "reference for a ProxyPay charge; any other value for a payment recorded by the merchant."
                },
                "provider": {
                    "type": "string",
                    "enum": [
                        "mock",
                        "proxypay"
                    ],
                    "nullable": true,
                    "description": "null for a payment recorded by the merchant."
                },
                "simulated": {
                    "type": "boolean"
                },
                "reference": {
                    "type": "object",
                    "properties": {
                        "entity": {
                            "type": "string"
                        },
                        "number": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "entity",
                        "number"
                    ],
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "paid_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "metadata": {
                    "type": "object"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT"
                    ],
                    "nullable": true
                },
                "invoice_requested": {
                    "type": "boolean"
                },
                "fiscal_document": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "FR of the charge, or its current FT.",
                    "nullable": true
                },
                "receipt": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "RG issued after payment of an FT charge.",
                    "nullable": true
                },
                "documents": {
                    "type": "array",
                    "description": "Every document of the charge: FT or FR, the receipts (RG) that settled it and the credit notes (NC) that rectified them. A rejected document already replaced by a correction is left out.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "type": {
                                "type": "string",
                                "enum": [
                                    "FT",
                                    "FR",
                                    "RG",
                                    "NC"
                                ]
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "status": {
                                "type": "string"
                            },
                            "simulated": {
                                "type": "boolean"
                            }
                        }
                    }
                },
                "items": {
                    "type": "array",
                    "description": "Only in GET /payments/{payment}. The lines of the invoice (FT or FR) the charge pays for, as issued.",
                    "items": {
                        "type": "object"
                    }
                },
                "method_reference": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "external_id",
                "environment",
                "amount_minor",
                "currency",
                "status",
                "method",
                "method_reference",
                "provider",
                "simulated",
                "reference",
                "expires_at",
                "paid_at",
                "created_at",
                "metadata",
                "document_type",
                "invoice_requested",
                "fiscal_document",
                "receipt"
            ],
            "$ref": "#/components/schemas/Payment"
        }
    },
    "required": [
        "data"
    ]
}

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "external_id": {
                    "type": "string"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "amount_minor": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 1,
                    "maximum": 9999999999
                },
                "currency": {
                    "type": "string",
                    "enum": [
                        "AOA"
                    ]
                },
                "description": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "awaiting_invoice",
                        "invoice_rejected",
                        "creating",
                        "pending",
                        "expired",
                        "paid",
                        "cancelled"
                    ],
                    "description": "awaiting_invoice: FT sent to AGT, no reference yet. invoice_rejected: AGT rejected the FT; correct it with PUT /payments/{payment}/invoice."
                },
                "method": {
                    "type": "string",
                    "enum": [
                        "reference",
                        "cash",
                        "bank_transfer",
                        "card",
                        "other"
                    ],
                    "description": "reference for a ProxyPay charge; any other value for a payment recorded by the merchant."
                },
                "provider": {
                    "type": "string",
                    "enum": [
                        "mock",
                        "proxypay"
                    ],
                    "nullable": true,
                    "description": "null for a payment recorded by the merchant."
                },
                "simulated": {
                    "type": "boolean"
                },
                "reference": {
                    "type": "object",
                    "properties": {
                        "entity": {
                            "type": "string"
                        },
                        "number": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "entity",
                        "number"
                    ],
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "paid_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "metadata": {
                    "type": "object"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT"
                    ],
                    "nullable": true
                },
                "invoice_requested": {
                    "type": "boolean"
                },
                "fiscal_document": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "FR of the charge, or its current FT.",
                    "nullable": true
                },
                "receipt": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "RG issued after payment of an FT charge.",
                    "nullable": true
                },
                "documents": {
                    "type": "array",
                    "description": "Every document of the charge: FT or FR, the receipts (RG) that settled it and the credit notes (NC) that rectified them. A rejected document already replaced by a correction is left out.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "type": {
                                "type": "string",
                                "enum": [
                                    "FT",
                                    "FR",
                                    "RG",
                                    "NC"
                                ]
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "status": {
                                "type": "string"
                            },
                            "simulated": {
                                "type": "boolean"
                            }
                        }
                    }
                },
                "items": {
                    "type": "array",
                    "description": "Only in GET /payments/{payment}. The lines of the invoice (FT or FR) the charge pays for, as issued.",
                    "items": {
                        "type": "object"
                    }
                },
                "method_reference": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "external_id",
                "environment",
                "amount_minor",
                "currency",
                "status",
                "method",
                "method_reference",
                "provider",
                "simulated",
                "reference",
                "expires_at",
                "paid_at",
                "created_at",
                "metadata",
                "document_type",
                "invoice_requested",
                "fiscal_document",
                "receipt"
            ],
            "$ref": "#/components/schemas/Payment"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/payments

List project payments in the credential environment.

Bearer do projecto · payments:read

Parâmetros

Nome	Local / tipo	Regra
`page`	query · integer	Opcional. Pages of 50 records.
`external_id`	query · string	Opcional.
`merchant_id`	query · string	Opcional.
`status`	query · string	Opcional. `pending \| paid \| expired \| cancelled \| creating \| awaiting_invoice \| invoice_rejected \| review_required`
`method`	query · string	Opcional. `reference \| cash \| bank_transfer \| card \| other`
`search`	query · string	Opcional. external_id, description, reference, payment reference text or the number of the charge document.
`from`	query · string	Opcional. First day of creation, Luanda time.
`to`	query · string	Opcional. Last day of creation, Luanda time.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "merchant_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "external_id": {
                        "type": "string"
                    },
                    "environment": {
                        "type": "string",
                        "enum": [
                            "sandbox",
                            "live"
                        ]
                    },
                    "amount_minor": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 1,
                        "maximum": 9999999999
                    },
                    "currency": {
                        "type": "string",
                        "enum": [
                            "AOA"
                        ]
                    },
                    "description": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "awaiting_invoice",
                            "invoice_rejected",
                            "creating",
                            "pending",
                            "expired",
                            "paid",
                            "cancelled"
                        ],
                        "description": "awaiting_invoice: FT sent to AGT, no reference yet. invoice_rejected: AGT rejected the FT; correct it with PUT /payments/{payment}/invoice."
                    },
                    "method": {
                        "type": "string",
                        "enum": [
                            "reference",
                            "cash",
                            "bank_transfer",
                            "card",
                            "other"
                        ],
                        "description": "reference for a ProxyPay charge; any other value for a payment recorded by the merchant."
                    },
                    "provider": {
                        "type": "string",
                        "enum": [
                            "mock",
                            "proxypay"
                        ],
                        "nullable": true,
                        "description": "null for a payment recorded by the merchant."
                    },
                    "simulated": {
                        "type": "boolean"
                    },
                    "reference": {
                        "type": "object",
                        "properties": {
                            "entity": {
                                "type": "string"
                            },
                            "number": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "entity",
                            "number"
                        ],
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "paid_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "metadata": {
                        "type": "object"
                    },
                    "document_type": {
                        "type": "string",
                        "enum": [
                            "FR",
                            "FT"
                        ],
                        "nullable": true
                    },
                    "invoice_requested": {
                        "type": "boolean"
                    },
                    "fiscal_document": {
                        "allOf": [
                            {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "FR",
                                            "FT",
                                            "RG"
                                        ]
                                    },
                                    "status": {
                                        "type": "string"
                                    },
                                    "number": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "simulated": {
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "id",
                                    "type",
                                    "status",
                                    "number",
                                    "simulated"
                                ],
                                "$ref": "#/components/schemas/DocumentSummary"
                            }
                        ],
                        "description": "FR of the charge, or its current FT.",
                        "nullable": true
                    },
                    "receipt": {
                        "allOf": [
                            {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "FR",
                                            "FT",
                                            "RG"
                                        ]
                                    },
                                    "status": {
                                        "type": "string"
                                    },
                                    "number": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "simulated": {
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "id",
                                    "type",
                                    "status",
                                    "number",
                                    "simulated"
                                ],
                                "$ref": "#/components/schemas/DocumentSummary"
                            }
                        ],
                        "description": "RG issued after payment of an FT charge.",
                        "nullable": true
                    },
                    "documents": {
                        "type": "array",
                        "description": "Every document of the charge: FT or FR, the receipts (RG) that settled it and the credit notes (NC) that rectified them. A rejected document already replaced by a correction is left out.",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FT",
                                        "FR",
                                        "RG",
                                        "NC"
                                    ]
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "status": {
                                    "type": "string"
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            }
                        }
                    },
                    "items": {
                        "type": "array",
                        "description": "Only in GET /payments/{payment}. The lines of the invoice (FT or FR) the charge pays for, as issued.",
                        "items": {
                            "type": "object"
                        }
                    },
                    "method_reference": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "required": [
                    "id",
                    "merchant_id",
                    "external_id",
                    "environment",
                    "amount_minor",
                    "currency",
                    "status",
                    "method",
                    "method_reference",
                    "provider",
                    "simulated",
                    "reference",
                    "expires_at",
                    "paid_at",
                    "created_at",
                    "metadata",
                    "document_type",
                    "invoice_requested",
                    "fiscal_document",
                    "receipt"
                ],
                "$ref": "#/components/schemas/Payment"
            }
        },
        "meta": {
            "type": "object",
            "properties": {
                "current_page": {
                    "type": "integer",
                    "format": "int64"
                },
                "last_page": {
                    "type": "integer",
                    "format": "int64"
                },
                "total": {
                    "type": "integer",
                    "format": "int64"
                }
            },
            "required": [
                "current_page",
                "last_page",
                "total"
            ],
            "$ref": "#/components/schemas/Meta"
        }
    },
    "required": [
        "data",
        "meta"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/payments/{payment}

Read payment, including late confirmations.

Bearer do projecto · payments:read

Parâmetros

Nome	Local / tipo	Regra
`payment`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "external_id": {
                    "type": "string"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "amount_minor": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 1,
                    "maximum": 9999999999
                },
                "currency": {
                    "type": "string",
                    "enum": [
                        "AOA"
                    ]
                },
                "description": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "awaiting_invoice",
                        "invoice_rejected",
                        "creating",
                        "pending",
                        "expired",
                        "paid",
                        "cancelled"
                    ],
                    "description": "awaiting_invoice: FT sent to AGT, no reference yet. invoice_rejected: AGT rejected the FT; correct it with PUT /payments/{payment}/invoice."
                },
                "method": {
                    "type": "string",
                    "enum": [
                        "reference",
                        "cash",
                        "bank_transfer",
                        "card",
                        "other"
                    ],
                    "description": "reference for a ProxyPay charge; any other value for a payment recorded by the merchant."
                },
                "provider": {
                    "type": "string",
                    "enum": [
                        "mock",
                        "proxypay"
                    ],
                    "nullable": true,
                    "description": "null for a payment recorded by the merchant."
                },
                "simulated": {
                    "type": "boolean"
                },
                "reference": {
                    "type": "object",
                    "properties": {
                        "entity": {
                            "type": "string"
                        },
                        "number": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "entity",
                        "number"
                    ],
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "paid_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "metadata": {
                    "type": "object"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT"
                    ],
                    "nullable": true
                },
                "invoice_requested": {
                    "type": "boolean"
                },
                "fiscal_document": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "FR of the charge, or its current FT.",
                    "nullable": true
                },
                "receipt": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "RG issued after payment of an FT charge.",
                    "nullable": true
                },
                "documents": {
                    "type": "array",
                    "description": "Every document of the charge: FT or FR, the receipts (RG) that settled it and the credit notes (NC) that rectified them. A rejected document already replaced by a correction is left out.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "type": {
                                "type": "string",
                                "enum": [
                                    "FT",
                                    "FR",
                                    "RG",
                                    "NC"
                                ]
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "status": {
                                "type": "string"
                            },
                            "simulated": {
                                "type": "boolean"
                            }
                        }
                    }
                },
                "items": {
                    "type": "array",
                    "description": "Only in GET /payments/{payment}. The lines of the invoice (FT or FR) the charge pays for, as issued.",
                    "items": {
                        "type": "object"
                    }
                },
                "method_reference": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "external_id",
                "environment",
                "amount_minor",
                "currency",
                "status",
                "method",
                "method_reference",
                "provider",
                "simulated",
                "reference",
                "expires_at",
                "paid_at",
                "created_at",
                "metadata",
                "document_type",
                "invoice_requested",
                "fiscal_document",
                "receipt"
            ],
            "$ref": "#/components/schemas/Payment"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/payments/{payment}/simulate

Local/testing mock sandbox only; disabled in production.

Bearer do projecto · payments:write

Parâmetros

Nome	Local / tipo	Regra
`payment`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "external_id": {
                    "type": "string"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "amount_minor": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 1,
                    "maximum": 9999999999
                },
                "currency": {
                    "type": "string",
                    "enum": [
                        "AOA"
                    ]
                },
                "description": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "awaiting_invoice",
                        "invoice_rejected",
                        "creating",
                        "pending",
                        "expired",
                        "paid",
                        "cancelled"
                    ],
                    "description": "awaiting_invoice: FT sent to AGT, no reference yet. invoice_rejected: AGT rejected the FT; correct it with PUT /payments/{payment}/invoice."
                },
                "method": {
                    "type": "string",
                    "enum": [
                        "reference",
                        "cash",
                        "bank_transfer",
                        "card",
                        "other"
                    ],
                    "description": "reference for a ProxyPay charge; any other value for a payment recorded by the merchant."
                },
                "provider": {
                    "type": "string",
                    "enum": [
                        "mock",
                        "proxypay"
                    ],
                    "nullable": true,
                    "description": "null for a payment recorded by the merchant."
                },
                "simulated": {
                    "type": "boolean"
                },
                "reference": {
                    "type": "object",
                    "properties": {
                        "entity": {
                            "type": "string"
                        },
                        "number": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "entity",
                        "number"
                    ],
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "paid_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "metadata": {
                    "type": "object"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT"
                    ],
                    "nullable": true
                },
                "invoice_requested": {
                    "type": "boolean"
                },
                "fiscal_document": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "FR of the charge, or its current FT.",
                    "nullable": true
                },
                "receipt": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "RG issued after payment of an FT charge.",
                    "nullable": true
                },
                "documents": {
                    "type": "array",
                    "description": "Every document of the charge: FT or FR, the receipts (RG) that settled it and the credit notes (NC) that rectified them. A rejected document already replaced by a correction is left out.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "type": {
                                "type": "string",
                                "enum": [
                                    "FT",
                                    "FR",
                                    "RG",
                                    "NC"
                                ]
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "status": {
                                "type": "string"
                            },
                            "simulated": {
                                "type": "boolean"
                            }
                        }
                    }
                },
                "items": {
                    "type": "array",
                    "description": "Only in GET /payments/{payment}. The lines of the invoice (FT or FR) the charge pays for, as issued.",
                    "items": {
                        "type": "object"
                    }
                },
                "method_reference": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "external_id",
                "environment",
                "amount_minor",
                "currency",
                "status",
                "method",
                "method_reference",
                "provider",
                "simulated",
                "reference",
                "expires_at",
                "paid_at",
                "created_at",
                "metadata",
                "document_type",
                "invoice_requested",
                "fiscal_document",
                "receipt"
            ],
            "$ref": "#/components/schemas/Payment"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/payments/{payment}/cancellation

Read cancellation separately from the bank payment fact.

Bearer do projecto · payments:read

Parâmetros

Nome	Local / tipo	Regra
`payment`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "payment_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "requested",
                        "sending",
                        "unknown",
                        "cancelled",
                        "failed",
                        "paid"
                    ]
                },
                "attempts": {
                    "type": "integer",
                    "format": "int64"
                },
                "retries": {
                    "type": "integer",
                    "format": "int64"
                },
                "result_code": {
                    "type": "string",
                    "nullable": true
                },
                "completed_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "payment_id",
                "status"
            ],
            "$ref": "#/components/schemas/Cancellation"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/payments/{payment}/cancellation

Queue cancellation. This operation is not a refund.

Bearer do projecto · payments:write

Parâmetros

Nome	Local / tipo	Regra
`payment`	path · string	Obrigatório.
`Idempotency-Key`	header · string	Obrigatório. Reuse the same key and body on retries. Scope is project and environment.

Corpo JSON

Campo	Tipo	Obrigatório
`reason`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 500
        }
    },
    "required": [
        "reason"
    ],
    "$ref": "#/components/schemas/Reason"
}

Respostas

202 401 403 404 409 422 423 429 502

202 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "payment_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "requested",
                        "sending",
                        "unknown",
                        "cancelled",
                        "failed",
                        "paid"
                    ]
                },
                "attempts": {
                    "type": "integer",
                    "format": "int64"
                },
                "retries": {
                    "type": "integer",
                    "format": "int64"
                },
                "result_code": {
                    "type": "string",
                    "nullable": true
                },
                "completed_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "payment_id",
                "status"
            ],
            "$ref": "#/components/schemas/Cancellation"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/payments/{payment}/cancellation/retry

Audit a retry of an uncertain cancellation; maximum three retries.

Bearer do projecto · payments:write

Parâmetros

Nome	Local / tipo	Regra
`payment`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`reason`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 500
        }
    },
    "required": [
        "reason"
    ],
    "$ref": "#/components/schemas/Reason"
}

Respostas

202 401 403 404 409 422 423 429 502

202 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "payment_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "requested",
                        "sending",
                        "unknown",
                        "cancelled",
                        "failed",
                        "paid"
                    ]
                },
                "attempts": {
                    "type": "integer",
                    "format": "int64"
                },
                "retries": {
                    "type": "integer",
                    "format": "int64"
                },
                "result_code": {
                    "type": "string",
                    "nullable": true
                },
                "completed_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "payment_id",
                "status"
            ],
            "$ref": "#/components/schemas/Cancellation"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

PUT/payments/{payment}/invoice

Correct the rejected FT of a charge (status invoice_rejected): a correction FT is sent to AGT and the reference follows its validation. Or correct the rejected FR of a paid charge: a new FR linked to the rejected one is issued and the charge stays paid. Or request an FR for a paid charge created without document; an FT is never issued after payment. Repeating the same data is harmless.

Bearer do projecto · payments:write

Parâmetros

Nome	Local / tipo	Regra
`payment`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`invoice_data`	object	Não

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "invoice_data": {
            "allOf": [
                {
                    "type": "object",
                    "properties": {
                        "customer": {
                            "type": "object",
                            "properties": {
                                "tax_id": {
                                    "type": "string",
                                    "pattern": "^[A-Z0-9]{9,15}$"
                                },
                                "name": {
                                    "type": "string",
                                    "maxLength": 160
                                },
                                "address": {
                                    "type": "string",
                                    "maxLength": 500
                                },
                                "country": {
                                    "type": "string",
                                    "enum": [
                                        "AO"
                                    ]
                                }
                            },
                            "required": [
                                "tax_id",
                                "name",
                                "address",
                                "country"
                            ],
                            "$ref": "#/components/schemas/Customer"
                        },
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "format": "int64",
                                        "minimum": 1,
                                        "maximum": 100000
                                    },
                                    "unit_amount_minor": {
                                        "type": "integer",
                                        "format": "int64",
                                        "minimum": 0,
                                        "maximum": 9999999999
                                    },
                                    "vat_rate": {
                                        "type": "integer",
                                        "format": "int64",
                                        "enum": [
                                            14,
                                            7,
                                            5,
                                            1,
                                            0
                                        ],
                                        "description": "Angolan VAT rate."
                                    },
                                    "tax_code": {
                                        "type": "string",
                                        "enum": [
                                            "NOR",
                                            "RED",
                                            "ISE"
                                        ],
                                        "description": "Optional. Derived from vat_rate (0 ISE, 14 NOR, 7/5/1 RED); when sent it must match."
                                    },
                                    "operation_type": {
                                        "type": "string",
                                        "enum": [
                                            "SE",
                                            "SS",
                                            "STP",
                                            "SR",
                                            "SIF",
                                            "SHS",
                                            "ST",
                                            "SG",
                                            "TB",
                                            "AS",
                                            "QT",
                                            "RD"
                                        ]
                                    },
                                    "exemption_code": {
                                        "type": "string",
                                        "pattern": "^M[0-9]{2}$",
                                        "description": "Required for 0% and forbidden otherwise: an active code from GET /fiscal/exemption-reasons.",
                                        "nullable": true
                                    },
                                    "cnbs_code": {
                                        "type": "string",
                                        "pattern": "^[0-9]{8}$",
                                        "description": "CNBS code (INE classification of goods and services) from GET /fiscal/cnbs-codes, sent to the AGT as productCode instead of code. Optional until fiscal.cnbs_required_from (2027-01-01); from that date every FT and FR line must carry an active code.",
                                        "nullable": true
                                    }
                                },
                                "required": [
                                    "code",
                                    "description",
                                    "quantity",
                                    "unit_amount_minor",
                                    "vat_rate",
                                    "operation_type"
                                ],
                                "$ref": "#/components/schemas/InvoiceItem"
                            },
                            "minItems": 1,
                            "maxItems": 100
                        },
                        "payment_method": {
                            "type": "string",
                            "enum": [
                                "reference"
                            ]
                        }
                    },
                    "required": [
                        "customer",
                        "items",
                        "payment_method"
                    ],
                    "$ref": "#/components/schemas/InvoiceRequest"
                }
            ],
            "description": "Corrected customer and items (same total). Optional for a paid charge with order_data, which is then reused."
        }
    },
    "$ref": "#/components/schemas/PaymentInvoice"
}

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "external_id": {
                    "type": "string"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "amount_minor": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 1,
                    "maximum": 9999999999
                },
                "currency": {
                    "type": "string",
                    "enum": [
                        "AOA"
                    ]
                },
                "description": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "awaiting_invoice",
                        "invoice_rejected",
                        "creating",
                        "pending",
                        "expired",
                        "paid",
                        "cancelled"
                    ],
                    "description": "awaiting_invoice: FT sent to AGT, no reference yet. invoice_rejected: AGT rejected the FT; correct it with PUT /payments/{payment}/invoice."
                },
                "method": {
                    "type": "string",
                    "enum": [
                        "reference",
                        "cash",
                        "bank_transfer",
                        "card",
                        "other"
                    ],
                    "description": "reference for a ProxyPay charge; any other value for a payment recorded by the merchant."
                },
                "provider": {
                    "type": "string",
                    "enum": [
                        "mock",
                        "proxypay"
                    ],
                    "nullable": true,
                    "description": "null for a payment recorded by the merchant."
                },
                "simulated": {
                    "type": "boolean"
                },
                "reference": {
                    "type": "object",
                    "properties": {
                        "entity": {
                            "type": "string"
                        },
                        "number": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "entity",
                        "number"
                    ],
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "paid_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "metadata": {
                    "type": "object"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT"
                    ],
                    "nullable": true
                },
                "invoice_requested": {
                    "type": "boolean"
                },
                "fiscal_document": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "FR of the charge, or its current FT.",
                    "nullable": true
                },
                "receipt": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "RG issued after payment of an FT charge.",
                    "nullable": true
                },
                "documents": {
                    "type": "array",
                    "description": "Every document of the charge: FT or FR, the receipts (RG) that settled it and the credit notes (NC) that rectified them. A rejected document already replaced by a correction is left out.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "type": {
                                "type": "string",
                                "enum": [
                                    "FT",
                                    "FR",
                                    "RG",
                                    "NC"
                                ]
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "status": {
                                "type": "string"
                            },
                            "simulated": {
                                "type": "boolean"
                            }
                        }
                    }
                },
                "items": {
                    "type": "array",
                    "description": "Only in GET /payments/{payment}. The lines of the invoice (FT or FR) the charge pays for, as issued.",
                    "items": {
                        "type": "object"
                    }
                },
                "method_reference": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "external_id",
                "environment",
                "amount_minor",
                "currency",
                "status",
                "method",
                "method_reference",
                "provider",
                "simulated",
                "reference",
                "expires_at",
                "paid_at",
                "created_at",
                "metadata",
                "document_type",
                "invoice_requested",
                "fiscal_document",
                "receipt"
            ],
            "$ref": "#/components/schemas/Payment"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/payments/{payment}/renewal

Renew an expired, unpaid charge: the same reference is registered again with a new validity. An FT charge that expired before its reference only gets the new validity and returns to awaiting_invoice. Repeating the same validity is harmless.

Bearer do projecto · payments:write

Parâmetros

Nome	Local / tipo	Regra
`payment`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`expires_at`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "New validity with seconds and offset, future and at most 90 days ahead. Amount, customer and items never change."
        }
    },
    "required": [
        "expires_at"
    ],
    "$ref": "#/components/schemas/Renewal"
}

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "external_id": {
                    "type": "string"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "amount_minor": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 1,
                    "maximum": 9999999999
                },
                "currency": {
                    "type": "string",
                    "enum": [
                        "AOA"
                    ]
                },
                "description": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "awaiting_invoice",
                        "invoice_rejected",
                        "creating",
                        "pending",
                        "expired",
                        "paid",
                        "cancelled"
                    ],
                    "description": "awaiting_invoice: FT sent to AGT, no reference yet. invoice_rejected: AGT rejected the FT; correct it with PUT /payments/{payment}/invoice."
                },
                "method": {
                    "type": "string",
                    "enum": [
                        "reference",
                        "cash",
                        "bank_transfer",
                        "card",
                        "other"
                    ],
                    "description": "reference for a ProxyPay charge; any other value for a payment recorded by the merchant."
                },
                "provider": {
                    "type": "string",
                    "enum": [
                        "mock",
                        "proxypay"
                    ],
                    "nullable": true,
                    "description": "null for a payment recorded by the merchant."
                },
                "simulated": {
                    "type": "boolean"
                },
                "reference": {
                    "type": "object",
                    "properties": {
                        "entity": {
                            "type": "string"
                        },
                        "number": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "entity",
                        "number"
                    ],
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "paid_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "metadata": {
                    "type": "object"
                },
                "document_type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT"
                    ],
                    "nullable": true
                },
                "invoice_requested": {
                    "type": "boolean"
                },
                "fiscal_document": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "FR of the charge, or its current FT.",
                    "nullable": true
                },
                "receipt": {
                    "allOf": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "type": {
                                    "type": "string",
                                    "enum": [
                                        "FR",
                                        "FT",
                                        "RG"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "simulated": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "id",
                                "type",
                                "status",
                                "number",
                                "simulated"
                            ],
                            "$ref": "#/components/schemas/DocumentSummary"
                        }
                    ],
                    "description": "RG issued after payment of an FT charge.",
                    "nullable": true
                },
                "documents": {
                    "type": "array",
                    "description": "Every document of the charge: FT or FR, the receipts (RG) that settled it and the credit notes (NC) that rectified them. A rejected document already replaced by a correction is left out.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "type": {
                                "type": "string",
                                "enum": [
                                    "FT",
                                    "FR",
                                    "RG",
                                    "NC"
                                ]
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "status": {
                                "type": "string"
                            },
                            "simulated": {
                                "type": "boolean"
                            }
                        }
                    }
                },
                "items": {
                    "type": "array",
                    "description": "Only in GET /payments/{payment}. The lines of the invoice (FT or FR) the charge pays for, as issued.",
                    "items": {
                        "type": "object"
                    }
                },
                "method_reference": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "external_id",
                "environment",
                "amount_minor",
                "currency",
                "status",
                "method",
                "method_reference",
                "provider",
                "simulated",
                "reference",
                "expires_at",
                "paid_at",
                "created_at",
                "metadata",
                "document_type",
                "invoice_requested",
                "fiscal_document",
                "receipt"
            ],
            "$ref": "#/components/schemas/Payment"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

Documentos fiscais

GET/documents

List fiscal documents, including documents without a payment.

Bearer do projecto · documents:read

Parâmetros

Nome	Local / tipo	Regra
`page`	query · integer	Opcional. Pages of 50 records.
`merchant_id`	query · string	Opcional.
`payment_id`	query · string	Opcional.
`status`	query · string	Opcional. `queued \| blocked \| submitting \| submitted \| checking \| unknown \| valid \| rejected \| simulated`
`type`	query · string	Opcional. `FT \| FR \| RG \| NC`
`search`	query · string	Opcional. Document number, customer name or NIF, or the charge external_id or reference.
`from`	query · string	Opcional. First day, Luanda time.
`to`	query · string	Opcional. Last day, Luanda time.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "payment_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "merchant_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "environment": {
                        "type": "string",
                        "enum": [
                            "sandbox",
                            "live"
                        ]
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "FR",
                            "FT",
                            "NC",
                            "RG"
                        ]
                    },
                    "number": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "queued",
                            "blocked",
                            "submitting",
                            "submitted",
                            "checking",
                            "unknown",
                            "valid",
                            "rejected",
                            "simulated"
                        ]
                    },
                    "simulated": {
                        "type": "boolean"
                    },
                    "fiscal_valid": {
                        "type": "boolean"
                    },
                    "snapshot": {
                        "type": "object",
                        "properties": {
                            "customer": {
                                "type": "object",
                                "properties": {
                                    "tax_id": {
                                        "type": "string",
                                        "pattern": "^[A-Z0-9]{9,15}$"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 160
                                    },
                                    "address": {
                                        "type": "string",
                                        "maxLength": 500
                                    },
                                    "country": {
                                        "type": "string",
                                        "enum": [
                                            "AO"
                                        ]
                                    }
                                },
                                "required": [
                                    "tax_id",
                                    "name",
                                    "address",
                                    "country"
                                ],
                                "$ref": "#/components/schemas/Customer"
                            },
                            "items": {
                                "type": "array",
                                "items": {
                                    "type": "object"
                                }
                            },
                            "totals": {
                                "type": "object",
                                "properties": {
                                    "net_minor": {
                                        "type": "integer",
                                        "format": "int64"
                                    },
                                    "tax_minor": {
                                        "type": "integer",
                                        "format": "int64"
                                    },
                                    "gross_minor": {
                                        "type": "integer",
                                        "format": "int64"
                                    }
                                },
                                "required": [
                                    "net_minor",
                                    "tax_minor",
                                    "gross_minor"
                                ]
                            }
                        }
                    },
                    "issued_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "validated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_error_code": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "original_document_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "corrects_document_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "due_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "calculation_version": {
                        "type": "string",
                        "nullable": true
                    },
                    "pdf_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "settlements": {
                        "type": "array",
                        "description": "The receipts (RG) that settled an FT (relation settled_by) or the FT an RG settles (relation settles), with the amount of each.",
                        "items": {
                            "type": "object",
                            "properties": {
                                "relation": {
                                    "type": "string",
                                    "enum": [
                                        "settles",
                                        "settled_by"
                                    ]
                                },
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "type": {
                                    "type": "string"
                                },
                                "amount_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                }
                            }
                        }
                    },
                    "linked": {
                        "type": "object",
                        "description": "Listing only. The document this one is tied to by a rectification: a credit note points to the document it rectifies, a rectified FT/FR to its credit note.",
                        "properties": {
                            "relation": {
                                "type": "string",
                                "enum": [
                                    "rectifies",
                                    "rectified_by"
                                ]
                            },
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "type": {
                                "type": "string"
                            }
                        },
                        "nullable": true
                    },
                    "payment": {
                        "type": "object",
                        "description": "The charge the document belongs to; for an FT or RG settled by allocation, the charge that paid it.",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "external_id": {
                                "type": "string",
                                "nullable": true
                            },
                            "reference": {
                                "type": "string",
                                "nullable": true
                            },
                            "method": {
                                "type": "string"
                            },
                            "amount_minor": {
                                "type": "integer",
                                "format": "int64"
                            },
                            "currency": {
                                "type": "string"
                            }
                        },
                        "nullable": true
                    },
                    "last_error_message": {
                        "type": "string",
                        "nullable": true,
                        "description": "The AGT explanation for last_error_code, when the AGT gave one."
                    },
                    "rectification": {
                        "type": "object",
                        "description": "Only in GET /documents/{document}. Whether the document can be rectified with a full NC, and the NC that rectified it.",
                        "properties": {
                            "allowed": {
                                "type": "boolean"
                            },
                            "blocked_reason": {
                                "type": "string",
                                "nullable": true,
                                "description": "Why an FT or FR cannot be rectified, for example an FT already settled by a receipt (RG)."
                            },
                            "credit_note": {
                                "type": "object",
                                "nullable": true,
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "number": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "status": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "required": [
                    "id",
                    "payment_id",
                    "merchant_id",
                    "environment",
                    "type",
                    "status",
                    "simulated",
                    "fiscal_valid",
                    "snapshot"
                ],
                "$ref": "#/components/schemas/FiscalDocument"
            }
        },
        "meta": {
            "type": "object",
            "properties": {
                "current_page": {
                    "type": "integer",
                    "format": "int64"
                },
                "last_page": {
                    "type": "integer",
                    "format": "int64"
                },
                "total": {
                    "type": "integer",
                    "format": "int64"
                }
            },
            "required": [
                "current_page",
                "last_page",
                "total"
            ],
            "$ref": "#/components/schemas/Meta"
        }
    },
    "required": [
        "data",
        "meta"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/documents/{document}

Read an immutable fiscal document and processing status.

Bearer do projecto · documents:read

Parâmetros

Nome	Local / tipo	Regra
`document`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "payment_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT",
                        "NC",
                        "RG"
                    ]
                },
                "number": {
                    "type": "string",
                    "nullable": true
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "queued",
                        "blocked",
                        "submitting",
                        "submitted",
                        "checking",
                        "unknown",
                        "valid",
                        "rejected",
                        "simulated"
                    ]
                },
                "simulated": {
                    "type": "boolean"
                },
                "fiscal_valid": {
                    "type": "boolean"
                },
                "snapshot": {
                    "type": "object",
                    "properties": {
                        "customer": {
                            "type": "object",
                            "properties": {
                                "tax_id": {
                                    "type": "string",
                                    "pattern": "^[A-Z0-9]{9,15}$"
                                },
                                "name": {
                                    "type": "string",
                                    "maxLength": 160
                                },
                                "address": {
                                    "type": "string",
                                    "maxLength": 500
                                },
                                "country": {
                                    "type": "string",
                                    "enum": [
                                        "AO"
                                    ]
                                }
                            },
                            "required": [
                                "tax_id",
                                "name",
                                "address",
                                "country"
                            ],
                            "$ref": "#/components/schemas/Customer"
                        },
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object"
                            }
                        },
                        "totals": {
                            "type": "object",
                            "properties": {
                                "net_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "tax_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "gross_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                }
                            },
                            "required": [
                                "net_minor",
                                "tax_minor",
                                "gross_minor"
                            ]
                        }
                    }
                },
                "issued_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "validated_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "last_error_code": {
                    "type": "string",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "original_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "corrects_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "due_date": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                },
                "calculation_version": {
                    "type": "string",
                    "nullable": true
                },
                "pdf_url": {
                    "type": "string",
                    "nullable": true
                },
                "settlements": {
                    "type": "array",
                    "description": "The receipts (RG) that settled an FT (relation settled_by) or the FT an RG settles (relation settles), with the amount of each.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "relation": {
                                "type": "string",
                                "enum": [
                                    "settles",
                                    "settled_by"
                                ]
                            },
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "type": {
                                "type": "string"
                            },
                            "amount_minor": {
                                "type": "integer",
                                "format": "int64"
                            }
                        }
                    }
                },
                "linked": {
                    "type": "object",
                    "description": "Listing only. The document this one is tied to by a rectification: a credit note points to the document it rectifies, a rectified FT/FR to its credit note.",
                    "properties": {
                        "relation": {
                            "type": "string",
                            "enum": [
                                "rectifies",
                                "rectified_by"
                            ]
                        },
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "number": {
                            "type": "string",
                            "nullable": true
                        },
                        "type": {
                            "type": "string"
                        }
                    },
                    "nullable": true
                },
                "payment": {
                    "type": "object",
                    "description": "The charge the document belongs to; for an FT or RG settled by allocation, the charge that paid it.",
                    "properties": {
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "external_id": {
                            "type": "string",
                            "nullable": true
                        },
                        "reference": {
                            "type": "string",
                            "nullable": true
                        },
                        "method": {
                            "type": "string"
                        },
                        "amount_minor": {
                            "type": "integer",
                            "format": "int64"
                        },
                        "currency": {
                            "type": "string"
                        }
                    },
                    "nullable": true
                },
                "last_error_message": {
                    "type": "string",
                    "nullable": true,
                    "description": "The AGT explanation for last_error_code, when the AGT gave one."
                },
                "rectification": {
                    "type": "object",
                    "description": "Only in GET /documents/{document}. Whether the document can be rectified with a full NC, and the NC that rectified it.",
                    "properties": {
                        "allowed": {
                            "type": "boolean"
                        },
                        "blocked_reason": {
                            "type": "string",
                            "nullable": true,
                            "description": "Why an FT or FR cannot be rectified, for example an FT already settled by a receipt (RG)."
                        },
                        "credit_note": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "status": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "required": [
                "id",
                "payment_id",
                "merchant_id",
                "environment",
                "type",
                "status",
                "simulated",
                "fiscal_valid",
                "snapshot"
            ],
            "$ref": "#/components/schemas/FiscalDocument"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/documents/{document}/pdf

Download a valid or simulated PDF. Simulation is visibly marked.

Bearer do projecto · documents:read

Parâmetros

Nome	Local / tipo	Regra
`document`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/pdf

{
    "type": "string",
    "format": "binary"
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/documents/{document}/balance

Read net outstanding balance, credits and payment allocations.

Bearer do projecto · documents:read

Parâmetros

Nome	Local / tipo	Regra
`document`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object"
        },
        "allocations": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "payment_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "fiscal_document_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "receipt_document_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "amount_minor": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 1,
                        "maximum": 9999999999
                    }
                },
                "required": [
                    "id",
                    "payment_id",
                    "fiscal_document_id",
                    "amount_minor"
                ],
                "$ref": "#/components/schemas/Allocation"
            }
        }
    },
    "required": [
        "data",
        "allocations"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/documents/{document}/allocations

Allocate confirmed funds to FT and create a linked receipt. No extra commercial usage.

Bearer do projecto · documents:write

Parâmetros

Nome	Local / tipo	Regra
`document`	path · string	Obrigatório.
`Idempotency-Key`	header · string	Obrigatório. Reuse the same key and body on retries. Scope is project and environment.

Corpo JSON

Campo	Tipo	Obrigatório
`payment_id`	string	Sim
`amount_minor`	integer	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "payment_id": {
            "type": "string",
            "format": "uuid"
        },
        "amount_minor": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "maximum": 9999999999
        }
    },
    "required": [
        "payment_id",
        "amount_minor"
    ],
    "$ref": "#/components/schemas/AllocationInput"
}

Respostas

201 401 403 404 409 422 423 429 502

201 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "payment_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "fiscal_document_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "receipt_document_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "amount_minor": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 1,
                    "maximum": 9999999999
                }
            },
            "required": [
                "id",
                "payment_id",
                "fiscal_document_id",
                "amount_minor"
            ],
            "$ref": "#/components/schemas/Allocation"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/documents/{document}/payment-links

List payment intentions linked to an invoice.

Bearer do projecto · documents:read

Parâmetros

Nome	Local / tipo	Regra
`document`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object"
            }
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/documents/{document}/payment-links

Link a reference payment to FT; fiscal worker allocates after confirmation and creates RG.

Bearer do projecto · documents:write

Parâmetros

Nome	Local / tipo	Regra
`document`	path · string	Obrigatório.
`Idempotency-Key`	header · string	Obrigatório. Reuse the same key and body on retries. Scope is project and environment.

Corpo JSON

Campo	Tipo	Obrigatório
`payment_id`	string	Sim
`amount_minor`	integer	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "payment_id": {
            "type": "string",
            "format": "uuid"
        },
        "amount_minor": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "maximum": 9999999999
        }
    },
    "required": [
        "payment_id",
        "amount_minor"
    ],
    "$ref": "#/components/schemas/AllocationInput"
}

Respostas

201 401 403 404 409 422 423 429 502

201 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/documents/{document}/payment-links/{link}/retry

Audit a new attempt to allocate a paid intention requiring review.

Bearer do projecto · documents:write

Parâmetros

Nome	Local / tipo	Regra
`document`	path · string	Obrigatório.
`link`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`reason`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 500
        }
    },
    "required": [
        "reason"
    ],
    "$ref": "#/components/schemas/Reason"
}

Respostas

202 401 403 404 409 422 423 429 502

202 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/documents/{document}/rectification

Rectify a validated FT or FR with a credit note (NC) of the whole document. Repeating it returns the same NC (200).

Bearer do projecto · documents:write

Parâmetros

Nome	Local / tipo	Regra
`document`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`reason`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "required": [
        "reason"
    ],
    "properties": {
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 60,
            "description": "Reason sent to the AGT in the credit note (referenceInfo.reason)."
        }
    },
    "$ref": "#/components/schemas/RectificationInput"
}

Respostas

200 201 401 403 404 409 422 423 429 502

200 · The NC that already rectified this document.

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "payment_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT",
                        "NC",
                        "RG"
                    ]
                },
                "number": {
                    "type": "string",
                    "nullable": true
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "queued",
                        "blocked",
                        "submitting",
                        "submitted",
                        "checking",
                        "unknown",
                        "valid",
                        "rejected",
                        "simulated"
                    ]
                },
                "simulated": {
                    "type": "boolean"
                },
                "fiscal_valid": {
                    "type": "boolean"
                },
                "snapshot": {
                    "type": "object",
                    "properties": {
                        "customer": {
                            "type": "object",
                            "properties": {
                                "tax_id": {
                                    "type": "string",
                                    "pattern": "^[A-Z0-9]{9,15}$"
                                },
                                "name": {
                                    "type": "string",
                                    "maxLength": 160
                                },
                                "address": {
                                    "type": "string",
                                    "maxLength": 500
                                },
                                "country": {
                                    "type": "string",
                                    "enum": [
                                        "AO"
                                    ]
                                }
                            },
                            "required": [
                                "tax_id",
                                "name",
                                "address",
                                "country"
                            ],
                            "$ref": "#/components/schemas/Customer"
                        },
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object"
                            }
                        },
                        "totals": {
                            "type": "object",
                            "properties": {
                                "net_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "tax_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "gross_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                }
                            },
                            "required": [
                                "net_minor",
                                "tax_minor",
                                "gross_minor"
                            ]
                        }
                    }
                },
                "issued_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "validated_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "last_error_code": {
                    "type": "string",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "original_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "corrects_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "due_date": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                },
                "calculation_version": {
                    "type": "string",
                    "nullable": true
                },
                "pdf_url": {
                    "type": "string",
                    "nullable": true
                },
                "settlements": {
                    "type": "array",
                    "description": "The receipts (RG) that settled an FT (relation settled_by) or the FT an RG settles (relation settles), with the amount of each.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "relation": {
                                "type": "string",
                                "enum": [
                                    "settles",
                                    "settled_by"
                                ]
                            },
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "type": {
                                "type": "string"
                            },
                            "amount_minor": {
                                "type": "integer",
                                "format": "int64"
                            }
                        }
                    }
                },
                "linked": {
                    "type": "object",
                    "description": "Listing only. The document this one is tied to by a rectification: a credit note points to the document it rectifies, a rectified FT/FR to its credit note.",
                    "properties": {
                        "relation": {
                            "type": "string",
                            "enum": [
                                "rectifies",
                                "rectified_by"
                            ]
                        },
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "number": {
                            "type": "string",
                            "nullable": true
                        },
                        "type": {
                            "type": "string"
                        }
                    },
                    "nullable": true
                },
                "payment": {
                    "type": "object",
                    "description": "The charge the document belongs to; for an FT or RG settled by allocation, the charge that paid it.",
                    "properties": {
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "external_id": {
                            "type": "string",
                            "nullable": true
                        },
                        "reference": {
                            "type": "string",
                            "nullable": true
                        },
                        "method": {
                            "type": "string"
                        },
                        "amount_minor": {
                            "type": "integer",
                            "format": "int64"
                        },
                        "currency": {
                            "type": "string"
                        }
                    },
                    "nullable": true
                },
                "last_error_message": {
                    "type": "string",
                    "nullable": true,
                    "description": "The AGT explanation for last_error_code, when the AGT gave one."
                },
                "rectification": {
                    "type": "object",
                    "description": "Only in GET /documents/{document}. Whether the document can be rectified with a full NC, and the NC that rectified it.",
                    "properties": {
                        "allowed": {
                            "type": "boolean"
                        },
                        "blocked_reason": {
                            "type": "string",
                            "nullable": true,
                            "description": "Why an FT or FR cannot be rectified, for example an FT already settled by a receipt (RG)."
                        },
                        "credit_note": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "status": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "required": [
                "id",
                "payment_id",
                "merchant_id",
                "environment",
                "type",
                "status",
                "simulated",
                "fiscal_valid",
                "snapshot"
            ],
            "$ref": "#/components/schemas/FiscalDocument"
        }
    },
    "required": [
        "data"
    ]
}

201 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "payment_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT",
                        "NC",
                        "RG"
                    ]
                },
                "number": {
                    "type": "string",
                    "nullable": true
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "queued",
                        "blocked",
                        "submitting",
                        "submitted",
                        "checking",
                        "unknown",
                        "valid",
                        "rejected",
                        "simulated"
                    ]
                },
                "simulated": {
                    "type": "boolean"
                },
                "fiscal_valid": {
                    "type": "boolean"
                },
                "snapshot": {
                    "type": "object",
                    "properties": {
                        "customer": {
                            "type": "object",
                            "properties": {
                                "tax_id": {
                                    "type": "string",
                                    "pattern": "^[A-Z0-9]{9,15}$"
                                },
                                "name": {
                                    "type": "string",
                                    "maxLength": 160
                                },
                                "address": {
                                    "type": "string",
                                    "maxLength": 500
                                },
                                "country": {
                                    "type": "string",
                                    "enum": [
                                        "AO"
                                    ]
                                }
                            },
                            "required": [
                                "tax_id",
                                "name",
                                "address",
                                "country"
                            ],
                            "$ref": "#/components/schemas/Customer"
                        },
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object"
                            }
                        },
                        "totals": {
                            "type": "object",
                            "properties": {
                                "net_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "tax_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "gross_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                }
                            },
                            "required": [
                                "net_minor",
                                "tax_minor",
                                "gross_minor"
                            ]
                        }
                    }
                },
                "issued_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "validated_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "last_error_code": {
                    "type": "string",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "original_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "corrects_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "due_date": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                },
                "calculation_version": {
                    "type": "string",
                    "nullable": true
                },
                "pdf_url": {
                    "type": "string",
                    "nullable": true
                },
                "settlements": {
                    "type": "array",
                    "description": "The receipts (RG) that settled an FT (relation settled_by) or the FT an RG settles (relation settles), with the amount of each.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "relation": {
                                "type": "string",
                                "enum": [
                                    "settles",
                                    "settled_by"
                                ]
                            },
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "type": {
                                "type": "string"
                            },
                            "amount_minor": {
                                "type": "integer",
                                "format": "int64"
                            }
                        }
                    }
                },
                "linked": {
                    "type": "object",
                    "description": "Listing only. The document this one is tied to by a rectification: a credit note points to the document it rectifies, a rectified FT/FR to its credit note.",
                    "properties": {
                        "relation": {
                            "type": "string",
                            "enum": [
                                "rectifies",
                                "rectified_by"
                            ]
                        },
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "number": {
                            "type": "string",
                            "nullable": true
                        },
                        "type": {
                            "type": "string"
                        }
                    },
                    "nullable": true
                },
                "payment": {
                    "type": "object",
                    "description": "The charge the document belongs to; for an FT or RG settled by allocation, the charge that paid it.",
                    "properties": {
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "external_id": {
                            "type": "string",
                            "nullable": true
                        },
                        "reference": {
                            "type": "string",
                            "nullable": true
                        },
                        "method": {
                            "type": "string"
                        },
                        "amount_minor": {
                            "type": "integer",
                            "format": "int64"
                        },
                        "currency": {
                            "type": "string"
                        }
                    },
                    "nullable": true
                },
                "last_error_message": {
                    "type": "string",
                    "nullable": true,
                    "description": "The AGT explanation for last_error_code, when the AGT gave one."
                },
                "rectification": {
                    "type": "object",
                    "description": "Only in GET /documents/{document}. Whether the document can be rectified with a full NC, and the NC that rectified it.",
                    "properties": {
                        "allowed": {
                            "type": "boolean"
                        },
                        "blocked_reason": {
                            "type": "string",
                            "nullable": true,
                            "description": "Why an FT or FR cannot be rectified, for example an FT already settled by a receipt (RG)."
                        },
                        "credit_note": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "status": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "required": [
                "id",
                "payment_id",
                "merchant_id",
                "environment",
                "type",
                "status",
                "simulated",
                "fiscal_valid",
                "snapshot"
            ],
            "$ref": "#/components/schemas/FiscalDocument"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

Emissão e exportação fiscal

GET/fiscal/exemption-reasons

List the active AGT VAT exemption reasons accepted on 0% lines.

Bearer do projecto · documents:read

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "pattern": "^M[0-9]{2}$"
                    },
                    "document_mention": {
                        "type": "string"
                    },
                    "legal_basis": {
                        "type": "string",
                        "nullable": true
                    },
                    "description": {
                        "type": "string"
                    },
                    "exemption_type": {
                        "type": "string",
                        "enum": [
                            "incompleta_interna",
                            "incompleta_importacao",
                            "completa",
                            "regime_especial_aduaneiro"
                        ]
                    }
                },
                "required": [
                    "code",
                    "document_mention",
                    "legal_basis",
                    "description",
                    "exemption_type"
                ],
                "$ref": "#/components/schemas/VatExemptionReason"
            }
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/taxpayer

Look up a customer's NIF at the AGT. 404 when the AGT does not know it; 503 when the lookup is off or the AGT does not answer.

Bearer do projecto · documents:read

Parâmetros

Nome	Local / tipo	Regra
`tax_id`	query · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502 503

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "tax_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string",
                    "nullable": true
                },
                "type": {
                    "type": "string",
                    "nullable": true
                },
                "status": {
                    "type": "string",
                    "nullable": true
                },
                "vat_regime": {
                    "type": "string",
                    "nullable": true
                },
                "non_resident": {
                    "type": "boolean"
                }
            },
            "required": [
                "tax_id",
                "non_resident"
            ]
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/drafts

List editable fiscal drafts.

Bearer do projecto · documents:read

Parâmetros

Nome	Local / tipo	Regra
`page`	query · integer	Opcional. Pages of 50 records.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "client_application_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "merchant_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "environment": {
                        "type": "string"
                    },
                    "document_type": {
                        "type": "string"
                    },
                    "revision": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "data": {
                        "type": "object"
                    },
                    "issued_document_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "required": [
                    "id",
                    "merchant_id",
                    "environment",
                    "document_type",
                    "revision",
                    "data"
                ],
                "$ref": "#/components/schemas/Draft"
            }
        },
        "current_page": {
            "type": "integer",
            "format": "int64"
        },
        "last_page": {
            "type": "integer",
            "format": "int64"
        },
        "total": {
            "type": "integer",
            "format": "int64"
        }
    },
    "required": [
        "data",
        "current_page",
        "last_page",
        "total"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/fiscal/drafts

Create an idempotent draft. Prices and catalogue data are copied.

Bearer do projecto · documents:write

Parâmetros

Nome	Local / tipo	Regra
`Idempotency-Key`	header · string	Obrigatório. Reuse the same key and body on retries. Scope is project and environment.

Corpo JSON

Campo	Tipo	Obrigatório
`merchant_id`	string	Sim
`type`	string	Sim
`customer`	object	Não
`customer_id`	string	Não
`items`	array	Sim
`due_date`	string	Não
`original_document_id`	string	Não
`corrects_document_id`	string	Não
`reason`	string	Não
`revision`	integer	Não

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "merchant_id": {
            "type": "string",
            "format": "uuid"
        },
        "type": {
            "type": "string",
            "enum": [
                "FT",
                "NC",
                "FR"
            ],
            "description": "FR only for correction of a rejected FR. Ordinary FR starts with a payment."
        },
        "customer": {
            "type": "object",
            "properties": {
                "tax_id": {
                    "type": "string",
                    "pattern": "^[A-Z0-9]{9,15}$"
                },
                "name": {
                    "type": "string",
                    "maxLength": 160
                },
                "address": {
                    "type": "string",
                    "maxLength": 500
                },
                "country": {
                    "type": "string",
                    "enum": [
                        "AO"
                    ]
                }
            },
            "required": [
                "tax_id",
                "name",
                "address",
                "country"
            ],
            "$ref": "#/components/schemas/Customer"
        },
        "customer_id": {
            "type": "string",
            "format": "uuid"
        },
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "maxLength": 60
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 200
                    },
                    "quantity": {
                        "oneOf": [
                            {
                                "type": "integer",
                                "format": "int64",
                                "minimum": 1,
                                "maximum": 99999
                            },
                            {
                                "type": "string",
                                "pattern": "^(?:0|[1-9][0-9]{0,4})(?:\\.[0-9]{1,4})?$"
                            }
                        ]
                    },
                    "unit_amount_minor": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 0,
                        "maximum": 9999999999
                    },
                    "vat_rate": {
                        "oneOf": [
                            {
                                "type": "integer",
                                "format": "int64",
                                "enum": [
                                    14,
                                    7,
                                    5,
                                    1,
                                    0
                                ]
                            },
                            {
                                "type": "string",
                                "pattern": "^(?:14|7|5|1|0)(?:\\.0{1,2})?$"
                            }
                        ],
                        "description": "Angolan VAT rate: 14, 7, 5, 1 or 0."
                    },
                    "tax_code": {
                        "type": "string",
                        "enum": [
                            "NOR",
                            "RED",
                            "ISE"
                        ],
                        "description": "Optional. Derived from vat_rate (0 ISE, 14 NOR, 7/5/1 RED); when sent it must match."
                    },
                    "operation_type": {
                        "type": "string",
                        "enum": [
                            "SE",
                            "SS",
                            "STP",
                            "SR",
                            "SIF",
                            "SHS",
                            "ST",
                            "SG",
                            "TB",
                            "AS",
                            "QT",
                            "RD"
                        ]
                    },
                    "exemption_code": {
                        "type": "string",
                        "pattern": "^M[0-9]{2}$",
                        "description": "Required for 0% and forbidden otherwise: an active code from GET /fiscal/exemption-reasons.",
                        "nullable": true
                    },
                    "discount_bps": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 0,
                        "maximum": 10000
                    },
                    "unit_of_measure": {
                        "type": "string",
                        "maxLength": 20
                    },
                    "original_line": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 1,
                        "description": "Required for NC: one-based line in the original document."
                    },
                    "catalogue_item_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "cnbs_code": {
                        "type": "string",
                        "pattern": "^[0-9]{8}$",
                        "description": "CNBS code (INE classification of goods and services) from GET /fiscal/cnbs-codes, sent to the AGT as productCode instead of code. Optional until fiscal.cnbs_required_from (2027-01-01); from that date every FT and FR line must carry an active code.",
                        "nullable": true
                    }
                },
                "required": [
                    "code",
                    "description",
                    "quantity",
                    "unit_amount_minor",
                    "vat_rate",
                    "operation_type"
                ],
                "$ref": "#/components/schemas/DecimalItem"
            },
            "minItems": 1,
            "maxItems": 100
        },
        "due_date": {
            "type": "string",
            "format": "date"
        },
        "original_document_id": {
            "type": "string",
            "format": "uuid"
        },
        "corrects_document_id": {
            "type": "string",
            "format": "uuid"
        },
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 60
        },
        "revision": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
        }
    },
    "required": [
        "merchant_id",
        "type",
        "items"
    ],
    "$ref": "#/components/schemas/DraftInput"
}

Respostas

201 401 403 404 409 422 423 429 502

201 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "client_application_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string"
                },
                "document_type": {
                    "type": "string"
                },
                "revision": {
                    "type": "integer",
                    "format": "int64"
                },
                "data": {
                    "type": "object"
                },
                "issued_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "document_type",
                "revision",
                "data"
            ],
            "$ref": "#/components/schemas/Draft"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

PUT/fiscal/drafts/{draft}

Revise a draft with the expected revision to prevent lost updates.

Bearer do projecto · documents:write

Parâmetros

Nome	Local / tipo	Regra
`draft`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`customer`	object	Não
`customer_id`	string	Não
`items`	array	Sim
`due_date`	string	Não
`original_document_id`	string	Não
`corrects_document_id`	string	Não
`reason`	string	Não
`revision`	integer	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "customer": {
            "type": "object",
            "properties": {
                "tax_id": {
                    "type": "string",
                    "pattern": "^[A-Z0-9]{9,15}$"
                },
                "name": {
                    "type": "string",
                    "maxLength": 160
                },
                "address": {
                    "type": "string",
                    "maxLength": 500
                },
                "country": {
                    "type": "string",
                    "enum": [
                        "AO"
                    ]
                }
            },
            "required": [
                "tax_id",
                "name",
                "address",
                "country"
            ],
            "$ref": "#/components/schemas/Customer"
        },
        "customer_id": {
            "type": "string",
            "format": "uuid"
        },
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "maxLength": 60
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 200
                    },
                    "quantity": {
                        "oneOf": [
                            {
                                "type": "integer",
                                "format": "int64",
                                "minimum": 1,
                                "maximum": 99999
                            },
                            {
                                "type": "string",
                                "pattern": "^(?:0|[1-9][0-9]{0,4})(?:\\.[0-9]{1,4})?$"
                            }
                        ]
                    },
                    "unit_amount_minor": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 0,
                        "maximum": 9999999999
                    },
                    "vat_rate": {
                        "oneOf": [
                            {
                                "type": "integer",
                                "format": "int64",
                                "enum": [
                                    14,
                                    7,
                                    5,
                                    1,
                                    0
                                ]
                            },
                            {
                                "type": "string",
                                "pattern": "^(?:14|7|5|1|0)(?:\\.0{1,2})?$"
                            }
                        ],
                        "description": "Angolan VAT rate: 14, 7, 5, 1 or 0."
                    },
                    "tax_code": {
                        "type": "string",
                        "enum": [
                            "NOR",
                            "RED",
                            "ISE"
                        ],
                        "description": "Optional. Derived from vat_rate (0 ISE, 14 NOR, 7/5/1 RED); when sent it must match."
                    },
                    "operation_type": {
                        "type": "string",
                        "enum": [
                            "SE",
                            "SS",
                            "STP",
                            "SR",
                            "SIF",
                            "SHS",
                            "ST",
                            "SG",
                            "TB",
                            "AS",
                            "QT",
                            "RD"
                        ]
                    },
                    "exemption_code": {
                        "type": "string",
                        "pattern": "^M[0-9]{2}$",
                        "description": "Required for 0% and forbidden otherwise: an active code from GET /fiscal/exemption-reasons.",
                        "nullable": true
                    },
                    "discount_bps": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 0,
                        "maximum": 10000
                    },
                    "unit_of_measure": {
                        "type": "string",
                        "maxLength": 20
                    },
                    "original_line": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 1,
                        "description": "Required for NC: one-based line in the original document."
                    },
                    "catalogue_item_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "cnbs_code": {
                        "type": "string",
                        "pattern": "^[0-9]{8}$",
                        "description": "CNBS code (INE classification of goods and services) from GET /fiscal/cnbs-codes, sent to the AGT as productCode instead of code. Optional until fiscal.cnbs_required_from (2027-01-01); from that date every FT and FR line must carry an active code.",
                        "nullable": true
                    }
                },
                "required": [
                    "code",
                    "description",
                    "quantity",
                    "unit_amount_minor",
                    "vat_rate",
                    "operation_type"
                ],
                "$ref": "#/components/schemas/DecimalItem"
            },
            "minItems": 1,
            "maxItems": 100
        },
        "due_date": {
            "type": "string",
            "format": "date"
        },
        "original_document_id": {
            "type": "string",
            "format": "uuid"
        },
        "corrects_document_id": {
            "type": "string",
            "format": "uuid"
        },
        "reason": {
            "type": "string",
            "minLength": 5,
            "maxLength": 60
        },
        "revision": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
        }
    },
    "required": [
        "items",
        "revision"
    ],
    "$ref": "#/components/schemas/DraftRevision"
}

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "client_application_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string"
                },
                "document_type": {
                    "type": "string"
                },
                "revision": {
                    "type": "integer",
                    "format": "int64"
                },
                "data": {
                    "type": "object"
                },
                "issued_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "document_type",
                "revision",
                "data"
            ],
            "$ref": "#/components/schemas/Draft"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/fiscal/drafts/{draft}/issue

Queue fiscal issuance once. New live capabilities require homologation configuration.

Bearer do projecto · documents:write

Parâmetros

Nome	Local / tipo	Regra
`draft`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`revision`	integer	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "revision": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
        }
    },
    "required": [
        "revision"
    ]
}

Respostas

202 401 403 404 409 422 423 429 502

202 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "payment_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string",
                    "enum": [
                        "sandbox",
                        "live"
                    ]
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "FR",
                        "FT",
                        "NC",
                        "RG"
                    ]
                },
                "number": {
                    "type": "string",
                    "nullable": true
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "queued",
                        "blocked",
                        "submitting",
                        "submitted",
                        "checking",
                        "unknown",
                        "valid",
                        "rejected",
                        "simulated"
                    ]
                },
                "simulated": {
                    "type": "boolean"
                },
                "fiscal_valid": {
                    "type": "boolean"
                },
                "snapshot": {
                    "type": "object",
                    "properties": {
                        "customer": {
                            "type": "object",
                            "properties": {
                                "tax_id": {
                                    "type": "string",
                                    "pattern": "^[A-Z0-9]{9,15}$"
                                },
                                "name": {
                                    "type": "string",
                                    "maxLength": 160
                                },
                                "address": {
                                    "type": "string",
                                    "maxLength": 500
                                },
                                "country": {
                                    "type": "string",
                                    "enum": [
                                        "AO"
                                    ]
                                }
                            },
                            "required": [
                                "tax_id",
                                "name",
                                "address",
                                "country"
                            ],
                            "$ref": "#/components/schemas/Customer"
                        },
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object"
                            }
                        },
                        "totals": {
                            "type": "object",
                            "properties": {
                                "net_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "tax_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "gross_minor": {
                                    "type": "integer",
                                    "format": "int64"
                                }
                            },
                            "required": [
                                "net_minor",
                                "tax_minor",
                                "gross_minor"
                            ]
                        }
                    }
                },
                "issued_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "validated_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "last_error_code": {
                    "type": "string",
                    "nullable": true
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "original_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "corrects_document_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                },
                "due_date": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                },
                "calculation_version": {
                    "type": "string",
                    "nullable": true
                },
                "pdf_url": {
                    "type": "string",
                    "nullable": true
                },
                "settlements": {
                    "type": "array",
                    "description": "The receipts (RG) that settled an FT (relation settled_by) or the FT an RG settles (relation settles), with the amount of each.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "relation": {
                                "type": "string",
                                "enum": [
                                    "settles",
                                    "settled_by"
                                ]
                            },
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "number": {
                                "type": "string",
                                "nullable": true
                            },
                            "type": {
                                "type": "string"
                            },
                            "amount_minor": {
                                "type": "integer",
                                "format": "int64"
                            }
                        }
                    }
                },
                "linked": {
                    "type": "object",
                    "description": "Listing only. The document this one is tied to by a rectification: a credit note points to the document it rectifies, a rectified FT/FR to its credit note.",
                    "properties": {
                        "relation": {
                            "type": "string",
                            "enum": [
                                "rectifies",
                                "rectified_by"
                            ]
                        },
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "number": {
                            "type": "string",
                            "nullable": true
                        },
                        "type": {
                            "type": "string"
                        }
                    },
                    "nullable": true
                },
                "payment": {
                    "type": "object",
                    "description": "The charge the document belongs to; for an FT or RG settled by allocation, the charge that paid it.",
                    "properties": {
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "external_id": {
                            "type": "string",
                            "nullable": true
                        },
                        "reference": {
                            "type": "string",
                            "nullable": true
                        },
                        "method": {
                            "type": "string"
                        },
                        "amount_minor": {
                            "type": "integer",
                            "format": "int64"
                        },
                        "currency": {
                            "type": "string"
                        }
                    },
                    "nullable": true
                },
                "last_error_message": {
                    "type": "string",
                    "nullable": true,
                    "description": "The AGT explanation for last_error_code, when the AGT gave one."
                },
                "rectification": {
                    "type": "object",
                    "description": "Only in GET /documents/{document}. Whether the document can be rectified with a full NC, and the NC that rectified it.",
                    "properties": {
                        "allowed": {
                            "type": "boolean"
                        },
                        "blocked_reason": {
                            "type": "string",
                            "nullable": true,
                            "description": "Why an FT or FR cannot be rectified, for example an FT already settled by a receipt (RG)."
                        },
                        "credit_note": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "number": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "status": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "required": [
                "id",
                "payment_id",
                "merchant_id",
                "environment",
                "type",
                "status",
                "simulated",
                "fiscal_valid",
                "snapshot"
            ],
            "$ref": "#/components/schemas/FiscalDocument"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/exports

List project export jobs.

Bearer do projecto · reports:read

Parâmetros

Nome	Local / tipo	Regra
`page`	query · integer	Opcional. Pages of 50 records.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "merchant_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "environment": {
                        "type": "string"
                    },
                    "format": {
                        "type": "string"
                    },
                    "scope": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "processing",
                            "complete",
                            "failed",
                            "expired"
                        ]
                    },
                    "summary": {
                        "type": "object"
                    },
                    "sha256": {
                        "type": "string",
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "error_code": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "required": [
                    "id",
                    "merchant_id",
                    "environment",
                    "format",
                    "scope",
                    "status"
                ],
                "$ref": "#/components/schemas/Export"
            }
        },
        "current_page": {
            "type": "integer",
            "format": "int64"
        },
        "last_page": {
            "type": "integer",
            "format": "int64"
        },
        "total": {
            "type": "integer",
            "format": "int64"
        }
    },
    "required": [
        "data",
        "current_page",
        "last_page",
        "total"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/fiscal/exports

Snapshot a project report for asynchronous generation, bounded to one fiscal year and 5000 documents/payments.

Bearer do projecto · reports:read

Parâmetros

Nome	Local / tipo	Regra
`Idempotency-Key`	header · string	Obrigatório. Reuse the same key and body on retries. Scope is project and environment.

Corpo JSON

Campo	Tipo	Obrigatório
`merchant_id`	string	Sim
`format`	string	Sim
`start_date`	string	Sim
`end_date`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "merchant_id": {
            "type": "string",
            "format": "uuid"
        },
        "format": {
            "type": "string",
            "enum": [
                "json_report"
            ],
            "description": "Issuer-wide SAF-T is restricted to the authorised owner in the portal."
        },
        "start_date": {
            "type": "string",
            "format": "date"
        },
        "end_date": {
            "type": "string",
            "format": "date"
        }
    },
    "required": [
        "merchant_id",
        "format",
        "start_date",
        "end_date"
    ],
    "$ref": "#/components/schemas/ExportRequest"
}

Respostas

202 401 403 404 409 422 423 429 502

202 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string"
                },
                "format": {
                    "type": "string"
                },
                "scope": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "pending",
                        "processing",
                        "complete",
                        "failed",
                        "expired"
                    ]
                },
                "summary": {
                    "type": "object"
                },
                "sha256": {
                    "type": "string",
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "error_code": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "format",
                "scope",
                "status"
            ],
            "$ref": "#/components/schemas/Export"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/exports/{export}

Read generation status and checksum.

Bearer do projecto · reports:read

Parâmetros

Nome	Local / tipo	Regra
`export`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string"
                },
                "format": {
                    "type": "string"
                },
                "scope": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "pending",
                        "processing",
                        "complete",
                        "failed",
                        "expired"
                    ]
                },
                "summary": {
                    "type": "object"
                },
                "sha256": {
                    "type": "string",
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "error_code": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "format",
                "scope",
                "status"
            ],
            "$ref": "#/components/schemas/Export"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/fiscal/exports/{export}/regenerate

Generate again an export that expired or failed, from the documents as they are now. An export still pending is returned as is; one still available answers 409.

Bearer do projecto · reports:read

Parâmetros

Nome	Local / tipo	Regra
`export`	path · string	Obrigatório.

Respostas

202 401 403 404 409 422 423 429 502

202 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string"
                },
                "format": {
                    "type": "string"
                },
                "scope": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "pending",
                        "processing",
                        "complete",
                        "failed",
                        "expired"
                    ]
                },
                "summary": {
                    "type": "object"
                },
                "sha256": {
                    "type": "string",
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "error_code": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "format",
                "scope",
                "status"
            ],
            "$ref": "#/components/schemas/Export"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/exports/{export}/download

Download verified report; availability expires after seven days.

Bearer do projecto · reports:read

Parâmetros

Nome	Local / tipo	Regra
`export`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object"
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/saft

List the SAF-T files of the companies the project owns.

Bearer do projecto · saft:read

Parâmetros

Nome	Local / tipo	Regra
`page`	query · integer	Opcional. Pages of 50 records.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "merchant_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "environment": {
                        "type": "string"
                    },
                    "format": {
                        "type": "string"
                    },
                    "scope": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "processing",
                            "complete",
                            "failed",
                            "expired"
                        ]
                    },
                    "summary": {
                        "type": "object"
                    },
                    "sha256": {
                        "type": "string",
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "error_code": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "required": [
                    "id",
                    "merchant_id",
                    "environment",
                    "format",
                    "scope",
                    "status"
                ],
                "$ref": "#/components/schemas/Export"
            }
        },
        "current_page": {
            "type": "integer",
            "format": "int64"
        },
        "last_page": {
            "type": "integer",
            "format": "int64"
        },
        "total": {
            "type": "integer",
            "format": "int64"
        }
    },
    "required": [
        "data",
        "current_page",
        "last_page",
        "total"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/fiscal/saft

Request the SAF-T file of a company the project owns, for a period of one fiscal year. It carries the documents of internal series, is generated asynchronously and is refused when the period has none.

Bearer do projecto · saft:read

Parâmetros

Nome	Local / tipo	Regra
`Idempotency-Key`	header · string	Obrigatório. Reuse the same key and body on retries. Scope is project and environment.

Corpo JSON

Campo	Tipo	Obrigatório
`merchant_id`	string	Sim
`start_date`	string	Sim
`end_date`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "merchant_id": {
            "type": "string",
            "format": "uuid"
        },
        "start_date": {
            "type": "string",
            "format": "date"
        },
        "end_date": {
            "type": "string",
            "format": "date",
            "description": "Within the same fiscal year as start_date."
        }
    },
    "required": [
        "merchant_id",
        "start_date",
        "end_date"
    ],
    "$ref": "#/components/schemas/SaftRequest"
}

Respostas

202 401 403 404 409 422 423 429 502

202 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string"
                },
                "format": {
                    "type": "string"
                },
                "scope": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "pending",
                        "processing",
                        "complete",
                        "failed",
                        "expired"
                    ]
                },
                "summary": {
                    "type": "object"
                },
                "sha256": {
                    "type": "string",
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "error_code": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "format",
                "scope",
                "status"
            ],
            "$ref": "#/components/schemas/Export"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/saft/{export}

Read the generation status, checksum and schema validation of a SAF-T file. summary.validation lists the translated schema errors; a file with errors is still delivered.

Bearer do projecto · saft:read

Parâmetros

Nome	Local / tipo	Regra
`export`	path · string	Obrigatório.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string"
                },
                "format": {
                    "type": "string"
                },
                "scope": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "pending",
                        "processing",
                        "complete",
                        "failed",
                        "expired"
                    ]
                },
                "summary": {
                    "type": "object"
                },
                "sha256": {
                    "type": "string",
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "error_code": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "format",
                "scope",
                "status"
            ],
            "$ref": "#/components/schemas/Export"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

POST/fiscal/saft/{export}/regenerate

Generate again a SAF-T file that expired or failed, from the documents as they are now. A pending one is returned as is; one still available answers 409.

Bearer do projecto · saft:read

Parâmetros

Nome	Local / tipo	Regra
`export`	path · string	Obrigatório.

Respostas

202 401 403 404 409 422 423 429 502

202 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "merchant_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "environment": {
                    "type": "string"
                },
                "format": {
                    "type": "string"
                },
                "scope": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "pending",
                        "processing",
                        "complete",
                        "failed",
                        "expired"
                    ]
                },
                "summary": {
                    "type": "object"
                },
                "sha256": {
                    "type": "string",
                    "nullable": true
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                },
                "error_code": {
                    "type": "string",
                    "nullable": true
                }
            },
            "required": [
                "id",
                "merchant_id",
                "environment",
                "format",
                "scope",
                "status"
            ],
            "$ref": "#/components/schemas/Export"
        }
    },
    "required": [
        "data"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/saft/{export}/download

Download the SAF-T file: a zip with the XML and its SHA-256 by default, or the XML with format=xml. Available for seven days.

Bearer do projecto · saft:read

Parâmetros

Nome	Local / tipo	Regra
`export`	path · string	Obrigatório.
`format`	query · string	Opcional. `zip \| xml`

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object"
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

GET/fiscal/cnbs-codes

Search the active CNBS codes accepted in cnbs_code, by the start of the code or words of the description.

Bearer do projecto · documents:read

Parâmetros

Nome	Local / tipo	Regra
`search`	query · string	Opcional.
`per_page`	query · integer	Opcional.
`page`	query · integer	Opcional.

Respostas

200 401 403 404 409 422 423 429 502

200 · Success

application/json

{
    "type": "object",
    "properties": {
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "pattern": "^[0-9]{8}$"
                    },
                    "description": {
                        "type": "string"
                    }
                },
                "required": [
                    "code",
                    "description"
                ],
                "$ref": "#/components/schemas/CnbsCode"
            }
        },
        "required_from": {
            "type": "string",
            "format": "date",
            "description": "Issue date from which every FT and FR line must carry a CNBS code."
        },
        "current_page": {
            "type": "integer"
        },
        "last_page": {
            "type": "integer"
        },
        "total": {
            "type": "integer"
        }
    },
    "required": [
        "data",
        "required_from",
        "current_page",
        "last_page",
        "total"
    ]
}

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

Notificações do provedor

POST/webhooks/proxypay/{account}

Provider callback. Authenticate the exact raw bytes before processing.

Endpoint exclusivo para notificações da ProxyPay. Não é o webhook do seu consumidor. Exige a assinatura do provedor com a chave da conta; não envie uma chave do projecto aqui.

Parâmetros

Nome	Local / tipo	Regra
`account`	path · string	Obrigatório.

Corpo JSON

Campo	Tipo	Obrigatório
`id`	integer	Sim
`reference_id`	integer	Sim
`entity_id`	integer	Sim
`amount`	string	Sim
`datetime`	string	Sim

Schema completo do pedido

{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer",
            "format": "int64"
        },
        "reference_id": {
            "type": "integer",
            "format": "int64"
        },
        "entity_id": {
            "type": "integer",
            "format": "int64"
        },
        "amount": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$"
        },
        "datetime": {
            "type": "string",
            "format": "date-time"
        }
    },
    "required": [
        "id",
        "reference_id",
        "entity_id",
        "amount",
        "datetime"
    ],
    "$ref": "#/components/schemas/ProviderCallback"
}

Respostas

204 401 403 404 409 422 423 429 502

204 · Success

Para respostas de erro, consulte códigos e tratamento de falhas. O contrato de download inclui todos os schemas e respostas.

Da integração à operação

Preparar produção

Antes de mudar para uma chave Live, valide uma cobrança completa em Sandbox: criação, confirmação, consulta, recepção do webhook e deduplicação no seu sistema. Um teste de autenticação isolado não valida esse percurso.

Empresa e projecto. A empresa precisa de conta própria no provedor e de autorização para o projecto consumidor. Cada ambiente guarda a sua configuração; um grant técnico não transfere a propriedade da empresa.
Credenciais e permissões. Configure a entidade e a chave ProxyPay de produção, conceda acesso Live aos operadores necessários e emita uma chave de projecto Live com os scopes adequados. Não partilhe chaves com o navegador.
Notificações. Publique os endpoints HTTPS, configure o destino do consumidor e o callback da conta ProxyPay, guarde os segredos e valide as assinaturas. Teste uma entrega repetida para garantir que não aplica a mesma venda duas vezes.
Processamento. Configure o scheduler para executar a cada minuto, base de dados e cache partilhadas, cópias de segurança e monitorização das falhas. A aplicação e os workers precisam da mesma configuração e APP_KEY.
Facturação. Complete as configurações da empresa, séries, chaves e homologação exigidas para os fluxos fiscais que vai utilizar. A confirmação do pagamento e a validade fiscal são verificações distintas.

Estado desta versão. A integração real com ProxyPay e os fluxos fiscais precisam de validação com credenciais e respostas dos respectivos serviços. A simulação local não demonstra homologação, liquidação bancária ou validade fiscal. Reembolsos automáticos não estão implementados.

Se a integração falhar, recolha X-Request-ID, ambiente, ID da cobrança e error.code. Não inclua chaves, palavras-passe ou dados bancários nos registos de suporte.

Voltar ao início

Da primeira chamada à confirmação do pagamento.

Prepare a conta no portal

Crie a conta

Adicione a empresa

Configure a conta de pagamentos

Configure a facturação, se for emitir documentos

Crie a chave e o webhook

Uma chave por projecto e ambiente

Criar e configurar empresas pela API

Crie a empresa

Configure a conta ProxyPay

Configure o perfil fiscal e as séries

Crie a sua primeira cobrança

Prepare a empresa e a chave

Obtenha o identificador da empresa

Guarde o pedido e envie-o

Guarde a resposta e acompanhe o estado

Cobrança com cliente e artigos, sem factura

Teste o ciclo com dados persistentes

Cancelar e acompanhar o resultado

Renovar uma cobrança expirada

Da cobrança à factura. Ou da factura à cobrança.

Consultar documentos e descarregar o PDF

Reutilizar clientes e artigos

Exportar um relatório do projecto

Receber e confirmar eventos

Configurar o destino

Eventos e formato

Autenticar antes de processar

Tentativas e recuperação

Estados, erros e limites

Limites de utilização

Referência da API

Disponibilidade

Respostas

Ligação da chave

Respostas

Parâmetros

Respostas

Empresas e catálogos

Respostas

Corpo JSON

Respostas

Parâmetros

Respostas

Parâmetros

Corpo JSON

Respostas

Parâmetros

Respostas

Parâmetros

Corpo JSON

Respostas

Parâmetros

Respostas

Parâmetros

Respostas

Parâmetros

Corpo JSON

Respostas

Parâmetros

Corpo JSON

Respostas

Parâmetros

Corpo JSON

Respostas

Parâmetros

Respostas

Parâmetros

Corpo JSON

Respostas

Pagamentos

Parâmetros

Corpo JSON

Respostas

Parâmetros

Respostas

Parâmetros

Respostas

Parâmetros

Da primeira chamada
à confirmação do pagamento.