Guia de Debitar Avenças

Rotas:

• Listagem: GET /gateway/debit-agreement
• Processar: POST /gateway/debit-agreement/save
• Ignorar: POST /gateway/debit-agreement/ignore

---

Autenticação: token Bearer (JWT) e contexto de tenant — ver Login Combinado

Visão Geral

Debitar Avenças é o passo operacional que segue a configuração dos Modelos de Avenças. Depois de os modelos serem criados e associados a Entidades, este módulo permite:

1. Listar todas as associações com vencimento até uma data indicada
2. Processar as avenças selecionadas — gerando os documentos de venda correspondentes e avançando a Próxima Data
3. Ignorar as avenças selecionadas — saltando a ocorrência atual e avançando a Próxima Data sem criar documento

O fluxo de débito cobre três operações: listar as avenças com vencimento, processá-las para gerar documentos, e ignorá-las para saltar uma ocorrência.

---

Fluxo de Trabalho

---

Passo 1 — Listar Avenças com Vencimento

Devolve todas as associações de avenças cuja Próxima Data seja igual ou anterior à Data de Processamento indicada.

GET /gateway/debit-agreement?processDate={data}
Authorization: Bearer {token}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
processDate	datetime	✅ Sim	Data de corte. Apenas avenças com NextDate ≤ processDate são devolvidas
customerInitial	string	Não	Filtra avenças a partir do cliente com este ID
customerFinal	string	Não	Filtra avenças até ao cliente com este ID
page	int	Não	Página de resultados a devolver. A página padrão é 1
pageSize	int	Não	Número de registos por página

Exemplo — Todas as Avenças com Vencimento Até ao Fim do Mês

GET /gateway/debit-agreement?processDate=2026-01-31T23:59:59
Authorization: Bearer {token}

Exemplo — Com Intervalo de Entidades e Paginação

GET /gateway/debit-agreement?processDate=2026-01-31T23:59:59&customerInitial=1&customerFinal=100&page=1&pageSize=50
Authorization: Bearer {token}

Resposta 200 OK

{
  "totalCount": 3,
  "pageSize": 50,
  "currentPage": 1,
  "totalPages": 1,
  "data": [
    {
      "customerCovenantAgreementId": "a1b2c3d4-1111-2222-3333-aabbccddeeff",
      "covenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Suporte Mensal TI",
      "description": "Contrato mensal de suporte e manutenção informática",
      "extraReference": null,
      "extraReference2": null,
      "entityKeyId": "1",
      "entityName": "Acme Tecnologias, Lda",
      "documentSerieDescription": "FT 2026",
      "documentTypeDescription": "Fatura",
      "lastProcessDate": "2025-12-31T00:00:00",
      "nextDate": "2026-01-31T00:00:00",
      "documentNumber": "",
      "totalAmount": null,
      "finalDate": "2026-12-31T00:00:00"
    },
    {
      "customerCovenantAgreementId": "b5c6d7e8-4444-5555-6666-112233445566",
      "covenantId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Pacote de Manutenção Anual TI",
      "description": "Pacote anual de manutenção de hardware e software",
      "extraReference": null,
      "extraReference2": null,
      "entityKeyId": "2",
      "entityName": "TechVision Solutions",
      "documentSerieDescription": "FT 2026",
      "documentTypeDescription": "Fatura",
      "lastProcessDate": "2025-01-31T00:00:00",
      "nextDate": "2026-01-31T00:00:00",
      "documentNumber": "",
      "totalAmount": null,
      "finalDate": null
    }
  ]
}

Campos da Listagem

