Modificación Masiva de Cuotas

Descripción

Permite modificar cuotas de múltiples suscripciones en una sola operación. Soporta hasta 200 suscripciones por petición y hasta 60 cuotas por suscripción.

URL

PATCH /api/subscriptions/installments/bulk

Autenticación

Header Api-Token con token UUID proporcionado por MetrePay.

Petición

Headers

Header	Valor
Api-Token	Token UUID del comercio
Content-Type	application/json

Cuerpo

Campo	Condición	Tipo	Descripción
operations	Requerido	Array	Lista de operaciones por suscripción (máximo 200).
operations[].custom_identifier	Opcional	Texto	Identificador único de la suscripción.
operations[].custom_identifier2	Opcional	Texto	Segundo identificador personalizado.
operations[].updates	Requerido	Array	Lista de cuotas a modificar (máximo 60 por suscripción).
operations[].updates[].payment_date	Requerido	Texto (yyyy-MM-dd)	Fecha de la cuota a modificar (se utiliza para identificar la cuota).
operations[].updates[].amount	Requerido	Numérico (2 decimales)	Nuevo monto de la cuota.

Ejemplo

{
  "operations": [
    {
      "custom_identifier": "123123",
      "updates": [
        {
          "payment_date": "2026-02-28",
          "amount": 275000.00
        },
        {
          "payment_date": "2026-04-28",
          "amount": 299900.00
        }
      ]
    },
    {
      "custom_identifier": "11",
      "custom_identifier2": "11",
      "updates": [
        {
          "payment_date": "2026-02-01",
          "amount": 42000.00
        }
      ]
    },
    {
      "custom_identifier": "532132",
      "custom_identifier2": "2313",
      "updates": [
        {
          "payment_date": "2026-02-01",
          "amount": 42000.00
        }
      ]
    }
  ]
}

Respuesta

Respuesta Exitosa

Se retorna un resumen de las operaciones realizadas y un detalle por suscripción.

Campo	Descripción
summary.subscriptions_received	Cantidad de suscripciones recibidas en la petición.
summary.subscriptions_processed	Cantidad de suscripciones procesadas.
summary.updates_applied	Cantidad de actualizaciones exitosas.
summary.updates_failed	Cantidad de actualizaciones fallidas.
results[]	Detalle por suscripción con el estado de cada operación.

{
  "summary": {
    "subscriptions_received": 4,
    "subscriptions_processed": 3,
    "updates_applied": 2,
    "updates_failed": 1
  },
  "results": [
    {
      "custom_identifier": "SUB-001",
      "custom_identifier2": "0009",
      "status": "success",
      "updates": [
        {
          "payment_date": "2025-07-01",
          "status": "updated",
          "installment_id": 12345,
          "updated_fields": {
            "amount": 75000.00
          }
        },
        {
          "payment_date": "2025-08-01",
          "status": "failed"
        }
      ]
    },
    {
      "custom_identifier": "SUB-002",
      "custom_identifier2": "0101",
      "status": "failed",
      "error": {
        "code": "SUBSCRIPTION_NOT_FOUND",
        "message": "No existe una suscripción para los identificadores solicitados."
      }
    }
  ]
}

Respuestas de Error

Código HTTP	Descripción
400	JSON mal formado o con datos inválidos.
401	Token de autenticación inválido o ausente.
413	Payload demasiado grande (se excedió el límite de 200 suscripciones o 60 cuotas por suscripción).

Notas

• Se responde 200 OK si la petición estuvo bien formada, aunque el procesamiento interno sea parcialmente exitoso. El detalle del resultado se indica en la respuesta.
• Ambos identificadores son opcionales. Se busca la suscripción según los identificadores recibidos.
• Si se encuentra más de una suscripción para la combinación de identificadores proporcionada, se retorna error para esa suscripción.
• Si se encuentra más de una cuota con la misma fecha para una suscripción, se retorna error para esa cuota.
• Límites por petición:
  • Máximo 200 suscripciones en el array operations.
  • Máximo 60 cuotas en el array updates por suscripción.