Pagamentos a fornecedores

Consultar e registar pagamentos feitos a fornecedores de um condomínio.

Listar os pagamentos de um condomínio

GET /buildings/{idBuilding}/supplier-payments

Permissão · finance:read

Parâmetros

Parâmetro	Tipo	Por omissão	Descrição
idBuilding	inteiro	—	No caminho. O condomínio
idSupplier	inteiro	todos	Só os pagamentos a este fornecedor
fromDate	data	—	A partir desta data
toDate	data	—	Até esta data, inclusive
include	texto	—	settledInvoices para trazer as faturas que cada pagamento liquidou
limit	inteiro	100	Registos por página, no máximo 500
cursor	texto	—	Cursor da página seguinte

Pedido

curl "https://servidor.exemplo/api/integrations/v1/acme/buildings/12/supplier-payments?include=settledInvoices" \
  -H "ApiKey: $GC_API_KEY"

Resposta · 200

{
  "Items": [
    {
      "Id": 2210,
      "IdBuilding": 12,
      "BuildingCode": "0012",
      "DocumentId": "PG 2026/331",
      "DocumentDate": "2026-09-30T00:00:00",
      "Supplier": { "Id": 88, "Description": "Elevadores Norte, Lda." },
      "Amount": 246.0,
      "BankingFees": 0.5,
      "Adjustment": null,
      "AccountingReference": "2026/B/118",
      "HasFile": true,
      "SettledInvoices": [
        { "Id": 4412, "DocumentId": "FT 2026/1180", "DocumentDate": "2026-09-10T00:00:00" }
      ]
    }
  ],
  "Paging": { "Limit": 100, "NextCursor": null, "HasMore": false }
}

Campo	Tipo	Descrição
Id	inteiro	Identificador do pagamento
IdBuilding · BuildingCode	inteiro · texto	O condomínio
DocumentId	texto	Número do documento de pagamento
DocumentDate	data	Data do pagamento
Supplier	objeto	O fornecedor pago
Amount	decimal	Valor pago
BankingFees	decimal	Encargos bancários. Pode vir a null
Adjustment	decimal	Acerto aplicado. Pode vir a null
AccountingReference	texto	Referência do lançamento contabilístico
HasFile	booleano	Existe comprovativo arquivado
SettledInvoices	lista	As faturas liquidadas, quando pedidas com include. null caso contrário

A ordem é da mais recente para a mais antiga.

As settledInvoices são o que liga um pagamento ao que foi pago — é por aí que se reconstrói o percurso de uma despesa.

Erros

Estado	Código	Quando
400	INVALID_CURSOR · UNSUPPORTED_INCLUDE	Cursor inválido, ou include diferente de settledInvoices
401 · 403		Ver Autenticação e Permissões
404	BUILDING_NOT_FOUND	Não existe condomínio com esse identificador

---

Registar um pagamento

POST /supplier-payments

Permissão · finance:write · aceita Idempotency-Key

Para um pagamento feito fora da aplicação, indicando as faturas que liquida.

Corpo

Campo	Tipo	Descrição
SupplierTaxId	inteiro	Contribuinte do fornecedor
IdSupplier	inteiro	Em alternativa, o identificador do GC
IdBuilding ou BuildingCode	inteiro / texto	O condomínio
DocumentId	texto	Número do documento de pagamento
PaymentDate	data	Data do pagamento
PaymentMode	texto	Obrigatório. check, transfer ou directDebit
PdfBase64	texto	Comprovativo, em base64
Lines	lista	Obrigatório. As faturas liquidadas

Cada linha de lines:

Campo	Tipo	Descrição
DocumentId	texto	O número do documento do fornecedor, não o identificador do GC
Amount	decimal	Valor imputado a essa fatura

Pedido

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/supplier-payments" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "SupplierTaxId": 501234567,
        "BuildingCode": "0012",
        "DocumentId": "PG 2026/331",
        "PaymentDate": "2026-09-30",
        "PaymentMode": "transfer",
        "Lines": [
          { "DocumentId": "FT 2026/1180", "Amount": 246.00 }
        ]
      }'

Resposta · 201

{ "Id": 2210 }

As faturas nomeiam-se pelo número do fornecedor

Cada linha identifica a fatura pelo DocumentId do fornecedor — o número que quem pagou tem em mãos — e não pelo identificador interno do GC. Assim não precisa de consultar nada antes de registar um pagamento.

Os modos de pagamento

Valor	Significado
check	Cheque
transfer	Transferência bancária
directDebit	Débito direto

Outro valor responde 400 INVALID_REFERENCE.

Erros

Estado	Código	Quando
400	INVALID_BODY · MISSING_FIELD	Corpo inválido, ou falta um campo obrigatório
400	INVALID_REFERENCE	O fornecedor não existe, ou o PaymentMode não é um dos três
400	INVOICE_NOT_FOUND	Uma fatura das linhas não existe nesse fornecedor e condomínio
401 · 403		Ver Autenticação e Permissões
404	BUILDING_NOT_FOUND	O condomínio não existe
409	INVOICE_ALREADY_SETTLED	Uma das faturas já estava liquidada
409	IDEMPOTENCY_KEY_REUSED	A chave já foi usada noutro pedido
422	BANK_ACCOUNT_NOT_DEFINED	O condomínio não tem conta bancária configurada para este modo
422	PAYMENT_NOT_CREATED	Não chegou a ser registado. Reporte

O INVOICE_ALREADY_SETTLED costuma significar que o pagamento já foi registado. Confirme antes de o tratar como falha.

O BANK_ACCOUNT_NOT_DEFINED depende de configuração do cliente na aplicação e não se resolve repetindo.

---

Registar o pagamento de um consumo

POST /supplier-payments/consumption

Permissão · finance:write · aceita Idempotency-Key

Água, eletricidade e gás. Como no registo da fatura, não se envia fornecedor nem condomínio: o ponto de entrega identifica o contrato. O modo é sempre débito direto, que é como estes se pagam.

Corpo

Campo	Tipo	Descrição
DeliveryPointCode	texto	Obrigatório. O ponto de entrega
PaymentDate	data	Data do pagamento
Lines	lista	Obrigatório. As faturas liquidadas, com DocumentId e Amount

Pedido

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/supplier-payments/consumption" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "DeliveryPointCode": "PT0002000012345678XY",
        "PaymentDate": "2026-09-25",
        "Lines": [
          { "DocumentId": "FT 2026/998877", "Amount": 87.43 }
        ]
      }'

Resposta · 201

{ "Id": 2211 }

Erros

Os mesmos do registo de pagamento, com DELIVERY_POINT_NOT_FOUND em vez de BUILDING_NOT_FOUND e sem PaymentMode.