Campo	Descrição
customerCovenantAgreementId	ID único da associação Entidade-Avença — usado nas chamadas de Guardar/Ignorar
covenantId	ID do modelo de avença
name	Nome do modelo de avença
description	Descrição do modelo
extraReference / extraReference2	Referências extra opcionais da associação
entityKeyId	ID da Entidade/Cliente
entityName	Nome da Entidade/Cliente
documentSerieDescription	Descrição da série de documento
documentTypeDescription	Descrição do tipo de documento
lastProcessDate	Última data em que esta associação foi processada ou ignorada
nextDate	Próxima data de vencimento para processamento
documentNumber	Preenchido após o processamento com o número do documento gerado
totalAmount	Preenchido após o processamento com o total do documento
finalDate	Data de fim da associação (null = indefinida)

---

Passo 2 — Processar Avenças (Guardar)

Cria documentos de venda para as avenças selecionadas e avança a Próxima Data para a próxima ocorrência programada.

POST /gateway/debit-agreement/save
Content-Type: application/json
Authorization: Bearer {token}
Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Idempotência

A idempotência garante que reenviar o mesmo pedido não gera documentos duplicados. Inclua um GUID único no header Idempotency-Key em cada operação.

Corpo do Pedido

{
  "processDate": "2026-01-31T00:00:00",
  "documentDate": "2026-01-31T00:00:00",
  "loadDate": "2026-01-31T00:00:00",
  "customerCovenantAgreementIds": [
    "a1b2c3d4-1111-2222-3333-aabbccddeeff",
    "b5c6d7e8-4444-5555-6666-112233445566"
  ]
}

Campos do Pedido

Campo	Tipo	Obrigatório	Descrição
processDate	datetime	✅ Sim	Data de referência para determinar as avenças com vencimento
documentDate	datetime	✅ Sim	Data oficial a registar nos documentos gerados
loadDate	datetime	✅ Sim	Data de carga/expedição — deve ser ≥ documentDate
customerCovenantAgreementIds	string[]	✅ Sim	Lista não vazia de valores CustomerCovenantAgreementId únicos, obtidos da listagem

Resposta 200 OK

{
  "successCount": 2,
  "failureCount": 0,
  "results": [
    {
      "customerCovenantAgreementId": "a1b2c3d4-1111-2222-3333-aabbccddeeff",
      "success": true,
      "newNextDate": "2026-02-28T00:00:00",
      "lastProcessDate": "2026-01-31T00:00:00",
      "documentNumber": "FT 2026/1",
      "documentId": 10042,
      "totalAmount": 184.50,
      "errorMessage": null
    },
    {
      "customerCovenantAgreementId": "b5c6d7e8-4444-5555-6666-112233445566",
      "success": true,
      "newNextDate": "2027-01-31T00:00:00",
      "lastProcessDate": "2026-01-31T00:00:00",
      "documentNumber": "FT 2026/2",
      "documentId": 10043,
      "totalAmount": 922.50,
      "errorMessage": null
    }
  ]
}

Exemplo de Falha Parcial

Se uma avença falhar, as restantes continuam a ser processadas. A entrada falhada tem success: false e uma errorMessage:

{
  "successCount": 1,
  "failureCount": 1,
  "results": [
    {
      "customerCovenantAgreementId": "a1b2c3d4-1111-2222-3333-aabbccddeeff",
      "success": true,
      "newNextDate": "2026-02-28T00:00:00",
      "lastProcessDate": "2026-01-31T00:00:00",
      "documentNumber": "FT 2026/1",
      "documentId": 10042,
      "totalAmount": 184.50,
      "errorMessage": null
    },
    {
      "customerCovenantAgreementId": "b5c6d7e8-4444-5555-6666-112233445566",
      "success": false,
      "newNextDate": null,
      "lastProcessDate": null,
      "documentNumber": null,
      "documentId": null,
      "totalAmount": null,
      "errorMessage": "CustomerCovenantAgreement not found."
    }
  ]
}

Campos do Resultado

Campo	Descrição
customerCovenantAgreementId	ID da associação processada
success	Indica se esta avença foi processada com sucesso
newNextDate	Próxima data de vencimento após este ciclo de processamento
lastProcessDate	Data registada como última data de processamento
documentNumber	Número do documento gerado (ex.: "FT 2026/1")
documentId	ID interno do documento gerado
totalAmount	Montante total do documento gerado
errorMessage	Detalhes do erro se success for false

