Documentación de la API de Suyo

La API de Suyo permite a desarrolladores integrar la confirmación instantánea de pagos de Lemon Cash (tanto transferencias por Lemon Tag como cobros por QR interbancario) en sus propios sistemas, bots de Discord, servidores de videojuegos, páginas web de comercio electrónico y terminales POS.

1. Autenticación

Todas las solicitudes a la API pública requieren tu clave secreta de transmisión (API Key). Puedes obtener tu clave en el panel de Suyo en la pestaña "API & Desarrolladores".

Puedes pasar tu API Key de dos formas:

1. Como parámetro de consulta en la URL: ?key=suyo_live_TU_CLAVE
2. Como cabecera HTTP: X-Api-Key: suyo_live_TU_CLAVE

2. Resumen de Cuenta y Saldo Diario

Obtiene las métricas consolidadas del día: total recaudado en PEN, cantidad de cobros y estado de la cuenta.

Respuesta de Ejemplo (200 OK)

{
  "success": true,
  "merchantId": "m-101",
  "businessName": "Minimarket Don Pepe",
  "lemonEmail": "donpepe.lemon@gmail.com",
  "today_total_pen": 238.50,
  "today_transactions_count": 8,
  "currency": "PEN",
  "status": "ACTIVE"
}

3. Listar Transacciones

Devuelve el listado en formato JSON de todas las transferencias y pagos verificados de Lemon Cash asociados a tu cuenta.

Respuesta de Ejemplo (200 OK)

{
  "success": true,
  "merchant": "Minimarket Don Pepe",
  "total_count": 2,
  "transactions": [
    {
      "id": "tx-1",
      "merchantId": "m-101",
      "provider": "Lemon",
      "amount": 25.00,
      "currency": "PEN",
      "payerName": "rafbre1501 (Tag P2P)",
      "referenceId": "5b2455c5-bc74-4038-94e6-d831368ef179",
      "note": "¡Aporte para el stream crack! 🔥",
      "createdAt": "2026-08-14T20:48:14Z"
    }
  ]
}

4. Flujo en Tiempo Real (Server-Sent Events)

Permite mantener una conexión abierta y persistente para recibir un evento JSON en el instante exacto (latencia < 0.4s) en que un cliente o donante envía dinero por Lemon Cash.

Estructura del Evento Emitido

data: {
  "type": "PAYMENT_RECEIVED",
  "data": {
    "provider": "Lemon",
    "name": "rafbre1501 (Lemon Tag)",
    "amount": "S/ 25.00",
    "note": "Donación en vivo 🔥",
    "referenceId": "OP-1786751360976"
  },
  "timestamp": 1786751360.976
}

5. Ejemplo Completo: Bot de Discord en Python

Este script escucha los pagos en tiempo real y publica automáticamente un anuncio en un canal de Discord:

import urllib.request
import json
import time

API_KEY = "suyo_live_TU_API_KEY_AQUI"
DISCORD_WEBHOOK_URL = "https://discord.com/api/webhooks/TU_WEBHOOK"
STREAM_URL = f"http://localhost:5000/api/v1/events/stream?key={API_KEY}"

def send_discord_notification(payer, amount, note):
    payload = {
        "embeds": [{
            "title": "🍋 ¡Nuevo Pago Recibido en Lemon Cash!",
            "color": 65351, # Color Verde Neón
            "fields": [
                {"name": "Donante / Pagador", "value": payer, "inline": True},
                {"name": "Monto", "value": f"**{amount}**", "inline": True},
                {"name": "Mensaje", "value": note or "Sin mensaje", "inline": False}
            ],
            "footer": {"text": "Verificado por Suyo • suyo.qd.je"}
        }]
    }
    req = urllib.request.Request(
        DISCORD_WEBHOOK_URL,
        data=json.dumps(payload).encode('utf-8'),
        headers={'Content-Type': 'application/json', 'User-Agent': 'SuyoBot/1.0'}
    )
    urllib.request.urlopen(req)

print(f"🚀 Conectando al flujo de Suyo para la clave {API_KEY}...")
with urllib.request.urlopen(STREAM_URL) as response:
    for line in response:
        decoded = line.decode('utf-8').strip()
        if decoded.startswith("data:"):
            try:
                msg = json.loads(decoded[5:].strip())
                if msg.get("type") == "PAYMENT_RECEIVED":
                    data = msg["data"]
                    print(f"💰 Cobro confirmado: {data['name']} envió {data['amount']}")
                    send_discord_notification(data['name'], data['amount'], data.get('note', ''))
            except Exception as e:
                pass

6. Ejemplo en Node.js / JavaScript

Conexión simple utilizando EventSource en Node.js o el navegador:

const API_KEY = "suyo_live_TU_API_KEY";
const eventSource = new EventSource(`http://localhost:5000/api/v1/events/stream?key=${API_KEY}`);

eventSource.onmessage = (event) => {
    const payload = JSON.parse(event.data);
    if (payload.type === "PAYMENT_RECEIVED") {
        console.log(`✅ ¡Pago recibido! ${payload.data.name} pagó ${payload.data.amount}`);
        console.log(`Nota: ${payload.data.note}`);
    }
};

eventSource.onerror = (err) => {
    console.error("Error en la conexión con Suyo:", err);
};