Despesas

Registar despesas pagas diretamente por um condomínio, em caixa ou pelo banco, sem fatura de fornecedor. Por exemplo, impressões e envelopes, portes de correio ou pequenas compras.

Para uma despesa titulada por uma fatura de fornecedor, use as faturas de fornecedor.

O registo usa três listagens, todas com masterdata:read: as contas de despesa, as respetivas rubricas e as contas por onde o condomínio paga. Os condomínios vêm de /buildings.

Peça expenses:write e masterdata:read

A permissão expenses:write só dá acesso ao registo. Os identificadores que o registo exige (condomínio, conta, rubrica e conta de pagamento) vêm das listagens, que pedem masterdata:read.

Listar as contas de despesa

GET /expense-accounts

Permissão · masterdata:read

As contas onde se pode lançar uma despesa. Valem para todos os condomínios da empresa.

Pedido

bash

curl "https://servidor.exemplo/api/integrations/v1/acme/expense-accounts" \
  -H "ApiKey: $GC_API_KEY"

Resposta · `200`

Um array simples, sem envelope.

json

[
  { "Id": 412, "Account": "6226", "Description": "Comunicação", "RequiresCategory": true },
  { "Id": 430, "Account": "6262", "Description": "Despesas de representação", "RequiresCategory": false }
]

Campo	Tipo	Descrição
`Id`	inteiro	Identificador da conta. É o que se envia em `IdAccount`
`Account`	texto	Número da conta no plano de contas
`Description`	texto	Descrição da conta
`RequiresCategory`	booleano	A conta tem rubricas e uma despesa lançada nela tem de indicar uma

Erros

Estado	Código	Quando
`401` · `403`		Ver Autenticação e Permissões

Listar as rubricas

GET /expense-categories

Permissão · masterdata:read

Parâmetros

Parâmetro	Tipo	Por omissão	Descrição
`idAccount`	inteiro	todas	Só as rubricas desta conta

Pedido

bash

curl "https://servidor.exemplo/api/integrations/v1/acme/expense-categories?idAccount=412" \
  -H "ApiKey: $GC_API_KEY"

Resposta · `200`

json

[
  { "Id": 57, "Code": "01", "Description": "Correio e economato", "IdAccount": 412 },
  { "Id": 58, "Code": "02", "Description": "Telefone", "IdAccount": 412 }
]

Campo	Tipo	Descrição
`Id`	inteiro	Identificador da rubrica. É o que se envia em `IdCategory`
`Code`	texto	Código da rubrica
`Description`	texto	Descrição da rubrica
`IdAccount`	inteiro	A conta a que a rubrica pertence

Cada rubrica pertence a uma única conta, e só se pode usar com essa conta.

Erros

Estado	Código	Quando
`401` · `403`		Ver Autenticação e Permissões

Listar as contas de pagamento de um condomínio

GET /buildings/{idBuilding}/payment-accounts

Permissão · masterdata:read

As contas por onde o condomínio pode pagar uma despesa: as suas contas bancárias abertas e as contas de caixa.

Pedido

bash

curl "https://servidor.exemplo/api/integrations/v1/acme/buildings/12/payment-accounts" \
  -H "ApiKey: $GC_API_KEY"

Resposta · `200`

json

[
  { "Id": 1201, "Account": "12101", "Description": "Banco A - Ordem", "Kind": "bank", "IsDefault": true },
  { "Id": 1202, "Account": "12102", "Description": "Banco B - Ordem", "Kind": "bank", "IsDefault": false },
  { "Id": 111, "Account": "111", "Description": "Caixa", "Kind": "cash", "IsDefault": true }
]

Campo	Tipo	Descrição
`Id`	inteiro	Identificador da conta. É o que se envia em `IdPaymentAccount`
`Account`	texto	Número da conta no plano de contas
`Description`	texto	Descrição da conta
`Kind`	texto	`bank` ou `cash`
`IsDefault`	booleano	A conta usada quando a despesa não indica nenhuma. Há no máximo uma de cada tipo

As contas de caixa são as mesmas em todos os condomínios. As bancárias são as de cada condomínio.

Erros

Estado	Código	Quando
`401` · `403`		Ver Autenticação e Permissões
`404`	`BUILDING_NOT_FOUND`	Não existe condomínio com esse identificador

Registar uma despesa

POST /expenses

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

Envie sempre uma Idempotency-Key

O GC não deteta despesas repetidas: não existe um número de documento pelo qual se possa reconhecer uma despesa já lançada. Se um pedido expirar e o repetir sem chave, ou com uma chave nova, a despesa fica lançada duas vezes na contabilidade do condomínio.

Gere uma chave por despesa antes do primeiro envio e reutilize-a em todas as repetições. Ver Idempotência.

Uma despesa tem uma ou mais linhas, cada uma com a sua conta, rubrica, descrição e valor. O total é a soma das linhas e sai da conta de pagamento.

Corpo

