Documentación

API de Integración BiPe Alerta

Conecta tu sistema con BiPe Alerta mediante nuestra API REST y webhooks. Consulta transacciones, recibe notificaciones en tiempo real y automatiza tus procesos.

Introducción a Webhooks

Fundamentos

¿Qué son los Webhooks?

Los webhooks son una forma de recibir notificaciones automáticas cuando ocurren eventos en BiPe Alerta. En lugar de consultar constantemente nuestra API para verificar nuevos pagos, puedes configurar un webhook para que nuestro sistema envíe automáticamente la información a tu servidor cuando ocurra un nuevo pago.

Nota importante
Para utilizar webhooks, necesitas contar con un endpoint HTTP accesible públicamente en tu servidor que pueda recibir solicitudes POST.

Implementación de Webhooks

Guía paso a paso

Configuración de tu Webhook

Crea un endpoint

Implementa un endpoint HTTP en tu servidor que acepte solicitudes POST. Este endpoint recibirá los datos del pago en formato JSON.

Configura la URL en BiPe Alerta

Ingresa a tu cuenta de BiPe Alerta, ve a "Configuración" > "Webhooks" y registra la URL de tu endpoint.

Procesa las notificaciones

Programa tu endpoint para procesar las notificaciones recibidas y actualizar tu sistema según sea necesario.

Estructura del Webhook

Referencia técnica

Formato JSON

Cuando ocurre un pago, BiPe Alerta enviará una solicitud POST a tu endpoint con un objeto JSON con la siguiente estructura:

YapeWebHook.json
{
                    "Id": 123,
                    "IdUsuarioNegocio": 456,
                    "Tipo": "Yape",
                    "NombreCliente": "Juan Pérez",
                    "Monto": 25.50,
                    "Estado": "Completado",
                    "FechaHora": "2025-03-18T15:30:45",
                    "IdBilletera": 789,
                    "PackageName": "com.yape.app"
}

Parámetros del Webhook

Parámetro Tipo Descripción
Id integer Identificador único de la notificación
IdUsuarioNegocio integer ID del usuario del negocio en BiPe
Tipo string Tipo de transacción (Yape, Plin, etc.)
NombreCliente string Nombre del cliente que realizó el pago
Monto decimal Monto de la transacción
Estado string Estado de la transacción
FechaHora DateTime Fecha y hora de la transacción
IdBilletera integer ID de la billetera asociada
PackageName string? Nombre del paquete de la aplicación (opcional)

API REST de Integración

Nuevo

Endpoints disponibles

Método Endpoint Descripción Autenticación
GET /api/integration/yapes Obtener transacciones por rango de fechas Token API
GET /api/integration/health Verificar estado del servicio Público
POST Webhook configurado Notificación de nueva transacción Configuración

Autenticación con Tokens de API

Seguridad

Tokens de API

Los endpoints de integración requieren un token de API asociado a tu negocio. Cada token identifica al negocio y permite consultar sus transacciones.

Genera un token

Desde tu Dashboard en Tokens API → Nuevo Token, crea un token con una descripción que identifique su uso (ej: "Token para integración con Bipe").

Copia el token

El token se muestra una sola vez al crearlo. Guárdalo en un lugar seguro inmediatamente. No volverá a mostrarse.

Usa el token en tus solicitudes

Incluye el token en el header de tus solicitudes HTTP.

Formato del token:

Ejemplo de token
ya_bp_Ev6v1NplEWBd2rAIsKBSA4927c2NsVO4MN1ey4whowk

Cómo enviar el token

Usa el header Authorization con el esquema Bearer:

Header HTTP
Authorization: Bearer ***

O alternativamente, usando el header X-API-Key:

Header alternativo
X-API-Key: ***
Seguridad de tokens
Los tokens se almacenan con hash SHA-256. Si un token se ve comprometido, revócalo inmediatamente desde el Dashboard. Los tokens revocados no se pueden reactivar.

Consultar Transacciones

GET

Obtener Yapes por fecha

Consulta las transacciones registradas en tu negocio filtradas por rango de fechas.

Request
GET /api/integration/yapes?fechaInicial=2026-07-01&fechaFinal=2026-07-07
Host: apialert.c-centralizador.com
Authorization: Bearer ***

Parámetros

Parámetro Tipo Requerido Descripción
fechaInicial string Fecha de inicio (YYYY-MM-DD)
fechaFinal string Fecha de fin (YYYY-MM-DD)

Ejemplo cURL

Terminal
curl -H "Authorization: Bearer ***" \
  "https://apialert.c-centralizador.com/api/integration/yapes?fechaInicial=2026-07-01&fechaFinal=2026-07-07"

Respuesta

200 OK
{
                    "status": true,
                    "message": "Yapes obtenidos correctamente",
                    "response": [
                        {
                        "idYape": 12345,
                        "nombreUsuarioNegocio": "Juan Perez",
                        "nombreCliente": "Maria Lopez",
                        "monto": 150.00,
                        "fechaHora": "2026-07-05T14:30:00",
                        "repetido": false,
                        "tipo": "Yape",
                        "nombreLocal": "Local Principal",
                        "nombreTrabajador": "Carlos"
                    }
                    ]
}

Códigos de error

Código Significado
200 Operación exitosa
400 Solicitud inválida (parámetros incorrectos)
401 Token no proporcionado, inválido o revocado
500 Error interno del servidor

Health Check

GET

Estado del servicio

