API Docs - BillApp v1

Base URL

https://billapp.sleypc.com/api/v1

Autenticacion

Hay dos tipos de clientes:

• Dispositivos (app movil): login con usuario+password, recibe JWT que se usa como Authorization: Bearer <jwt>. JWT expira en 7 dias.
• Consumers externos (3rd party): envia los 3 headers:
  • X-Api-Key: pk_xxxxx (key publica)
  • X-Api-Token: xxxxxxxx (key privada en plain, va por HTTPS)
  • X-Api-Timestamp: 1747800000 (unix timestamp, ventana 5 min)

Endpoints publicos (3rd party)

GET /api/v1/health

curl https://billapp.sleypc.com/api/v1/health
# {"ok":true,"service":"billapp","time":"2026-05-21T..."}

GET /api/v1/notifications

Lista notificaciones del dispositivo asociado al consumer.

Query params opcionales:

• since: unix timestamp o ISO datetime
• min_amount, max_amount: monto
• sender: filtro LIKE en remitente parseado
• op_code: filtro exacto en codigo de operacion
• limit: 1-200 (default 50)

curl https://billapp.sleypc.com/api/v1/notifications?min_amount=20&since=1747800000 \
  -H "X-Api-Key: pk_xxxxx" \
  -H "X-Api-Token: priv_xxxx" \
  -H "X-Api-Timestamp: $(date +%s)"

GET /api/v1/notifications/{id}

Devuelve una notificacion especifica del device del consumer.

POST /api/v1/verify-payment

Verifica si una notificacion coincide con monto/remitente/op_code en los ultimos N segundos.

curl -X POST https://billapp.sleypc.com/api/v1/verify-payment \
  -H "X-Api-Key: pk_xxxxx" \
  -H "X-Api-Token: priv_xxxx" \
  -H "X-Api-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{"amount":25.50,"since_seconds":600}'
# {"ok":true,"verified":true,"match":{...}}

Endpoints solo de dispositivos (app movil)

POST /api/v1/device/login

curl -X POST https://billapp.sleypc.com/api/v1/device/login \
  -H "Content-Type: application/json" \
  -d '{"username":"billapp_xxx","password":"yyyy"}'
# {"ok":true,"token":"eyJ...","device":{...}}

POST /api/v1/device/checkin

Heartbeat. La app envia su android_device_id y app_version. Servidor responde con status (active|paused|kill_switch).

POST /api/v1/device/notifications

Bulk upload (max 100/batch). Dedup por hash(package+title+text+when).

{
  "notifications": [
    {
      "package": "com.bcp.innovacxion.yapeapp",
      "app_label": "Yape",
      "title": "Yape! Recibiste un pago",
      "text": "Recibiste S/ 25.50 de JUAN PEREZ",
      "when": 1747800000000,
      "received_at": 1747800001
    }
  ]
}

Codigos de error

• 401 unauthorized - credenciales invalidas
• 403 not_active - device pausado/revocado
• 400 invalid_input - JSON o campos malformados
• 413 too_many - excede limites de batch
• 429 - rate limit excedido