API y Webhooks

Tingu Alerta captura las notificaciones de pago que llegan al celular del negocio y las normaliza. La integración te da acceso a esos pagos ya estructurados, sin que tengas que tocar ninguna app bancaria.

• Webhook — te enviamos un POST a tu URL cada vez que entra un pago. Es la vía recomendada: llega en segundos y no tienes que consultar nada.
• API REST — consultas el historial de pagos con filtros de fecha, tipo de billetera y sucursal. Útil para conciliar o para cargar datos históricos.

Dos cabeceras en cada petición:

Buenas prácticas

• Guarda las credenciales en variables de entorno, no en el código.
• Crea una credencial por sistema (POS, ERP, panel). Así puedes revocar una sin tumbar las demás.
• Ponle fecha de expiración a las credenciales de pruebas.
• Revisa el uso desde la app: cada credencial registra su último uso y su total de peticiones.

Parámetros de consulta

Respuesta

{
  "success": true,
  "alertas": [
    {
      "id": 1842,
      "tipo": "yape",
      "monto": 50.00,
      "nombre_cliente": "Juan Carlos R.",
      "codigo_seguridad": "482",
      "estado": "enviado",
      "fecha_hora": "2026-08-09T15:42:11.000Z",
      "id_billetera": 3,
      "id_sucursal": 1
    }
  ],
  "total": 248,
  "page": 1,
  "limit": 20,
  "totalPages": 13
}

Consultar el histórico sirve para cuadrar caja. Para que tu sistema reaccione en el momento en que entra un pago, conéctate por Socket.io con las mismas credenciales.

const { io } = require('socket.io-client');

const socket = io('https://api.tingualerta.com', {
  auth: {
    apiKey: 'lpa_a1b2c3d4...',
    apiSecret: '9f8e7d6c...',
    idSucursal: 3   // opcional: solo los pagos de esa sucursal
  }
});

socket.on('connect', () => socket.emit('solicitar-pendientes'));

socket.on('nueva-alerta', (pago) => {
  // pago.esPrueba  -> alerta de prueba, no la cuentes en caja
  // pago.esPendiente -> reenvío tras reconectar, no la vuelvas a anunciar
  console.log(pago.monto, pago.nombreCliente);
  socket.emit('alerta-recibida', { alertaId: pago.id });
});

Eventos

• nueva-alerta — un pago. Responde siempre con alerta-recibida: sin ese acuse el pago queda marcado como pendiente y se te reenvía al reconectar.
• joined-room — { room, idSucursal }. Si pediste una sucursal que no es de tu cuenta, llega idSucursal: null y escucharás todas.
• cuenta-sin-servicio — el plan venció o se agotó la cuota: ese pago no se registró. Trae el monto para que puedas cobrarlo por otra vía en vez de quedarte a ciegas.

Errores de conexión

Llegan en connect_error. Estos tres son definitivos: reintentar con la misma credencial no puede funcionar, así que detén la reconexión y avisa en pantalla.

• API_KEY_INVALIDA — credenciales incorrectas o key revocada.
• API_NO_HABILITADA — la cuenta no tiene activo el Acceso API.
• CUENTA_DESACTIVADA — cuenta suspendida.

Configuras una URL desde la app y te enviamos un POST con Content-Type: application/json cada vez que entra un pago.

Cabeceras que recibes

Cuerpo del envío

{
  "Id": 1842,
  "IdUsuarioNegocio": 17,
  "Tipo": "yape",
  "NombreCliente": "Juan Carlos R.",
  "Monto": 50.00,
  "CodigoSeguridad": "482",
  "Estado": "Completado",
  "FechaHora": "2026-08-09T15:42:11.000Z",
  "IdBilletera": 3,
  "IdSucursal": 1,
  "PackageName": "com.bcp.innovacxion.yapeapp",
  "NombreNegocio": "Bodega Central",
  "FechaRegistro": "2026-08-09T15:42:12.000Z"
}

Verificar la firma (obligatorio)

Sin verificar la firma, cualquiera que conozca tu URL puede inyectarte pagos falsos. Calcula el HMAC-SHA256 del cuerpo crudo con tu secret y compáralo en tiempo constante.

// Node.js + Express
const crypto = require('crypto');

app.post('/webhook-tingu',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const firma = req.headers['x-tingu-signature'];
    const esperada = crypto
      .createHmac('sha256', process.env.TINGU_SECRET)
      .update(req.body)
      .digest('hex');

    const a = Buffer.from(firma || '');
    const b = Buffer.from(esperada);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send('Firma invalida');
    }

    const pago = JSON.parse(req.body);
    // Responde 200 YA. Procesa despues, en segundo plano.
    res.sendStatus(200);
    procesarEnSegundoPlano(pago);
  }
);

# Python + Flask
import hmac, hashlib, os
from flask import request, abort

@app.route('/webhook-tingu', methods=['POST'])
def webhook():
    esperada = hmac.new(
        os.environ['TINGU_SECRET'].encode(),
        request.get_data(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(esperada, request.headers.get('X-Tingu-Signature', '')):
        abort(401)

    pago = request.get_json()
    return '', 200

// C# / .NET — para integrar con un POS Windows
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var esperada = Convert.ToHexString(
    hmac.ComputeHash(Encoding.UTF8.GetBytes(cuerpoCrudo))
).ToLowerInvariant();

if (!CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(esperada),
        Encoding.UTF8.GetBytes(firmaRecibida)))
    return Unauthorized();

• HTTPS con certificado válido y accesible desde internet.
• Responde en menos de 10 segundos. Ese es el tiempo de espera; después se considera fallo.
• Devuelve 2xx en cuanto recibas. Procesa en segundo plano: si tardas en responder porque estás guardando en tu base de datos, provocas reintentos innecesarios.
• Sé idempotente. Un reintento puede reenviarte un pago que ya procesaste. Usa el campo Id como clave única.

Reintentos

Si tu endpoint no responde 2xx, reintentamos hasta 3 veces con 5 segundos de separación. Cada intento queda registrado con su código de respuesta y su error, consultable desde la app.

Todas las respuestas de error comparten forma:

{
  "success": false,
  "error": "El acceso API no esta habilitado en esta cuenta",
  "code": "API_NO_HABILITADA"
}

Ambos servicios se habilitan por cuenta. Escríbenos por WhatsApp indicando el correo del negocio y qué necesitas —webhook, API o los dos— y lo activamos.

Si estás integrando y algo no cuadra, cuéntanos qué endpoint llamas y qué respuesta recibes. Los registros de cada webhook y de cada credencial quedan guardados, así que podemos ver exactamente qué pasó.