Mi Recibo de Luz Agua Gas Peru — API integration & OpenData services

Deliverables checklist

• OpenAPI 3.1 specification covering all utility providers in scope
• Protocol analysis report per provider (request flow, headers, captcha handling, session lifetime)
• Runnable source in Python (FastAPI) and Node.js (Express) for bill list, PDF fetch and consumption series
• PDF parser module that maps each provider's layout to a unified Bill JSON schema
• Postman collection, integration tests and a docker-compose dev environment
• Compliance notes referencing Ley N. 29733 (Peru data protection), SUNASS and OSINERGMIN expectations

What changed in 2024–2025

Beyond the original PDF download flow, the app evolved in 2024 to offer a stronger Renter Calculator for tenants without separate meters and faster offline access to previously downloaded bills — both useful signals when designing API-side caching and bill-splitting logic. Providers also moved: in 2024 Enel Distribución Perú was rebranded as Pluz Perú, which means any prior integration pointing at enel.pe URLs has to be re-pointed to pluz.pe. Cálidda continued to enhance its Oficina Virtual receipt download feature, exposing the last six receipts directly. Yape (Peru's BCP-owned wallet) widened utility bill payment coverage in 2025 to include Pluz, Hidrandina, Electrocentro, Enosa, Luz del Sur, Sedapal and Cálidda — creating clear demand for an aggregator-grade bill API on the merchant side.

1. Property management for Lima rentals

A property manager handling 200 apartments across Miraflores and San Isidro pulls every Luz del Sur, Sedapal and Cálidda bill once a day via the bill list endpoint, attaches the PDF to the tenant ledger, and triggers the Renter Calculator when a single meter covers a shared unit. Maps to OpenData by treating the supply number as the canonical identifier and the bill as a structured statement object.

2. ERP utility expense ingestion

A retailer with branches across Trujillo (Hidrandina), Pucallpa (Electro Ucayali) and Lima (Pluz Perú) ingests monthly bills through one webhook. Each bill.created event is posted to SAP / Odoo / NetSuite with billed amount, taxes (IGV), period and CIP. This collapses three regional utilities into a single AP workflow — an OpenFinance pattern applied to utility procure-to-pay.

3. Energy-efficiency analytics

An ESG / sustainability team pulls 24 months of kWh consumption from Luz del Sur and gas Sm3 from Cálidda, blends them with HVAC schedules, and outputs a CO2-equivalent dashboard. The API delivers reading dates and consumption arrays so the analytics layer can compute peak / off-peak and weather-normalized metrics.

4. Fintech bill pay & PFM

A neobank or PFM app surfaces upcoming utility obligations alongside bank balances. It calls our bill list endpoint, shows due dates and amounts inside the app, and on user tap opens a PagoEfectivo / Yape deeplink with the CIP. This is OpenBanking-style consent flow extended to non-bank statements.

5. Compliance & KYC residency proof

A digital onboarding flow needs proof-of-address. The user authorizes a one-shot pull of the latest Sedapal or Pluz bill PDF showing their service address; the API returns the PDF plus a parsed JSON with supply_address, billing_period and issue_date, ready to feed into the KYC vendor with a clear consent timestamp.

API: list bills for a supply number

POST /api/v1/peru-utilities/bills.list
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
  "provider": "luz_del_sur",
  "supply_number": "12345678",
  "from": "2025-01-01",
  "to":   "2025-12-31",
  "include_pdf_url": true
}

200 OK
{
  "supply_number": "12345678",
  "provider": "luz_del_sur",
  "currency": "PEN",
  "bills": [
    {
      "bill_id": "LDS-2025-09-12345678",
      "issue_date": "2025-09-04",
      "due_date":   "2025-09-22",
      "period":     {"from":"2025-08-01","to":"2025-08-31"},
      "amount_total": 187.40,
      "amount_igv":   28.59,
      "consumption_kwh": 312,
      "status": "open",
      "cip_code": "8893200012345678",
      "pdf_url": "https://api.openfinance-lab.com/files/LDS-2025-09-12345678.pdf"
    }
  ]
}

API: fetch bill PDF (Cálidda gas)