---

Passo 3 — Ignorar Avenças (Saltar)

Avança a Próxima Data para a próxima ocorrência programada sem criar qualquer documento. Útil quando um ciclo de faturação precisa de ser saltado num determinado período.

POST /gateway/debit-agreement/ignore
Content-Type: application/json
Authorization: Bearer {token}
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

Idempotência

Inclua um GUID único no header Idempotency-Key para evitar que a mesma ocorrência seja ignorada mais do que uma vez.

Corpo do Pedido

{
  "processDate": "2026-01-31T00:00:00",
  "customerCovenantAgreementIds": [
    "c9d0e1f2-7777-8888-9999-aabbccddeeff"
  ]
}

Campos do Pedido

Campo	Tipo	Obrigatório	Descrição
processDate	datetime	✅ Sim	Data de referência usada para calcular a próxima data de vencimento
customerCovenantAgreementIds	string[]	✅ Sim	Lista não vazia de valores CustomerCovenantAgreementId únicos

Resposta 200 OK

{
  "successCount": 1,
  "failureCount": 0,
  "results": [
    {
      "customerCovenantAgreementId": "c9d0e1f2-7777-8888-9999-aabbccddeeff",
      "success": true,
      "newNextDate": "2026-02-28T00:00:00",
      "lastProcessDate": "2026-01-31T00:00:00",
      "errorMessage": null
    }
  ]
}

Campos do Resultado

Campo	Descrição
customerCovenantAgreementId	ID da associação ignorada
success	Indica se a operação de ignorar foi bem-sucedida
newNextDate	Próxima data de vencimento após saltar esta ocorrência
lastProcessDate	Data registada como última data de processamento (mesmo sem documento criado)
errorMessage	Detalhes do erro se success for false

---

Cálculo da Próxima Data

Após cada Guardar ou Ignorar, a Próxima Data é recalculada automaticamente com base na configuração de periodicidade da avença:

Tipo de Periodicidade	Lógica de Cálculo
Diário (1)	Avança para o próximo dia cujo bit de dia da semana esteja definido em periodicityValue (bitmask)
Semanal (2)	Avança periodicityValue × 7 dias, alinhado com a initialDate
Mensal (3)	Avança periodicityValue meses, alinhado com o dia da initialDate
Anual (4)	Avança periodicityValue anos

Alinhamento mensal

Para periodicidades mensais e semanais, a Próxima Data está sempre alinhada com o dia da Data Inicial original. Por exemplo, se Data Inicial for 2026-01-15 e a periodicidade for mensal, a Próxima Data cairá sempre no dia 15 de cada mês.

Referência do Bitmask Diário

O mesmo bitmask de dias da semana usado na criação dos modelos de avenças:

Valor	Dia
1	Domingo
2	Segunda-feira
4	Terça-feira
8	Quarta-feira
16	Quinta-feira
32	Sexta-feira
64	Sábado

Exemplo: Segunda a Sexta = 2+4+8+16+32 = 62

---

Regras de Validação

Comando Guardar

Regra	Descrição
processDate obrigatório	Não pode estar vazio ou ser o valor predefinido
documentDate obrigatório	Não pode estar vazio ou ser o valor predefinido
loadDate obrigatório	Não pode estar vazio ou ser o valor predefinido
loadDate ≥ documentDate	A data de carga deve ser igual ou posterior à data do documento
customerCovenantAgreementIds obrigatório	Deve ter pelo menos um ID
IDs não vazios	Cada ID na lista deve ser uma string não vazia
IDs únicos	Não pode haver IDs duplicados no mesmo pedido

Comando Ignorar

Regra	Descrição
processDate obrigatório	Não pode estar vazio ou ser o valor predefinido
customerCovenantAgreementIds obrigatório	Deve ter pelo menos um ID
IDs não vazios	Cada ID na lista deve ser uma string não vazia
IDs únicos	Não pode haver IDs duplicados no mesmo pedido