Campo	Tipo	Descrição
`IdBuilding`	inteiro	Obrigatório. O condomínio
`DocumentId`	texto	Número do documento, quando existe. Aparece na descrição do lançamento
`DocumentDate`	data	Obrigatório. Data do documento. É a data do lançamento
`PaymentMode`	texto	Obrigatório. `cash`, `transfer` ou `check`
`IdPaymentAccount`	inteiro	A conta por onde se paga, de `/payment-accounts`. Sem ela, usa-se a que tem `IsDefault`
`AttachmentFileName`	texto	Nome do ficheiro. Obrigatório quando se envia o ficheiro
`AttachmentBase64`	texto	O documento, em base64
`Lines`	lista	Obrigatório. Pelo menos uma linha

Cada linha de Lines:

Campo	Tipo	Descrição
`IdAccount`	inteiro	Obrigatório. A conta de despesa, de `/expense-accounts`
`IdCategory`	inteiro	A rubrica, de `/expense-categories`. Obrigatória quando a conta tem `RequiresCategory`
`Description`	texto	Obrigatório. Descrição da despesa
`Amount`	decimal	Obrigatório. Valor, maior que zero, com IVA incluído

Pedido

bash

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/expenses" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "IdBuilding": 12,
        "DocumentId": "ECO 2026/10",
        "DocumentDate": "2026-10-31",
        "PaymentMode": "transfer",
        "AttachmentFileName": "economato-outubro.pdf",
        "AttachmentBase64": "JVBERi0xLjQK...",
        "Lines": [
          { "IdAccount": 412, "IdCategory": 57, "Description": "Impressões e envelopes de outubro", "Amount": 18.45 }
        ]
      }'

Resposta · `201`

json

{ "Id": 90321, "Reference": "2026/P/0412" }

Campo	Tipo	Descrição
`Id`	inteiro	Identificador do lançamento contabilístico
`Reference`	texto	Referência do lançamento, como aparece nos ecrãs e relatórios da aplicação

Os modos de pagamento

Valor	Significado	Paga por
`cash`	Caixa	Uma conta de caixa (`Kind` `cash`)
`transfer`	Transferência bancária	Uma conta bancária do condomínio (`Kind` `bank`)
`check`	Cheque	Uma conta bancária do condomínio (`Kind` `bank`)

O IdPaymentAccount tem de ser do tipo que o modo usa: uma conta de caixa num pagamento por transferência responde 400 INVALID_REFERENCE.

O documento

O ficheiro fica arquivado com o lançamento. Do nome enviado só se aproveita a extensão: o arquivo dá-lhe um nome próprio. Sem extensão, é tratado como PDF.

Erros

Estado	Código	Quando
`400`	`INVALID_BODY`	Corpo inválido, ou o ficheiro não é base64 válido
`400`	`MISSING_FIELD`	Falta um campo obrigatório, incluindo a rubrica numa conta que a exige. O `Field` diz qual, por exemplo `lines[0].idCategory`
`400`	`INVALID_REFERENCE`	O `PaymentMode` não é um dos três, a conta não é de despesa, a rubrica não pertence à conta da linha, ou a conta de pagamento não serve o condomínio nesse modo
`400`	`INVALID_AMOUNT`	Uma linha tem valor igual ou inferior a zero
`401` · `403`		Ver Autenticação e Permissões
`404`	`BUILDING_NOT_FOUND`	O condomínio não existe
`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 aberta, e o modo é `transfer` ou `check`
`422`	`EXERCISE_CLOSED`	A contabilidade do condomínio está fechada no mês da `DocumentDate`
`422`	`EXPENSE_NOT_CREATED`	Não chegou a ser registada. Reporte

Nos erros de uma linha, o Field indica a posição, a contar de zero: lines[1].idAccount é a conta da segunda linha.

A despesa é registada por inteiro ou não é registada: se uma linha falhar, nenhuma fica lançada.

O BANK_ACCOUNT_NOT_DEFINED e o EXERCISE_CLOSED dependem do estado do condomínio na aplicação. Repetir o pedido não os resolve.

Despesas ​

Listar as contas de despesa ​

Pedido ​

Resposta · 200 ​

Erros ​

Listar as rubricas ​

Parâmetros ​

Pedido ​

Resposta · 200 ​

Erros ​

Listar as contas de pagamento de um condomínio ​

Pedido ​

Resposta · 200 ​

Erros ​

Registar uma despesa ​

Corpo ​

Pedido ​

Resposta · 201 ​

Os modos de pagamento ​

O documento ​

Erros ​

Despesas

Listar as contas de despesa

Pedido

Resposta · `200`

Erros

Listar as rubricas

Parâmetros

Pedido

Resposta · `200`

Erros

Listar as contas de pagamento de um condomínio

Pedido

Resposta · `200`

Erros

Registar uma despesa

Corpo

Pedido

Resposta · `201`

Os modos de pagamento

O documento

Erros