Guia de integração — Conta corrente CRM
Conceitos
Cliente (entityKeyId)
Identificador textual do cliente (até 25 caracteres). Ambos os endpoints usam este valor como keyId na rota.
Saldo por escalões de vencimento
Resposta de balance-aging: saldo total em aberto do cliente, repartido por períodos de atraso (como na ficha de entidade: Total, Não vencido, Até 30 dias, 31 a 60 dias, etc.), mais pontos de fidelização:
| Campo | Descrição |
|---|---|
balance | Total (saldo líquido em aberto) |
notDue | Não vencido |
overdue0To30 | Até 30 dias |
overdue31To60 | 31 a 60 dias |
overdue61To90 | 61 a 90 dias |
overdueOver90 | Mais de 90 dias |
points | Pontos de fidelização |
Saldo do cliente
| Método | URL | Descrição |
|---|---|---|
| GET | /gateway/entity/{keyId}/balance-aging | Devolve saldo por períodos de atraso e pontos, sem reconstruir movimentos |
| POST | /gateway/entity/{keyId}/balance-aging/recalculate | Reconstrói a conta corrente e devolve o saldo recalculado |
Parâmetro de rota: keyId — entityKeyId do cliente (codificar caracteres especiais na URL se necessário).
Use GET para leitura rápida do saldo já calculado. Use POST recalculate quando movimentos recentes possam não estar reflectidos (por exemplo, após liquidações ou lançamentos na conta corrente).
Resposta (200 OK)
{
"balance": 1250.5,
"notDue": 800,
"overdue0To30": 200.5,
"overdue31To60": 150,
"overdue61To90": 100,
"overdueOver90": 0,
"points": 42.5
}
Exemplos
Consultar saldo
GET /gateway/entity/CLI001/balance-aging
Recalcular saldo
POST /gateway/entity/CLI001/balance-aging/recalculate
Fluxo recomendado
- Identificar o cliente — obter
entityKeyId. - Consultar posição —
GET /gateway/entity/{keyId}/balance-aging. - Actualizar saldo —
POST /gateway/entity/{keyId}/balance-aging/recalculatequando necessário reflectir movimentos recentes.
Erros frequentes
| Código HTTP | Situação | Acção sugerida |
|---|---|---|
| 401 | Token em falta ou inválido | Autenticar no gateway |
| 404 | keyId inexistente | Confirmar entityKeyId do cliente |
As respostas de erro seguem o padrão Problem Details da API.
Conclusão
A conta corrente CRM expõe consulta e recálculo do saldo por escalões de vencimento em /gateway/entity/{keyId}/balance-aging. Consulte com GET e recalcule com POST quando a posição financeira do cliente precisar de ser actualizada.
Última actualização: 2 de Junho de 2026