---

Respostas de Erro

Listagem

Código HTTP	Descrição
401	Não autorizado — token inválido ou em falta
500	Erro interno do servidor

Guardar / Ignorar

Código HTTP	Descrição
400	Erro de validação — consulte as regras de validação acima
401	Não autorizado — token inválido ou em falta
404	Um ou mais valores de CustomerCovenantAgreementId não encontrados
500	Erro interno do servidor

Erros ao nível da avença vs erros ao nível do pedido

Um 404 ao nível HTTP significa que o pedido completo foi rejeitado (ex.: nenhum dos IDs foi encontrado ou o pedido estava malformado).
Falhas individuais de avenças dentro de um pedido válido são reportadas em results[].success = false com results[].errorMessage, enquanto a resposta HTTP permanece 200 OK.

---

Boas Práticas

✅ Recomendado

• Chamar sempre o endpoint de listagem primeiro com a processDate alvo para identificar o que está com vencimento
• Usar customerInitial / customerFinal para processar grandes volumes em lotes mais pequenos
• Verificar results[].success por avença — uma resposta 200 OK não garante que todas as avenças foram processadas
• Retentar apenas os customerCovenantAgreementIds falhados (aqueles com success: false) para evitar duplicar entradas já processadas
• Usar chaves de idempotência ao retentar para evitar geração de documentos duplicados
• Confirmar que loadDate ≥ documentDate antes de submeter o comando de guardar

❌ Evitar

• Submeter todas as avenças num único lote massivo — preferir paginação ou processamento por intervalos
• Assumir que 200 OK significa sucesso total — verificar sempre failureCount e os resultados individuais
• Enviar customerCovenantAgreementIds duplicados no mesmo pedido (bloqueado pela validação)
• Usar processDate além da finalDate da avença — as associações após a data de fim não aparecem na listagem

---

Cenários Comuns

Processamento de Fim de Mês

Processar todas as avenças com vencimento até ao último dia do mês:

1. Listar: GET /gateway/debit-agreement?processDate=2026-01-31T23:59:59
2. Recolher o customerCovenantAgreementId de todos os itens devolvidos
3. Guardar: POST /gateway/debit-agreement/save com todos os IDs recolhidos

Processamento Seletivo com Exceções

Processar a maioria das avenças mas saltar a avença de um cliente específico este mês:

1. Listar: Obter todas as avenças com vencimento
2. Separar: Identificar IDs a saltar (ignore) vs a processar (save)
3. Ignorar: POST /gateway/debit-agreement/ignore com os IDs a saltar
4. Guardar: POST /gateway/debit-agreement/save com os IDs restantes

Grande Volume — Processamento por Intervalos de Entidades

Para tenants com milhares de avenças, processar por intervalos:

Lote 1: GET /gateway/debit-agreement?processDate=...&customerInitial=1&customerFinal=500
Lote 2: GET /gateway/debit-agreement?processDate=...&customerInitial=501&customerFinal=1000
Lote 3: ...

---

Integração com os Modelos de Avenças

O processo de débito lê a configuração da avença no momento do processamento:

• documentType e documentSerie — determinam o tipo e série de documento a usar
• periodicityType e periodicityValue — usados para calcular a nova NextDate
• items — copiados diretamente para as linhas do documento gerado
• priceType, withTax, ignoreCustomerDiscount — aplicados durante o cálculo de preços do documento

Snapshot vs Dados em Direto

O documento gerado captura os preços e configuração dos artigos da avença no momento do processamento. Alterações subsequentes ao modelo de avença não afetam retroativamente os documentos já processados.

---

Guias Relacionados

• Guia de Modelos de Avenças — Criar e configurar templates de faturação recorrente
• Guia de Utilização Geral — Autenticação e padrões comuns

---

Última actualização: 2 de junho de 2026