Saltar al contenido principal

Crear Parada(s)​

Descripción​

Crea una o múltiples Paradas SPIDI en un mismo request.

¿Qué son las Paradas SPIDI?​

Las Paradas SPIDI son espacios únicos y permanentes asociados a cada cliente, donde este puede consultar, gestionar y pagar todas sus solicitudes de pago activas o históricas, sin necesidad de recibir nuevos solicitudes de pago cada vez.

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.

Características principales​

  • URL permanente: Cada parada posee una stop_url única que el cliente puede visitar en cualquier momento
  • Gestión centralizada: Desde esa URL, el cliente ve todas sus solicitudes de pago (pendientes, vencidas o completadas)
  • Creación masiva: Permite crear de 1 a N paradas en un solo request, ideal para procesos de onboarding inicial
  • Idempotencia: Soporta reintentos idempotentes mediante Idempotency-Key
  • Asociación flexible: Puede vincularse a un cliente específico o a múltiples referencias según las necesidades de tu plataforma

Estados de una Parada​

  • Active: Existe al menos un enlace de pago activo; se muestran los pagos disponibles
  • Empty: Sin solicitudes de pago activas; muestra el mensaje configurado en empty_state_message
  • Disabled: Deshabilitada temporalmente, pero puede reactivarse
  • Deleted: Eliminada definitivamente

Integración técnica​

Se recomienda 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, y asociar solicitudes de pago con su Parada correspondiente.

Endpoint​

POST 
/api/v1/ext/payment-stops

Autenticación Requerida

Bearer / Token: BearerAuth

Requiere el uso de el token obtenido en /auth/login

Esquema: bearer (JWT)

Request​

Ejemplos de Body (JSON)​

Crear una sola parada​

{
  "continue_on_error": false,
  "spidi_id": "88eab2b9-739e-11f0-9e3f-42010a1ce014",
  "items": [
    {
      "internal_reference": "8233232",
      "stop_title": "Federico Díaz",
      "empty_state_message": "No tienes pagos pendientes",
      "status": "active"
    }
  ]
}

Crear múltiples paradas​

{
  "continue_on_error": false,
  "spidi_id": "88eab2b9-739e-11f0-9e3f-42010a1ce014",
  "items": [
    {
      "internal_reference": "8233232",
      "stop_title": "Federico Díaz",
      "empty_state_message": "No tienes pagos pendientes",
      "status": "active"
    },
    {
      "internal_reference": "8233235",
      "stop_title": "Juan González",
      "empty_state_message": "No tienes pagos pendientes",
      "status": "active"
    }
  ]
}

Responses​

Batch procesado exitosamente