Integrating Protección — affiliated-portal pension and cesantías ledgers

Colombia's Open Finance system became mandatory on 7 April 2026 with Decree 0368, and pension-fund administrators sit explicitly in scope alongside banks, trust companies and insurers. Protección is one of the four AFPs — relabelled ACCAIs after the pension reform that took effect on 1 July 2025 — that hold a sizeable share of the country's individual retirement and severance ledgers. An integrator who wants a programmatic view of an affiliate's saldo, semanas cotizadas, and cesantías has two practical lanes available right now: the afiliado portal under the user's authorization, and, on a 30-month transition timeline, the SFA endpoints once Protección is registered in the Superfinanciera's participant directory. The studio builds either lane against the same schema, so the data layer can switch sources without the consumer changing.

Affiliated data on Protección's portal

The afiliado portal at proteccion.com/portalafiliados presents a small set of clearly named modules, each backed by structured records the integration can pull. Internal names track the labels the affiliate sees on screen.

Three lanes into Protección's data

Three integration lanes apply to Protección right now. Which one to build against turns on where the source data lives and how long you want to own the parser.

Authorized interface integration / protocol analysis

The studio builds against the afiliado portal under the customer's authorization, with the user's consent. Every domain in the table above is reachable through this lane because it covers everything the affiliate themselves can see. Effort: one to two weeks. Durability is medium — portal markup occasionally shifts, and we re-check the parse on a maintenance cadence rather than freezing it to a single capture. Access to a consenting affiliate's account or an enterprise sandbox is arranged with the client during onboarding, under NDA where the data is sensitive.

Sistema de Finanzas Abiertas (Open Finance Colombia)

Under Decree 0368, Protección is in scope as a data-supplying entity, and the dual-layer consent model (third-party authorization plus institution-side verification) governs every read. The Superfinanciera maintains the participant directory and issued External Circular 001 in February 2026 to extend the operational transition from 18 to 30 months. The studio's build keeps the data layer abstracted: the same OpenAPI surface the consumer calls is fed by the portal lane today, and by the SFA endpoints as each Protección product registers.

Native export via Certifácil

Certifácil already issues annual PDF certificates downloadable per year and can email them, per the Protección help page. For tax-flow integrations this is often the lightest source — we wrap the retrieval, parse the canonical fields out, and emit a structured record alongside the original PDF.

For most buyers we ship lane 1 today, with the data-source layer abstracted so lane 2 plugs in product-by-product as Protección's endpoints go live; the Certifácil exporter sits behind the same façade for tax flows.

Open Finance Colombia, Decree 0368, and consent

Decree 0368 — published in the Presidencia normativa on 7 April 2026 — replaces the voluntary Open Finance regime established by Decree 1297 of 2022 with a mandatory one, and pension-fund administrators are named participants. Consent runs on two layers: the affiliate authorizes the third-party data recipient, specifying scope, purpose and duration, and Protección must then verify that authorization before releasing data. The Superfinanciera operates the participant directory. The transition window, as extended by External Circular 001 in February 2026, runs 30 months — so some products surface on the SFA endpoints before others, which is why the integration is built source-agnostic from day one. We log consent grants, scopes and revocations as first-class events so the audit trail satisfies SFC inspections. Data minimization is applied at the schema layer: only the fields a consumer's consent authorizes are pulled across.

Code shape — an afiliado session and the queries it carries

The auth dance and the four highest-traffic queries, in a shape that survives portal-skin changes. Exact field names are confirmed against the live afiliado portal during the build.

# Illustrative — class names and field shapes are the studio's,
# confirmed against the live afiliado portal at build time.

from oss_proteccion import AfiliadoSession, ConsentScope

scope = ConsentScope(
    products=["pension_obligatoria", "cesantias", "certifacil"],
    purpose="aggregation",
    expires_at="2026-11-20",          # consent duration the affiliate granted
)

sess = AfiliadoSession(consent=scope)
sess.login(
    documento_tipo="CC",              # CC / CE / TI / PA / NIT
    documento_numero=user_doc,
    clave_personal=user_clave,
    # 2FA handled inside .login() — challenge surface depends on the request
)

# 1) Pensión obligatoria — saldo total, contribution weeks, fund choice
po = sess.pension_obligatoria()
# po.saldo, po.semanas_cotizadas, po.fondo, po.movimientos[*]

# 2) Cesantías — joined across employers for the year
ces = sess.cesantias(year=2025)
# ces[*].empleador, ces[*].saldo, ces[*].movimientos, ces[*].fecha_ingreso

# 3) Cesantías retiro — request status, not balance-derived
ret = sess.cesantias_retiros.list_open()
# ret[*].estado in {"recibido","en_revision","aprobado","desembolsado"}

# 4) Certifácil — annual aportes-y-retenciones certificate (PDF + parsed)
cert = sess.certifacil(year=2025, tipo="aportes_retenciones")
# cert.pdf_bytes, cert.parsed.year, cert.parsed.lines[*]
      

What ships with a Protección build

Every Protección engagement leaves a stable set of artefacts behind, named so an internal team can carry the integration forward without us.

