Faturas de fornecedor

Consultar e registar faturas de fornecedores de um condomínio.

Listar as faturas de um condomínio

GET /buildings/{idBuilding}/supplier-invoices

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ó as faturas deste fornecedor
`fromDate`	data	—	Documentos a partir desta data
`toDate`	data	—	Documentos até esta data, inclusive
`include`	texto	—	`lines` para trazer as linhas de cada fatura
`limit`	inteiro	`100`	Registos por página, no máximo 500
`cursor`	texto	—	Cursor da página seguinte

Pedido

bash

curl "https://servidor.exemplo/api/integrations/v1/acme/buildings/12/supplier-invoices?include=lines&fromDate=2026-01-01" \
  -H "ApiKey: $GC_API_KEY"

Resposta · `200`

json

{
  "Items": [
    {
      "Id": 4412,
      "IdBuilding": 12,
      "BuildingCode": "0012",
      "DocumentId": "FT 2026/1180",
      "DocumentDate": "2026-09-10T00:00:00",
      "DueDate": "2026-10-10T00:00:00",
      "PeriodFrom": null,
      "PeriodTo": null,
      "DocumentType": { "Id": 1, "Description": "Fatura" },
      "TaxIncluded": true,
      "Supplier": { "Id": 88, "Description": "Elevadores Norte, Lda." },
      "SupplierTaxId": "501234567",
      "Amount": 246.0,
      "ExpenseAmount": 200.0,
      "OutstandingAmount": 246.0,
      "Settled": false,
      "AccountingReference": "2026/A/442",
      "HasFile": true,
      "Lines": [
        {
          "Id": 9901,
          "Description": "Manutenção mensal de elevadores - Setembro",
          "Amount": 246.0,
          "TaxPercentage": 23.0,
          "Account": "6226",
          "AccountDescription": "Conservação e reparação",
          "Category": { "Id": 5, "Description": "Elevadores" }
        }
      ]
    }
  ],
  "Paging": { "Limit": 100, "NextCursor": null, "HasMore": false }
}

Campo	Tipo	Descrição
`Id`	inteiro	Identificador da fatura no GC
`IdBuilding` · `BuildingCode`	inteiro · texto	O condomínio
`DocumentId`	texto	Número do documento do fornecedor
`DocumentDate`	data	Data do documento
`DueDate`	data	Vencimento
`PeriodFrom` · `PeriodTo`	data	Período a que respeita, nas faturas de consumo
`DocumentType`	objeto	Tipo de documento — fatura, nota de crédito, consumo
`TaxIncluded`	booleano	O tipo de documento inclui IVA
`Supplier`	objeto	O fornecedor
`SupplierTaxId`	texto	Contribuinte do fornecedor
`Amount`	decimal	Total do documento, com IVA
`ExpenseAmount`	decimal	Valor lançado em contas de gasto — o custo que o condomínio suporta
`OutstandingAmount`	decimal	Por liquidar
`Settled`	booleano	Se está totalmente liquidada
`AccountingReference`	texto	Referência do lançamento contabilístico
`HasFile`	booleano	O documento do fornecedor está arquivado
`Lines`	lista	As linhas, quando pedidas com `include=lines`. `null` caso contrário

A ordem é da mais recente para a mais antiga.

O valor sem IVA

A API devolve o total com IVA em Amount. O valor líquido deriva-se das linhas, cada uma com a sua taxa:

const net = invoice.Lines.reduce(
    (total, line) => total + line.Amount / (1 + line.TaxPercentage / 100), 0)

Repare que TaxIncluded diz se o tipo de documento já inclui IVA — quando for false, line.Amount já é o valor líquido e a divisão não se aplica.

Uma fatura não se liga a uma ocorrência

Não existe relação entre uma fatura e a ocorrência que lhe deu origem. Se precisa de relacionar custo com ocorrência, mantenha essa ligação do seu lado a partir do momento em que adjudica o trabalho.

Erros

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

Obter uma fatura

GET /supplier-invoices/{idSupplierInvoice}

Permissão · finance:read

Parâmetros

Parâmetro	Tipo	Descrição
`idSupplierInvoice`	inteiro	No caminho
`include`	texto	`lines` para trazer as linhas

Pedido

bash

curl "https://servidor.exemplo/api/integrations/v1/acme/supplier-invoices/4412?include=lines" \
  -H "ApiKey: $GC_API_KEY"

Erros

Estado	Código	Quando
`400`	`UNSUPPORTED_INCLUDE`	`include` diferente de `lines`
`401` · `403`		Ver Autenticação e Permissões
`404`	`INVOICE_NOT_FOUND`	Não existe fatura com esse identificador

Registar uma fatura

POST /supplier-invoices

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

Para um fornecedor que envia as suas faturas por via eletrónica. A fatura entra no GC já lançada na contabilidade do condomínio.

Corpo

Campo	Tipo	Descrição
`SupplierTaxId`	inteiro	Contribuinte do fornecedor. É por aqui que é reconhecido
`IdSupplier`	inteiro	Em alternativa ao contribuinte, o identificador do GC
`IdBuilding` ou `BuildingCode`	inteiro / texto	O condomínio
`DocumentId`	texto	Obrigatório. Número do documento do fornecedor
`DocumentDate`	data	Data do documento
`DocumentDueDate`	data	Vencimento
`IsInvoice`	booleano	`true` numa fatura, `false` numa nota de crédito
`Amount`	decimal	Total do documento
`PdfBase64`	texto	Obrigatório. O documento, em base64
`Lines`	lista	Obrigatório. Pelo menos uma linha

Cada linha de lines:

