Iniciar sesion

API Docs - BillApp v1

Base URL

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

Que es esta API

Permite a cualquier sistema externo consultar las notificaciones Yape (u otras apps de pago) capturadas por un dispositivo movil BillApp.

Casos de uso tipicos:

Autenticacion

Todas las llamadas requieren 3 headers HTTP:

HeaderValorDescripcion
X-Api-Keypk_xxxxxxxKey publica del consumer (visible en el panel)
X-Api-TokenxxxxxxxxKey privada (se muestra una sola vez al crear)
X-Api-Timestamp1747800000Unix timestamp actual (anti-replay, ventana 5 min)

Las claves se generan desde el panel admin: Dispositivos > (device) > Crear nuevo API consumer.

Codigos de respuesta HTTP

CodeSignificado
200Operacion exitosa, cuerpo JSON
400Parametros invalidos o faltantes
401Auth invalida: key/token incorrecto o timestamp fuera de ventana
404Endpoint o notificacion no encontrada
429Rate limit excedido (por defecto 60 req/min, configurable por consumer)

Endpoint 1: GET /health

Health check publico, no requiere auth.

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

Endpoint 2: GET /me

Info del consumer actual y device asociado. Util para validar credenciales.

curl https://billapp.sleypc.com/api/v1/me \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Token: priv_xxx" \
  -H "X-Api-Timestamp: $(date +%s)"

# Response:
# {
#   "ok": true,
#   "consumer": {"id":1,"label":"POS Tienda Foo","rate_limit_per_min":60,"request_count":42},
#   "device": {"id":1,"label":"YAPE TIENDA","phone":"+51999999999","status":"active","last_seen_at":"2026-05-21 15:30:00","total_notifs":7},
#   "server_time":"2026-05-21T15:30:05-05:00"
# }

Endpoint 3: GET /notifications

Lista notificaciones con filtros opcionales.

Query paramTipoDescripcion
sinceunix ts o ISO datetimeSolo notifs despues de esta fecha
min_amountfloatMonto minimo
max_amountfloatMonto maximo
senderstringMatch parcial (LIKE %sender%) en remitente
op_codestringMatch exacto en codigo de operacion
limitint 1-200Default 50
# Notifs de las ultimas 24h, monto >= 10
curl 'https://billapp.sleypc.com/api/v1/notifications?since=1747800000&min_amount=10' \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Token: priv_xxx" \
  -H "X-Api-Timestamp: $(date +%s)"

# Response:
# {
#   "ok": true,
#   "count": 3,
#   "notifications": [
#     {"id":7,"package":"com.bcp.innovacxion.yapeapp","title":"Confirmacion de Pago","text":"Yape! JUAN PEREZ te envio...","amount":25.5,"currency":"PEN","sender":"JUAN PEREZ","op_code":null,"received_at":"2026-05-21 15:00:00"},
#     ...
#   ]
# }

Endpoint 4: GET /notifications/{id}

Detalle de una notificacion especifica.

curl https://billapp.sleypc.com/api/v1/notifications/7 \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Token: priv_xxx" \
  -H "X-Api-Timestamp: $(date +%s)"

Endpoint 5: POST /verify-payment ★

El mas usado: verificacion rapida de un pago en una ventana de tiempo.

curl -X POST https://billapp.sleypc.com/api/v1/verify-payment \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Token: priv_xxx" \
  -H "X-Api-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.50,
    "sender": "JUAN",
    "since_seconds": 600
  }'

# Body params:
#   amount         (float, opcional) - busqueda exacta de monto
#   sender         (string, opcional) - LIKE %sender%
#   op_code        (string, opcional) - codigo exacto
#   since_seconds  (int, opcional, default 600) - cuantos seg hacia atras buscar (max 86400)

# Response cuando hay match:
# {"ok":true,"verified":true,"match":{"id":7,"amount":25.5,"sender":"JUAN PEREZ",...}}

# Response cuando NO hay match:
# {"ok":true,"verified":false}

Endpoint 6: POST /wait-for-payment ★★

Long polling. La request queda BLOQUEADA esperando a que el pago llegue.

Ideal para flujos donde tu sistema le dice al cliente "esperando tu Yape..." y necesitas reaccionar al instante.

curl -X POST https://billapp.sleypc.com/api/v1/wait-for-payment \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Token: priv_xxx" \
  -H "X-Api-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.50,
    "amount_tolerance": 0.01,
    "since": 1747800000,
    "timeout_seconds": 60
  }'

# Body params:
#   amount         (float) - monto esperado
#   amount_tolerance (float, default 0.01) - tolerancia +- al comparar
#   sender         (string, opcional)
#   op_code        (string, opcional)
#   since          (unix ts, default = ahora - 60s) - desde cuando buscar
#   timeout_seconds (int 5-120, default 30) - cuanto bloquear esperando

