Saltar al contenido principal

Paradas

Las Paradas SPIDI son URLs únicas y permanentes asignadas a cada cliente, con las que puede acceder a un espacio para consultar, gestionar y pagar todas sus solicitudes de pago activas o históricas, sin necesidad de recibir nuevos enlaces cada vez. Basta con acceder a su Parada para revisar o completar los pagos pendientes.

Funcionan como un punto de acceso trazable y constante, ideal para relaciones comerciales continuas, suscripciones o pagos recurrentes, simplificando la experiencia tanto para el pagador como para la empresa.

Desde una Parada, el cliente puede:

  • Visualizar solicitudes pendientes, pagadas o vencidas.
  • Pagar directamente, sin depender de nuevos envíos de enlace.
  • Consultar su historial de pagos y operaciones anteriores.

En escenarios de suscripciones, pagos recurrentes o relaciones comerciales continuas, las Paradas SPIDI son el acompañante ideal de las Solicitudes de Pago.

Cómo funcionan​

  • Cada Parada se crea y asocia mediante el API de SPIDI, vinculándola siempre a un mismo cliente o referencia o a múltiples clientes o referencias específicas de tu plataforma.

  • Posee una URL única y permanente, que el cliente puede visitar en cualquier momento para consultar y pagar.

  • Desde esa URL, el cliente ve todas sus solicitudes de pago (pendientes, vencidas o completadas), cada una con su payment_url generado por SPIDI.

  • Los pagos se procesan en la interfaz segura de SPIDI, con las mismas opciones inmediatas: débito bancario, Pago Móvil y Binance Pay (USDT), siempre con liquidación directa en bolívares.

  • La Parada puede configurarse para mostrar solo solicitudes activas o todo el historial, según las necesidades de tu plataforma.

  • Tu plataforma puede usar una única Parada por cliente o generar Paradas específicas por servicio, contrato o suscripción.

Integración técnica​

  • Las Paradas pueden crearse de forma individual o masiva mediante el endpoint
    POST /api/v1/ext/stops, que permite generar 1..N Paradas en un solo request.
    Esta función resulta clave para procesos de onboarding inicial (por ejemplo, 100 suscriptores) y reintentos idempotentes.

  • Cada Parada se identifica por un stop_id y puede consultarse o modificarse posteriormente.

  • Las Paradas agrupan las Solicitudes de Pago relacionadas con un mismo cliente o referencia lógica.

  • Es recomendable definir y mantener un campo internal_reference para cada recurso (cliente, contrato o factura), que servirá para:

    • Conciliar y auditar operaciones entre tu sistema y SPIDI.

    • Asociar solicitudes de pago con su Parada correspondiente.

Estados de una Parada​

  • Active: existe al menos un enlace de pago activo; se muestran los pagos disponibles en una lista con su identificador, monto y estado.

  • Empty (sin enlaces activos): la parada muestra el estado “no hay pagos disponibles”.

  • Disabled: la parada está deshabilitada temporalmente, pero puede reactivarse.

  • Deleted: la parada fue eliminada definitivamente.

⚙️ Resumen de endpoints​

  • Crear Parada (P): genera una o varias Paradas vinculadas a clientes o referencias internas.

  • Consultar Parada (P): devuelve el detalle y los enlaces de pago asociados.

  • Actualizar o deshabilitar Parada (P): permite ajustar título, mensaje o estado.

  • Eliminar Parada (P): baja definitiva, aunque se recomienda deshabilitar antes de eliminar.

Asociación entre Paradas y Solicitudes**

La asociación entre Paradas y Sesiones de Pago SPIDI permite vincular, en una sola llamada o de forma individual, los enlaces de pago (payment_url) derivados de cada sesión de pago (session_id) con una Parada (stop_id) específica.
Esta relación convierte cada Parada en un contenedor dinámico de sesiones activas, ofreciendo una experiencia continua para el cliente y una administración centralizada para el comercio.

Cada Parada puede tener 0, 1 o varias sesiones activas asociadas, todas compartiendo el mismo stop_id.
Los endpoints disponibles permiten operar en lote, reordenar o consultar las sesiones asociadas de forma eficiente y segura.

Concepto operativo​

  • Una Parada actúa como el punto de referencia único del cliente o suscripción.

  • Las sesiones de pago representan operaciones activas y se asocian a esa Parada; en la interfaz del cliente aparecen como sus enlaces de pago (payment_url).

  • Las empresas pueden agregar, remover, reemplazar, limpiar o reordenar las sesiones activas según sus procesos comerciales o ciclos de renovación.

  • La asociación es completamente dinámica, reversible y trazable mediante el API.

  • SPIDI mantiene una trazabilidad completa de todas las operaciones de asociación para auditoría y sincronización con tu sistema.

⚙️ Endpoints principales​

MétodoEndpointDescripción
POST{{base_url}}/api/v1/ext/payment-stops/batchEjecuta operaciones en lote para asociar, desasociar, reemplazar o limpiar sesiones de pago en una o varias Paradas. Soporta las operaciones add, remove, replace, clear. Idempotente mediante Idempotency-Key.
PATCH{{base_url}}/api/v1/ext/payment-stops/reorderDefine el orden de visualización de los enlaces de pago (payment_url) dentro de una Parada o en lote para varias.
GET{{base_url}}/api/v1/ext/payment-stops/{stop_id}/linksDevuelve la lista completa de sesiones asociadas a una Parada, incluyendo sus estados y sus enlaces de pago.
POST{{base_url}}/api/v1/ext/payment-stops/queryPermite consultar los enlaces activos de múltiples Paradas en una sola llamada, con filtros, paginación y reducción de campos. Optimizado para paneles y sincronización masiva.

Buenas prácticas de implementación​

  • Idempotencia: usa siempre Idempotency-Key en operaciones en lote; misma clave + mismo payload → misma respuesta.

  • Solo las sesiones en estado pending pueden asociarse como activas; las paid o expired se mueven automáticamente al histórico.

  • replace con session_ids: [] equivale a clear (limpieza total).

  • Usa reorder después de un replace o add para actualizar el orden visual.

  • Para sincronizar o renderizar múltiples Paradas, utiliza POST {{base_url}}/payment-stop/links/query, limitando los campos con only_fields para eficiencia.

  • Implementa webhooks de tipo stop.link_* para mantener tu backend sincronizado sin depender de polling frecuente.

Beneficios operativos​

  • Escalabilidad: maneja cientos de Paradas y miles de enlaces en pocas llamadas.

  • Flexibilidad: soporta operaciones masivas o por Parada individual.

  • Trazabilidad total: cada batch genera un batch_id para auditoría y conciliación.

  • Eficiencia: reduce la carga de consultas repetitivas con links/query.

  • Experiencia persistente: el cliente siempre accede al mismo stop_url, con sus enlaces actualizados automáticamente.