Protección (com.ProteccionApp): wiring pension & cesantías reads into a daily data feed

Reachable surfaces (and what stays out)

Protección's consumer surface is the official Android/iOS app plus the Portal Afiliados web channel. Under explicit affiliate consent, both expose the same read perimeter. The scope below is what we treat as in-bounds for an ingestion build; anything beyond is left alone.

• Pensión Obligatoria — balance, fund choice (conservador / moderado / mayor riesgo / programado), latest contribution date, employer-tagged movement lines.
• Pensión Voluntaria / +Protección — voluntary plan balance, alternative-by-alternative composition, contributions and withdrawals timeline.
• Cesantías — balance, employer-by-employer breakdown, withdrawal status from the online retirement/withdrawal portal (per the app's store description).
• Certifácil PDFs — afiliación a Pensión Obligatoria, afiliación a Cesantías, aportes y retenciones de cesantías, certificado como pensionado, generated on demand and emailed or downloaded (per the proteccion.com Certifácil page).
• Pension-request status — tracking for old-age and disability pension applications, mirrored from the Seguimiento a mi solicitud de pensión view in the affiliate portal.

Out of bounds for this build: any write that moves money or changes the affiliate's fund, scraping aggregate fund-performance numbers Protección publishes for the market, and anything that would touch another affiliate's record.

What ships in the build

The output is concrete software, not a memo. Order of priority:

1. Runnable Python (3.11) and Node (20) source — a small library that authenticates against the affiliate channel under the user's consent, pulls the snapshot for the requested products, returns a normalised JSON payload, and writes the raw response next to it for replay.
2. Sync & freshness design — a scheduler module with the freshness windows from the snapshot row, plus a single /refresh endpoint that fires an on-demand pull and updates your store under the same consent token.
3. Reconciliation logic — snapshot diffing per (affiliate, product, captured_at), typed alerts for balance jumps outside tolerance, missing-product detection, and a freshness SLO check that raises before a downstream consumer reads stale data.
4. Automated test harness — recorded-fixture tests covering each product surface, a contract test that fails when the upstream JSON shape drifts, and a smoke test wired for CI.
5. Secondary, on request: an OpenAPI description of the shipped contract, a one-page authentication-flow note, and a short compliance memo aligned to the Finanzas Abiertas trajectory under Decreto 0368/2026.

Sample call against the shipped contract

The hosted variant exposes one endpoint per product family, plus a certificate retrieval call. Calls are scoped by the consent token issued when the affiliate authorises the link.

# Python 3.11
from openfinance_lab import ProteccionClient

cli = ProteccionClient(consent_token=CONSENT)

# 1) Pension + cesantías snapshot for one affiliate, single round trip
snap = cli.snapshot(products=["pension_obligatoria",
                              "pension_voluntaria",
                              "cesantias"],
                    freshness="1h")     # accept up to 1h-old cached snapshot

print(snap["pension_obligatoria"]["balance_cop"],
      snap["pension_obligatoria"]["fund"],          # e.g. "moderado"
      snap["captured_at"])                          # ISO-8601, COT

# 2) Force a fresh read (on-demand refresh path)
fresh = cli.refresh(products=["cesantias"])

# 3) Pull a Certifácil PDF by type (afiliacion | aportes_retenciones | pensionado)
pdf = cli.certificate(kind="aportes_retenciones", year=2025)
open("cert.pdf", "wb").write(pdf.bytes)

# Response shape (truncated)
# {
#   "affiliate_id": "CO-CC-...redacted...",
#   "captured_at": "2026-05-31T02:14:07-05:00",
#   "pension_obligatoria": {"balance_cop": 184320500, "fund": "moderado",
#                           "last_contribution": "2026-05-15"},
#   "cesantias": {"balance_cop": 6420100,
#                 "employers": [{"nit": "...", "balance_cop": 6420100}]},
#   "pension_voluntaria": {"balance_cop": 21500000,
#                          "alternatives": [{"name": "+Protección Moderado",
#                                            "balance_cop": 21500000}]}
# }

Where teams plug this in

• Retirement-planning dashboards — pull all three Protección balances daily, blend with the user's other AFP or Colpensiones data, and show a single net retirement position.
• Cesantías-backed lending — on application, fire /refresh for cesantías, ingest the latest aportes-y-retenciones PDF as proof, and run affordability against captured_at < 15 minutes.
• Employer HR portals — for the employer-tagged movement lines on cesantías, drive a periodic reconciliation against the employer's own contribution records to catch posting gaps before payroll closes.
• Tax season prep — schedule a one-shot January pull of the certificado de aportes y retenciones for every consenting user, store the PDFs, and surface them in-product.

Freshness, reconciliation & failure modes

The ingestion layer is built around three knobs the consumer controls:

• Freshness window — per call, the consumer declares the oldest captured_at it will accept. If the cache is older, the client transparently re-reads; if it is fresh enough, the call returns the cached snapshot.
• Reconciliation pass — a nightly job diffs the latest two snapshots per (affiliate, product). Configurable tolerance bands separate normal contribution-driven movement from suspicious jumps; product-missing-from-payload is its own typed alert, not a silent zero.
• Staleness SLO — every product family has a max-age. A snapshot older than the SLO raises before any downstream read can consume it, so consumers never see stale data without a flag.

Failure modes we model explicitly: affiliate consent revoked mid-cycle, Protección affiliate channel down or rate-limiting, certificate generation queue delay (Certifácil is asynchronous in practice), and product appearing/disappearing in the payload when an affiliate changes plan. Each surfaces as a typed error a consumer can match on, not a 500.

Interface evidence

Screens captured from the public Play Store listing for com.ProteccionApp, used to anchor field names and product surfaces during the build.

Regulatory framing (Colombia)

Protección S.A. is one of four private AFPs operating in Colombia alongside the public Colpensiones, and is supervised by the Superintendencia Financiera de Colombia with policy set by the Unidad de Regulación Financiera. Open Finance was first established as a voluntary regime under Decreto 1297 de 2022 and then replaced by Decreto 0368 de 2026, which makes data-sharing mandatory across SFC-supervised entities — pension fund managers included.

That puts Protección inside the perimeter of supervised entities for Finanzas Abiertas, with one practical caveat: the SFC's technical standards (APIs, data schemas, consent UX) and the AFP go-live date are still being operationalised, on a different track from core deposit banking. Until those rails are live for AFPs, the route we build against is user-consented access to the affiliate channel, with the same contract designed to migrate onto the regulated route once it is published.

Adjacent apps we build similar ingestion against

• Porvenir (Grupo Aval) — Largest private Colombian AFP; pensión obligatoria, pensión voluntaria and cesantías balances, contributions and certificates.
• Colfondos (Habitat group) — Pension and cesantías balances, contribution history, fund/portfolio choice, tax certificates.
• Skandia Colombia — AFP and wealth manager; pension, voluntary savings and investment portfolio data.
• Colpensiones - Mi Cuenta / Asesor Virtual — Public Régimen de Prima Media operator; weeks contributed, BEPS savings, pension application status.
• Bancolombia App Personas — Balances, accounts, cards, loans, investments and transaction history.
• Nequi — Bancolombia-affiliated wallet; balance, movements, bolsillos, llaves transfers.
• Daviplata — Davivienda's wallet; balance, transfers, bill payments, subsidy disbursements.
• Davivienda Móvil — Davivienda retail bank app; accounts, cards, loans, investments, certificates.
• BBVA Colombia / BBVA Móvil — BBVA Colombia retail app; accounts, cards, credits, investment holdings.
• Banco de Bogotá App — Grupo Aval retail bank app; deposit/credit balances, transactions, consumer credit.

Common questions