Campo	Tipo	Descrição
`ProductCode`	texto	Código do artigo, mapeado para uma conta neste fornecedor
`Description`	texto	Descrição da linha
`Quantity`	inteiro	Quantidade
`Amount`	decimal	Valor da linha

Pedido

bash

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/supplier-invoices" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "SupplierTaxId": 501234567,
        "BuildingCode": "0012",
        "DocumentId": "FT 2026/1180",
        "DocumentDate": "2026-09-10",
        "DocumentDueDate": "2026-10-10",
        "IsInvoice": true,
        "Amount": 246.00,
        "PdfBase64": "JVBERi0xLjQK...",
        "Lines": [
          {
            "ProductCode": "MAN-ELEV",
            "Description": "Manutenção mensal de elevadores - Setembro",
            "Quantity": 1,
            "Amount": 246.00
          }
        ]
      }'

Resposta · `201`

json

{ "Id": 4412, "Reference": "2026/A/442" }

O Reference é a referência contabilística pela qual a fatura passa a ser conhecida no GC — não o número do documento, que já era seu.

Os códigos de artigo têm de estar mapeados

Cada ProductCode tem de corresponder a uma conta configurada para esse fornecedor. Um código não mapeado responde 400 INVALID_REFERENCE em vez de ser lançado numa conta errada — o que seria pior.

Combine os códigos com a empresa antes de começar a enviar, e tenha em conta que são por fornecedor.

Erros

Estado	Código	Quando
`400`	`INVALID_BODY`	Corpo inválido, ou `PdfBase64` não é base64 válido
`400`	`MISSING_FIELD`	Falta `DocumentId`, o documento, ou as linhas
`400`	`INVALID_REFERENCE`	O fornecedor não existe, ou um `ProductCode` não está mapeado
`401` · `403`		Ver Autenticação e Permissões
`404`	`BUILDING_NOT_FOUND`	O condomínio não existe, por identificador nem por código
`409`	`DOCUMENT_ALREADY_EXISTS`	Já existe documento com esse número, desse fornecedor, nesse condomínio
`409`	`IDEMPOTENCY_KEY_REUSED`	A chave já foi usada noutro pedido
`422`	`INVOICE_NOT_CREATED`	Não chegou a ser registada. Reporte

O DOCUMENT_ALREADY_EXISTS normalmente significa que a fatura já entrou. Confirme antes de a tratar como falha.

Registar uma fatura de consumo

POST /supplier-invoices/consumption

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

Água, eletricidade e gás. Aqui não se envia fornecedor nem condomínio: o ponto de entrega identifica o contrato, e o contrato já diz de quem é e a que condomínio pertence.

Corpo

Campo	Tipo	Descrição
`DeliveryPointCode`	texto	Obrigatório. O código do ponto de entrega (CPE, CUI)
`DocumentId`	texto	Obrigatório. Número do documento
`CorrectedDocumentId`	texto	Numa nota de crédito, a fatura que corrige
`DocumentDate`	data	Data do documento
`DocumentDueDate`	data	Vencimento
`PeriodFrom` · `PeriodTo`	data	Período de consumo
`IsInvoice`	booleano	`true` numa fatura, `false` numa nota de crédito
`Amount`	decimal	Total
`PdfBase64`	texto	Obrigatório. O documento, em base64

Não há linhas: a conta e a categoria vêm do contrato do ponto de entrega.

Pedido

bash

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/supplier-invoices/consumption" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "DeliveryPointCode": "PT0002000012345678XY",
        "DocumentId": "FT 2026/998877",
        "DocumentDate": "2026-09-05",
        "DocumentDueDate": "2026-09-25",
        "PeriodFrom": "2026-08-01",
        "PeriodTo": "2026-08-31",
        "IsInvoice": true,
        "Amount": 87.43,
        "PdfBase64": "JVBERi0xLjQK..."
      }'

Resposta · `201`

json

{ "Id": 4413, "Reference": "2026/A/443" }

Numa nota de crédito, dê CorrectedDocumentId

Sem ele, a nota de crédito fica em aberto na conta do fornecedor em vez de acertar a fatura que corrige.

Erros

Estado	Código	Quando
`400`	`INVALID_BODY` · `MISSING_FIELD`	Corpo inválido, ou falta um campo obrigatório
`400`	`DELIVERY_POINT_NOT_FOUND`	Nenhum contrato de consumo tem esse ponto de entrega
`401` · `403`		Ver Autenticação e Permissões
`409`	`DOCUMENT_ALREADY_EXISTS`	Documento já registado
`409`	`IDEMPOTENCY_KEY_REUSED`	A chave já foi usada noutro pedido
`422`	`INVOICE_NOT_CREATED`	Não chegou a ser registada. Reporte

Faturas de fornecedor ​

Listar as faturas de um condomínio ​

Parâmetros ​

Pedido ​

Resposta · 200 ​

O valor sem IVA ​

Erros ​

Obter uma fatura ​

Parâmetros ​

Pedido ​

Erros ​

Registar uma fatura ​

Corpo ​

Pedido ​

Resposta · 201 ​

Erros ​

Registar uma fatura de consumo ​

Corpo ​

Pedido ​

Resposta · 201 ​

Erros ​

Faturas de fornecedor

Listar as faturas de um condomínio

Parâmetros

Pedido

Resposta · `200`

O valor sem IVA

Erros

Obter uma fatura

Parâmetros

Pedido

Erros

Registar uma fatura

Corpo

Pedido

Resposta · `201`

Erros

Registar uma fatura de consumo

Corpo

Pedido

Resposta · `201`

Erros