Recordatorios de cobro

Tu organización decide en UTILIA OS cuándo y cuántas veces se recuerda cada factura pendiente, con qué tono y por dónde (correo y, si lo tiene, WhatsApp). Esos recordatorios salen solos y se paran en cuanto la factura consta como pagada.

Desde tu aplicación puedes ver los recordatorios de una factura tuya y hacer lo mismo que el equipo desde la factura: pausarlos, reanudarlos o registrar que el cliente ha prometido pagar un día. Configurar las reglas no se hace por la API: se hace en UTILIA OS, y la guía de uso está en Recordatorios de cobro de tus facturas.

Las cuatro rutas buscan la factura por su identificador, tu aplicación y el usuario indicado. Si es de otra aplicación o de otro usuario, la respuesta es un 404 INVOICE_NOT_ACCESSIBLE, igual que el de una factura que no existe.

Plan y permisos

Además, la aplicación actúa en nombre de su persona responsable, que tiene que poder ver esa factura en UTILIA OS y, para pausar, reanudar o registrar una promesa, también enviarla. Si no puede, la respuesta es 403 APP_RESPONSIBLE_PERMISSION_DENIED: lo arregla un administrador de tu organización, dándole ese permiso o nombrando otra persona responsable.

Estas rutas no tienen periodo de gracia: sin el permiso de la API, 403 INSUFFICIENT_SCOPE. Exigen también la facturación de la aplicación activada (403 BILLING_NOT_ENABLED).

Consultar los recordatorios

userIdqueryobligatorio

Identificador del usuario en tu aplicación (externalId) al que pertenece la factura.

Respuesta (200)

{
  "invoiceId": "ckinv1234567890",
  "policy": { "id": "ckpol01", "name": "Por defecto", "source": "DEFAULT" },
  "status": "PAUSED",
  "reason": "PAUSED",
  "reasonText": "Recordatorios en pausa hasta el martes, 3 de noviembre.",
  "pendingAmount": "1200.00",
  "currency": "EUR",
  "state": {
    "status": "PAUSED",
    "pausedUntil": "2026-11-03T00:00:00.000Z",
    "pauseReason": "PROMISE_TO_PAY",
    "promisedPaymentDate": "2026-11-01T00:00:00.000Z",
    "promisedAmount": null,
    "sentCount": 2,
    "lastSentAt": "2026-10-27T09:00:00.000Z",
    "escalated": false,
    "stopReason": null
  },
  "upcoming": [
    {
      "plannedDate": "2026-11-03",
      "sendAt": "2026-11-03T09:00:00.000Z",
      "kind": "AFTER_DUE",
      "occurrence": 1,
      "channels": ["EMAIL"],
      "tone": "NEUTRAL",
      "shifted": false
    }
  ],
  "history": [
    {
      "id": "cklog01",
      "sentAt": "2026-10-27T09:00:00.000Z",
      "channel": "EMAIL",
      "success": true,
      "outcome": "SENT",
      "reason": null,
      "kind": "REMINDER",
      "stepKind": "ON_DUE",
      "tone": "FRIENDLY",
      "manual": false,
      "fallbackFromWhatsApp": false
    }
  ]
}

statusstringobligatorio

ACTIVE (en seguimiento), PAUSED, STOPPED (parados: pagada, anulada...), COMPLETED (ya salieron todos) o NONE (a esta factura no le tocan recordatorios).

reason / reasonTextstring

Por qué no va a salir nada, como código estable y como frase lista para enseñar.

stateobjeto

Pausa, promesa de pago, envíos hechos, si el seguimiento pasó a una persona del equipo (escalated) y el motivo de la parada. null si la factura todavía no ha entrado en los recordatorios.

upcomingobjeto[]obligatorio

Hasta 12 próximos envíos, con el día, la hora, el momento (antes, el día o después del vencimiento), el tono y los canales que de verdad saldrían.

historyobjeto[]obligatorio

Hasta 50 recordatorios enviados o intentados, del más reciente al más antiguo, con su canal y su resultado.

La respuesta nunca trae a quién se escribió, su correo, su teléfono ni el enlace de pago.

Pausar

userIdstringobligatorio

Identificador del usuario en tu aplicación (externalId).

reasonenum

MANUAL (por defecto) o DISPUTE, si la factura está en discusión con el cliente.

untilstring

Día (AAAA-MM-DD, en la zona horaria de tu organización) en que se reanudan solos: desde mañana y como mucho dentro de 180 días. Sin él, siguen en pausa hasta que llames a resume.

notestring

Nota para el equipo, hasta 1.000 caracteres. La ve en la factura; el cliente no.

Reanudar

Los días que pasaron en pausa no se recuperan: no sale de golpe lo que no salió. Si los recordatorios no estaban en pausa, 409 PAYMENT_REMINDER_NOT_PAUSED.

Registrar una promesa de pago

userIdstringobligatorio

Identificador del usuario en tu aplicación (externalId).

promisedPaymentDatestringobligatorio

Día prometido (AAAA-MM-DD, en la zona horaria de tu organización), de hoy a 180 días.

promisedAmountnumber

Importe prometido, si no es todo lo pendiente. No puede superar lo pendiente.

notestring

Nota para el equipo, hasta 1.000 caracteres.

Las tres acciones responden 200 con la misma forma que la consulta, ya con el cambio aplicado, y ninguna envía nada al cliente.

Errores

Avisos a tu servidor

Si tu aplicación se suscribe, recibe dos avisos de cada factura suya (o de todas las de tu organización, si son facturas del equipo):

• INVOICE_REMINDER_SENT: ha salido un recordatorio. Llega uno por canal y dice cuál (EMAIL o WHATSAPP), el momento del paso, el tono y cuántos lleva la factura.
• INVOICE_REMINDER_STATE_CHANGED: han cambiado sus recordatorios. reminders.change vale PAUSED, RESUMED, PROMISED, STOPPED o ESCALATED.

Ninguno lleva el destinatario, su teléfono, su correo ni el enlace de pago. Su forma está en Eventos de los avisos.

Ejemplo: registrar una promesa de pago

curl -X POST 'https://os.utilia.ai/api/external/v1/invoices/ckinv1234567890/reminders/promise' \
  -H "X-Api-Key: utl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_01HXYZ", "promisedPaymentDate": "2026-11-20"}'

sdk.invoices.reminders está en los dos SDK oficiales desde la versión 4.8.0.