• An OpenAPI specification covering the affiliate identity, pensión obligatoria balance and weeks, the cesantías ledger query, Certifácil retrieval, cesantías-withdrawal status, and pensión voluntaria holdings.
• Runnable source in Python and Node, structured around the AfiliadoSession class above, with the portal-coupled layer isolated so SFA endpoints can replace it as they come online.
• A protocol and auth-flow report — how the document-type plus clave login works, how session tokens age, how 2FA fires on retiros, and how withdrawal status is polled rather than inferred.
• Automated tests — a portal-replay fixture that records the afiliado session and verifies every parsed field round-trips, plus a contract test that asserts the OpenAPI spec against the live shape.
• Interface documentation in both English and Spanish, mapping every internal field to the screen label the affiliate sees on proteccion.com/portalafiliados.
• Compliance notes — where Decree 0368 consent records live, retention windows we recommend, what to log on revocation, and what the SFC participant directory expects.

Engineering decisions specific to Protección

A handful of choices are particular to this app rather than generic AFP scaffolding, and we handle each inside the build.

• Affiliate identity is keyed on (documento_tipo, documento_numero) rather than email — the portal accepts CC, CE, TI, PA and NIT, and the same person can carry different document types across their working life. We resolve this in the auth layer so downstream code sees a single stable affiliate ID.
• The 2025 reform splits contributions at the 2.3 SMMLV threshold: up to that figure the money flows to Colpensiones, anything above flows to Protección as the ACCAI. We model that split in the contribution stream so the same code path handles transition-regime affiliates (where the threshold doesn't bite) and post-reform affiliates without forks.
• Cesantías-withdrawal requests are quoted at 3 to 6 business days, per Protección's own help pages. The integration polls the request endpoint and surfaces state changes (recibido → en revisión → aprobado → desembolsado) as first-class events; we do not infer state from balance differences, which previously broke when a withholding step landed before the balance refresh.
• Portal access is arranged with the client during onboarding — a consenting affiliate's account under NDA, or an enterprise sandbox where the client or Protección provides one. The build runs against the live portal shape; re-validating the parse is part of the studio's maintenance cadence rather than a one-shot capture.

Screens we worked from

Public Play Store screenshots used to map domains to surfaces. Tap any tile for a larger view.

Adjacent Colombian apps that share this circuit

Several Colombian financial apps sit in the same data circuit, and a buyer often wants more than one normalized under a single integration. Porvenir is the largest of the four private AFPs alongside Protección, with the same pension-and-cesantías product split. Colfondos and Skandia Pensiones round out the authorized ACCAI set; both expose comparable afiliado portals. Colpensiones, the public pension administrator, holds the contributions up to the 2.3 SMMLV threshold for all affiliates after the reform and operates its own consulta portal. Bancolombia carries the largest current-account share in the country and the Nequi wallet rides on its rails. Davivienda runs the Daviplata wallet, which competes head-to-head with Nequi in lower-income segments. Tributi automates Colombian income-tax filing and is the obvious downstream consumer of a Protección Certifácil feed. Ualet offers retail investment funds and pension-flavoured products to the same audience as Protección's voluntary line. A unified integration normalizes balances, contributions, and certificates across the lot.

Questions a Protección integrator asks

How does the integration handle Protección's move from AFP to ACCAI under the 2025 pension reform?

The reform took effect on 1 July 2025 and routes employer contributions up to 2.3 SMMLV to Colpensiones, with anything above flowing to an ACCAI — Protección is one of the four authorized ACCAIs per the Superfinanciera notice. We model affiliate identity once and split the contribution stream by threshold, so the same integration covers transition-regime affiliates and post-reform workers without parallel code paths.

Can the integration reconcile cesantías across multiple employers and pull the annual Certifácil certificate?

Yes. The portal exposes a per-employer ledger under "Mis cesantías" and the Certifácil tool returns the annual aportes-y-retenciones certificate as a PDF when given the year, per Protección's own help pages. The build joins the two: the ledger drives reconciliation, the certificate gives a tax-attached snapshot.

Does the integration depend on Protección being listed in the Open Finance directory under Decree 0368?

No. The current build runs against the afiliado portal under the user's authorization, which is independent of the directory timeline. When Protección registers and the Superfinanciera publishes its endpoints — the External Circular 001 transition runs 30 months from February 2026 — we swap the data-source layer over to the SFA API without rewriting the schema or the downstream consumers.

Are pensión voluntaria balances reachable in the same session as pensión obligatoria?

They sit behind the same afiliado login but in different portal modules, with separate currency and product-code shapes. The integration models them as two product types under one affiliate identity, and surfaces the consolidated view the affiliate sees inside the app.

Sources and method

This brief was assembled from primary regulatory texts and the Protección portal as they stood on 2026-05-20. We read the decree, the SFC announcement, the Play Store listing, and the affiliate-facing help pages, and mapped surfaces in the screenshots to data domains. Specific deep-link sources used:

• Presidencia de la República — Decreto No. 0368 del 07 de abril de 2026 (PDF)
• Superintendencia Financiera de Colombia — Finanzas Abiertas Obligatorias
• Google Play — Protección (com.ProteccionApp)
• Protección — Certifácil affiliate help

OpenBanking Studio · integration desk, reviewed May 2026.

Source-code delivery for a Protección integration starts at $300, invoiced after the build is running against your data and you sign off — the cycle is one to two weeks. If you would rather skip the build and pay only when you call, the studio's hosted endpoints carry no upfront fee. Tell us the affiliate scope and timing at /contact.html and we will come back with a delivery plan written against your specific use case.