Referência

Avenças

A facturação recorrente: um cliente, um valor e uma periodicidade. O sistema emite a factura de cada ciclo; nunca cobra sozinho.

Operação	O que faz
GET `/api/avencas`	Lista as avenças (facturação recorrente).
POST `/api/avencas`	Cria uma avença.
GET `/api/avencas/{id}/historico`	O histórico de uma avença: as facturas que já gerou.
POST `/api/avencas/{id}/pausar`	Pausa uma avença: deixa de emitir até ser retomada.
POST `/api/avencas/{id}/retomar`	Retoma uma avença pausada.
POST `/api/avencas/{id}/cancelar`	Cancela uma avença: não volta a emitir. As facturas já emitidas mantêm-se.
POST `/api/avencas/gerar-pendentes`	Emite agora todas as facturas das avenças que estão por emitir.

GET/api/avencas#

Lista as avenças (facturação recorrente).

Permissão Documentos.AvencasLer

A resposta é uma página: itens e proximoCursor. Ver Paginação.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`cursor`	na pesquisa	texto
`tamanho`	na pesquisa	número inteiro

Pedido

curl

curl 'https://<endereço-da-API>/api/avencas' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/avencas#

Cria uma avença.

Permissão Documentos.AvencasCriar
Idempotência aceita Idempotency-Key

Devolve o id. O sistema emite a factura de cada ciclo; nunca cobra sozinho.

Corpo do pedido (JSON · CriarAvencaCommand)

Campo	Tipo	Obrigatório	Significado
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`frequencia`	uma de: «Mensal», «Trimestral», «Semestral», «Anual»	sim
`diaEmissao`	número inteiro	sim
`prazoPagamentoDias`	número inteiro	sim
`dataInicio`	data (AAAA-MM-DD)	sim
`dataFim`	data (AAAA-MM-DD) ou nulo
`enviarEmail`	verdadeiro/falso	sim
`observacao`	texto ou nulo		O texto livre.
`linhas`	lista de objectos	sim
`linhas[].produtoId`	identificador (UUID) ou nulo		O artigo.
`linhas[].descricao`	texto	sim	A descrição.
`linhas[].quantidade`	número	sim	A quantidade.
`linhas[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`linhas[].impostoId`	identificador (UUID) ou nulo
`linhas[].motivoIsencaoIvaId`	identificador (UUID) ou nulo
`linhas[].taxaRetencaoId`	identificador (UUID) ou nulo
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/avencas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "clienteId": "00000000-0000-0000-0000-000000000000",
  "frequencia": "Mensal",
  "diaEmissao": 1,
  "prazoPagamentoDias": 1,
  "dataInicio": "2026-10-12",
  "enviarEmail": false,
  "linhas": [
    {
      "descricao": "texto",
      "quantidade": 0,
      "precoUnitario": 0
    }
  ]
}'

GET/api/avencas/{id}/historico#

O histórico de uma avença: as facturas que já gerou.

Permissão Documentos.AvencasLer

A resposta é uma página: itens e proximoCursor. Ver Paginação.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`cursor`	na pesquisa	texto
`tamanho`	na pesquisa	número inteiro

Pedido

curl

curl 'https://<endereço-da-API>/api/avencas/<id>/historico' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/avencas/{id}/pausar#

Pausa uma avença: deixa de emitir até ser retomada.

Permissão Documentos.AvencasGerir

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/avencas/<id>/pausar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/avencas/{id}/retomar#

Retoma uma avença pausada.

Permissão Documentos.AvencasGerir

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/avencas/<id>/retomar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/avencas/{id}/cancelar#

Cancela uma avença: não volta a emitir. As facturas já emitidas mantêm-se.

Permissão Documentos.AvencasGerir

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/avencas/<id>/cancelar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/avencas/gerar-pendentes#

Emite agora todas as facturas das avenças que estão por emitir.

Permissão Documentos.AvencasGerir

Pode demorar (uma factura por ciclo em atraso). Emite em nome de quem criou cada avença.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/avencas/gerar-pendentes' \
  -H 'X-Api-Key: <a-sua-chave>'