GET /api/v1/peru-utilities/bills/{bill_id}/pdf
Authorization: Bearer <ACCESS_TOKEN>

200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="calidda-2025-09.pdf"

# Errors
401 invalid_token
403 consent_revoked
404 supply_not_found
429 provider_rate_limited     // upstream portal throttled us; retry after 30s
502 provider_unreachable      // portal down; we surface a circuit-breaker state

Webhook: bill due reminder

POST https://your-app.example/webhooks/peru-utilities
X-OFL-Signature: t=1715212800,v1=hex(hmac_sha256(secret, body))
Content-Type: application/json

{
  "event": "bill.due_soon",
  "occurred_at": "2026-05-09T10:00:00Z",
  "data": {
    "provider": "sedapal",
    "supply_number": "0098765",
    "bill_id": "SDP-2026-05-0098765",
    "amount_total": 64.10,
    "currency": "PEN",
    "due_date": "2026-05-14",
    "days_to_due": 5
  }
}

Compliance & privacy

Peru's regulatory perimeter for utility data is anchored by Ley N. 29733 (Ley de Protección de Datos Personales) and its enforcement body the Autoridad Nacional de Protección de Datos Personales. On the sectoral side, OSINERGMIN regulates electricity and gas, while SUNASS regulates water. We restrict ingestion to public consultation endpoints on .pe and .com.pe domains — exactly the same scope the original Mi Recibo app declares — and we do not collect, store or modify provider-issued data beyond what the user is authorized to retrieve.

For B2B clients exporting Peru utility data outside the country, we provide a data-protection impact summary, a record of consents, and field-level minimization (e.g. masking the holder's national ID by default). For European / global stacks, we cross-reference GDPR purpose-limitation principles so the same OpenData pipeline can serve LatAm operations and EU headquarters.

Data flow / architecture

Each request follows a four-stage pipeline:

1. Client App — your backend or mobile client calls our REST endpoint with a supply number and provider hint.
2. Provider Adapter — a per-utility adapter handles session, captcha and HTML/JSON parsing against the official portal.
3. Storage — bills, PDFs and consumption series are persisted with consent metadata; PDFs are encrypted at rest.
4. API / Webhook output — normalized JSON is served via REST, plus optional bill.created and bill.due_soon webhook events.

Market positioning & user profile

The Mi Recibo Peru audience is dominated by Spanish-speaking residential users on Android (the dominant platform in Peru), with a strong long tail of small landlords, accountants and SME finance teams who need to retrieve recurring bills across multiple providers. From an integration buyer's perspective, the adjacent demand is clearly B2B: property managers, multi-branch retailers, energy services companies, ESG / sustainability platforms, fintechs offering bill pay (Yape, Plin, neobank apps), and KYC vendors using utility bills as proof-of-address. Coverage is concentrated in Lima & Callao (Luz del Sur, Sedapal, Cálidda) plus the northern, central and Amazon regions through Distriluz and Electro Ucayali — broadly mirroring Peru's urban population centers.

About OpenFinance Lab

We are an independent studio focused on app protocol analysis, OpenData and OpenFinance integrations across LatAm, Europe and APAC. Our team has shipped utility, banking and fintech connectors against portals that have no public APIs, with rigorous adapter testing and circuit-breaker design when upstream sites change.

• End-to-end pipeline: protocol analysis → build → validation → compliance review
• Python (FastAPI), Node.js, Go SDKs and reference clients
• Source code delivery from $300 — runnable API + docs, pay after delivery upon satisfaction
• Pay-per-call hosted API — no upfront fee, ideal for variable-volume teams

Contact

For quotes or to submit your target app and requirements, open our contact page:

Contact page

Engagement workflow

1. Scope confirmation: which Peru utility providers, which fields, which delivery mode (REST, webhook, file).
2. Protocol analysis per provider portal (2–5 business days, depending on captcha and session model).
3. Adapter build, PDF parser tuning and internal validation (3–8 business days).
4. Documentation, sample clients (Python / Node.js) and integration tests (1–2 business days).
5. First delivery typically lands in 5–15 business days; provider-side outages may extend timelines.