# Response cuando llega:
# {"ok":true,"matched":true,"wait_seconds":12,"notification":{...}}

# Response si timeout:
# {"ok":true,"matched":false,"wait_seconds":60,"message":"Timeout sin coincidencia"}

Endpoint 7: GET /last

Devuelve la ultima notificacion recibida por este device.

curl https://billapp.sleypc.com/api/v1/last \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Token: priv_xxx" \
  -H "X-Api-Timestamp: $(date +%s)"

# {"ok":true,"notification":{"id":7,"amount":25.5,...}}

Endpoint 8: GET /search?q=texto

Busqueda de texto libre en titulo, texto, sender, op_code.

curl 'https://billapp.sleypc.com/api/v1/search?q=PEREZ&limit=10' \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Token: priv_xxx" \
  -H "X-Api-Timestamp: $(date +%s)"

Endpoint 9: GET /stats

Estadisticas del device.

curl https://billapp.sleypc.com/api/v1/stats \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Token: priv_xxx" \
  -H "X-Api-Timestamp: $(date +%s)"

# {
#   "ok":true,
#   "device_id":1,
#   "stats":{
#     "total":42,
#     "last_hour":3,
#     "last_24h":15,
#     "last_7d":42,
#     "total_amount":1250.75,
#     "avg_amount":29.78,
#     "min_amount":1.0,
#     "max_amount":500.0,
#     "first_at":"2026-05-15 10:00:00",
#     "last_at":"2026-05-21 15:00:00"
#   }
# }

Flujos completos - ejemplos por lenguaje

PHP - verificar pago tras pedirle Yape al cliente

<?php
$key = 'pk_xxx';
$token = 'priv_xxx';
$amount = 25.50;

$ch = curl_init('https://billapp.sleypc.com/api/v1/verify-payment');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-Api-Key: $key",
        "X-Api-Token: $token",
        "X-Api-Timestamp: " . time(),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => $amount,
        'since_seconds' => 600,
    ]),
]);
$res = json_decode(curl_exec($ch), true);

if ($res['verified'] ?? false) {
    echo "Pago confirmado: S/ " . $res['match']['amount'] . " de " . $res['match']['sender'];
} else {
    echo "Pago aun no recibido";
}

JavaScript / Node.js - long polling de pago

async function waitForYape(amount, timeoutSec = 60) {
  const res = await fetch('https://billapp.sleypc.com/api/v1/wait-for-payment', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'pk_xxx',
      'X-Api-Token': 'priv_xxx',
      'X-Api-Timestamp': Math.floor(Date.now() / 1000).toString(),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount,
      amount_tolerance: 0.01,
      timeout_seconds: timeoutSec,
    }),
  });
  return await res.json();
}

// Uso:
const result = await waitForYape(25.50, 60);
if (result.matched) {
  console.log('Yape recibido:', result.notification);
} else {
  console.log('No llego en 60s, reintentar?');
}

Python - verificar y reaccionar

import requests, time

KEY = 'pk_xxx'
TOKEN = 'priv_xxx'
BASE = 'https://billapp.sleypc.com/api/v1'

def hdrs():
    return {
        'X-Api-Key': KEY,
        'X-Api-Token': TOKEN,
        'X-Api-Timestamp': str(int(time.time())),
        'Content-Type': 'application/json',
    }

# Esperar pago de S/25.50 durante 60s
r = requests.post(f'{BASE}/wait-for-payment',
    headers=hdrs(),
    json={'amount': 25.50, 'timeout_seconds': 60},
    timeout=70)
data = r.json()
if data.get('matched'):
    n = data['notification']
    print(f"OK pago recibido de {n['sender']} por S/ {n['amount']}")
else:
    print("Timeout - el cliente no pago")

cURL - polling simple en bash

# Espera 5 minutos consultando cada 10 seg
KEY=pk_xxx
TOKEN=priv_xxx
AMOUNT=25.50
for i in {1..30}; do
  RES=$(curl -sS -X POST https://billapp.sleypc.com/api/v1/verify-payment \
    -H "X-Api-Key: $KEY" \
    -H "X-Api-Token: $TOKEN" \
    -H "X-Api-Timestamp: $(date +%s)" \
    -H "Content-Type: application/json" \
    -d "{\"amount\":$AMOUNT,\"since_seconds\":300}")
  if echo "$RES" | jq -e '.verified == true' >/dev/null; then
    echo "OK pago recibido"
    echo "$RES" | jq
    break
  fi
  sleep 10
done

Recomendaciones de uso

Errores comunes

Error JSONCausaFix
unauthorizedKey/token incorrectoVerifica panel
unauthorized con timestamp fuera de ventanaReloj del server consumidor desincronizadoSincronizar con NTP
rate_limit / 429Mas de N req/minReduce frecuencia o pide al admin subir el limite
invalid_inputJSON malformado o param invalidoRevisa schema