Endpoint público para verificar que la API de integración está operativa. No requiere autenticación.

Terminal
curl https://apialert.c-centralizador.com/api/integration/health

Respuesta:

200 OK
{
                    "status": "ok",
                    "timestamp": "2026-07-07T07:30:00Z",
                    "service": "yapealerta-integration"
}

Ejemplos de Implementación

Código ejemplo

Receptor de Webhook

C# / .NET
Node.js
Python
YapeWebhookController.cs
// Controlador ASP.NET para recibir webhooks
[ApiController]
[Route("api/webhooks")]
public class YapeWebhookController : ControllerBase
{
                        private readonly ILogger _logger;
    
                        public YapeWebhookController(ILogger logger)
                        {
        _logger = logger;
                        }
    
                        [HttpPost("yape")]
                        public async Task ReceiveYapeWebhook([FromBody] YapeWebHook webhook)
                        {
                        // Registra la notificación recibida
        _logger.LogInformation($"Webhook recibido: Pago {webhook.Tipo} de {webhook.NombreCliente} por S/{webhook.Monto}");
        
                        // Procesa la notificación según tus necesidades
                        await ProcessPaymentNotification(webhook);
        
                        // Responde con éxito
                        return Ok(new { success = true });
                        }
    
                        private async Task ProcessPaymentNotification(YapeWebHook webhook)
                        {
                        // Implementa tu lógica para procesar el pago
        // Por ejemplo: actualizar base de datos, enviar notificaciones, etc.
                        }
}
yapeWebhookHandler.js
// Servidor Express para recibir webhooks de BiPe Alerta
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
const PORT = process.env.PORT || 3000;

// Middleware para analizar JSON
app.use(bodyParser.json());

// Endpoint para recibir webhooks de Yape
app.post('/api/webhooks/yape', async (req, res) => {
                        try {
                        const webhook = req.body;
    
                        // Registra la recepción del webhook
    console.log(`Webhook recibido: Pago ${webhook.Tipo} de ${webhook.NombreCliente} por S/${webhook.Monto}`);
    
                        // Procesa la notificación
                        await processPaymentNotification(webhook);
    
                        // Responde con éxito
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Error al procesar el webhook:', error);
    res.status(500).json({ 
      success: false, 
      error: 'Error al procesar la notificación' 
    });
  }
});

// Función para procesar las notificaciones de pago
async function processPaymentNotification(webhook) {
                        // Aquí va tu lógica para procesar el pago
  // Por ejemplo:
  // - Actualizar el estado de un pedido en la base de datos
  // - Enviar una notificación al cliente o vendedor
  // - Generar un comprobante o factura
  // - etc.
  
                        // Ejemplo: Verificar estado del pago
                        if (webhook.Estado === "Completado") {
                        // Actualiza el estado del pedido o inventario
  }
}

// Iniciar el servidor
app.listen(PORT, () => {
  console.log(`Servidor de webhooks escuchando en el puerto ${PORT}`);
});
yape_webhook_handler.py
# Servidor Flask para recibir webhooks de BiPe Alerta
from flask import Flask, request, jsonify
import logging
from datetime import datetime

# Configuración de logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('bipe-webhook')

app = Flask(__name__)

# Endpoint para recibir webhooks de Yape
@app.route('/api/webhooks/yape', methods=['POST'])
def yape_webhook():
                        # Obtener el JSON recibido
    webhook_data = request.json
    
                        # Registrar la notificación recibida
    logger.info(
                        f"Webhook recibido: Pago {webhook_data.get('Tipo')} de"
                        f" {webhook_data.get('NombreCliente')} por S/{webhook_data.get('Monto')}"
    )
    
                        # Procesar la notificación
    process_payment_notification(webhook_data)
    
                        # Responder con éxito
                        return jsonify({"success": True})

def process_payment_notification(webhook_data):
                        # Extraer información relevante
    payment_id = webhook_data.get('Id')
    client_name = webhook_data.get('NombreCliente')
    amount = webhook_data.get('Monto')
    payment_type = webhook_data.get('Tipo')
    payment_status = webhook_data.get('Estado')
    
                        # Convertir la fecha y hora
                        try:
        payment_datetime = datetime.fromisoformat(webhook_data.get('FechaHora').replace('Z', '+00:00'))
                        except ValueError:
        payment_datetime = datetime.now()  # Valor predeterminado si hay error de formato
    
                        # Implementa tu lógica de negocio aquí
    # Por ejemplo:
    # - Actualizar estado de pedidos en la base de datos
    # - Enviar confirmaciones por correo electrónico
    # - Actualizar inventario
    # - etc.
    
                        # Ejemplo de lógica básica
                        if payment_status == "Completado":
        logger.info(f"Procesando pago completado #{payment_id} de {client_name}")
                        # Aquí actualizarías tu base de datos o sistema

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)

Consideraciones de Seguridad

Seguridad

Protección de tu Endpoint

Para asegurar que solo BiPe Alerta pueda enviar notificaciones a tu webhook, te recomendamos implementar las siguientes medidas de seguridad:

  • Usa HTTPS para tu endpoint
  • Verifica la autenticidad de las solicitudes mediante headers de autenticación
  • Implementa validación de IPs conocidas
  • Registra todas las solicitudes para detectar posibles abusos
Consejo de seguridad
Puedes utilizar los tokens de API para autenticar llamadas entrantes a tu webhook verificando que provienen de fuentes autorizadas.