SimBot

Buzón transitorio de avisos de pago recibidos de pasarelas y bancos (Bancamiga pago móvil y transferencia, Humaniz, Reserve, Binance, log de Mailgun, ...). Cada fila guarda un aviso con su payload en el formato original del proveedor y caduca a los pocos minutos (expires_at).

Propósito

Sirve para conciliar pagos manuales: el operador busca por los últimos dígitos de la referencia (sim-bots/search) y, si encuentra el aviso, lo acepta (set-accepted), lo que marca el pago de la orden indicada. Al aceptarlo, type pasa de payment_registered a payment_approved.

Accesores normalizados

payload es heterogéneo según el proveedor; estos accesores lo traducen a un formato común: name (medio de pago legible), payment_amount / payment_amount_e2 / payment_currency / payment_money, source_phone / source_account / source_bank / source_dni (datos del pagador), ref_id / ref_pk (referencia), date_time, description y has_expired.

Estructura de Datos

Atributo Tipo Descripción
id int
type string Estado del aviso: payment_registered, payment_processing, payment_approved o mailgun_log.
subtype string Origen del aviso (humaniz, pago móvil/CI de Bancamiga, reserve, ...); determina cómo se lee el payload.
identifier string Identificador del aviso; suele terminar en la referencia del pago, por la que se busca.
payload array Contenido del aviso en el formato original del proveedor.
expires_at datetime Momento en que el aviso caduca.
created_at datetime\|null Fecha de recepción.
updated_at datetime\|null Fecha de última modificación.
company_id int\|null Compañía a la que pertenece el aviso (oculto en la respuesta).
allLogs ApiLog> Registros de auditoría de la API, incluidos los internos.
date_time datetime\|null Fecha/hora del pago, normalizada desde el payload.
description datetime\|null Descripción/concepto del pago, normalizada desde el payload.
has_expired bool true si expires_at ya pasó.
logs ApiLog> Registros de auditoría de la API visibles.
name string\|null Nombre legible del medio de pago (Pago Móvil, Transferencia Bancaria, ...).
payment_amount float\|null Monto del pago, normalizado desde el payload.
payment_amount_e2 int\|null Monto del pago en céntimos.
payment_currency string\|null ISO de la moneda del pago.
payment_money Money\|null Monto del pago como objeto Money en la moneda de la compañía.
ref_id string\|null Referencia del pago, normalizada desde el payload.
ref_pk string\|null Referencia única compuesta (fecha + ref_id) usada para deduplicar.
source_account string\|null Cuenta de origen del pago.
source_bank string\|null Banco de origen del pago.
source_dni string\|null Documento de identidad del pagador.
source_phone string\|null Teléfono del pagador. 
{
    "name": null,
    "payment_money": null,
    "source_phone": null,
    "source_account": null,
    "source_bank": null,
    "source_dni": null,
    "ref_id": null,
    "date_time": null,
    "description": null
}

Endpoints

Actualizar SimBot

Aceptar un aviso de pago

Marca el SimBot como payment_approved y, si se envía order_id, registra el pago correspondiente en esa orden (confirmándola si estaba sin pagar).

Método URI Cabeceras
POST /companies/{companyId}/sim-bots/{simBotId}/set-accepted Authorization 
{
    "order_id": "nullable|integer|min:0"
}

Acciones de SimBot

Buscar avisos de pago por referencia

{info} Soporta: Paginación Filters Carga dinámica

Fuerza una sincronización de pagos y devuelve, para el code (últimos dígitos de la referencia): pending (avisos SimBot de tipo payment_registered sin conciliar) y approved (pagos ya aprobados que coinciden).

Método URI Cabeceras
GET /companies/{companyId}/sim-bots/search Authorization 
{
    "code": "required|string|min:6|max:32"
}

Relaciones