Webhook de actividad completada en plan
Allaria envía una notificación al endpoint registrado del partner cada vez que una liberación (claim) o un retiro de una suscripción a plan de ahorro es completado. El partner debe implementar este endpoint para recibir estas notificaciones.
El request se envía como HTTP POST a la URL completa que el partner registró. La ruta es propia del partner — Allaria no impone ninguna:
la URL que registrastePor ejemplo, un partner que registra https://api.partner.com/webhooks/allaria/plan-activity recibe todas las notificaciones ahí.
Las liberaciones y los retiros llegan a la misma URL. Nombrá el endpoint en consecuencia — una ruta nombrada por una sola de las dos operaciones va a recibir igual la otra.
El campo activity_type del body es el que las distingue, y tiene cuatro valores posibles, no dos: una operación parcial informa PARTIALLY_CLAIM o PARTIALLY_WITHDRAWAL con plan_status: ACTIVE.
Relacioná por activity_id y no por los demás campos: una suscripción puede tener varias operaciones parciales del mismo tipo y monto, y nada más en el body las distingue.
Ese mismo id es:
- el que devuelven el Rescate y el Retiro al momento de pedir la operación;
- el
idde la actividad en Obtener actividades de una suscripción.
Enviá la URL completa en la que querés recibir las notificaciones a integraciones@allaria.com.ar, una por ambiente. No hay endpoint para esto — la URL se configura del lado de Allaria cuando se da de alta tu integración.
Hasta que esté registrada no se envía ninguna notificación y no falla nada de forma visible.
Request
Allaria envía este request al partner. El partner debe exponer el endpoint y responder con un código 2XX para confirmar la recepción.
Headers
| Campo | Tipo | Descripción |
|---|---|---|
Content-Type | string | Siempre application/json |
Path Parameters
No aplica.
Query Parameters
No aplica.
Body
| Campo | Tipo | Descripción |
|---|---|---|
activity_id | number | Identificador de la actividad completada: el mismo valor que devuelven el Rescate y el Retiro al pedir la operación. Relacioná la notificación por este campo. |
account_investment_plan_id | number | Identificador de la suscripción. |
account_number | number | Número de cuenta asociada a la suscripción. |
activity_type | string | Tipo de actividad completada. Ver Valores de tipo de actividad a continuación. |
amount | number | Monto involucrado en la operación. En una liberación o retiro total, el monto efectivamente transferido. |
currency | string | Moneda del monto. Valores posibles: ARS, USD. |
plan_status | string | Estado actualizado de la suscripción tras la operación. Ver Valores de estado a continuación. |
Valores de tipo de actividad
| Valor | Descripción |
|---|---|
CLAIM | Liberación total — todas las cuotapartes fueron transferidas al partner y la suscripción está cerrada. |
PARTIALLY_CLAIM | Liberación parcial — una porción de las cuotapartes fue transferida al partner; la suscripción permanece activa. |
WITHDRAWAL | Retiro total — todos los fondos fueron devueltos al CVU del usuario y la suscripción está cerrada. |
PARTIALLY_WITHDRAWAL | Retiro parcial — una porción de los fondos fue devuelta al CVU del usuario; la suscripción permanece activa. |
Valores de estado
| Valor | Descripción |
|---|---|
ACTIVE | La suscripción está activa y operando con normalidad. |
AWAITING_BIND | Esperando que el usuario apruebe la recurrencia de débito directo DEBIN en su aplicación bancaria. |
PAUSED_BY_CONSECUTIVE_ERRORS_DEBIN | Pausada automáticamente tras tres fallas consecutivas de DEBIN. Allaria cancela la suscripción si este estado persiste. |
PAUSED_BY_USER | Pausada a pedido del usuario. |
AWAITING_ASSET_TRANSFER | Una liberación o retiro está en curso; las cuotapartes están siendo transferidas. |
AWAITING_ASSET_WITHDRAWAL | Las cuotapartes están siendo liquidadas a efectivo. |
AWAITING_CASH_TRANSFER | La transferencia de efectivo al CVU de destino está en curso. |
CLAIMED | Todas las cuotapartes fueron transferidas al partner. La suscripción está cerrada. |
WITHDRAWN | Todos los fondos fueron devueltos al CVU del usuario. La suscripción está cerrada. |
BIND_ACTIVATION_FAILED | La suscripción de recurrencia DEBIN expiró sin aprobación del usuario. |
Ejemplo de payload
{
"activity_id": 4821,
"account_investment_plan_id": 42,
"account_number": 20000008,
"activity_type": "PARTIALLY_CLAIM",
"amount": 50000.00,
"currency": "ARS",
"plan_status": "ACTIVE"
}
Response
El partner debe responder con cualquier código 2XX para confirmar la recepción.
La notificación se envía solo cuando la operación quedó registrada de forma durable del lado de Allaria, así que el estado que informa siempre puede leerse desde Consultar suscripción y Consultar actividades de una suscripción.
Si Allaria recibe una respuesta que no es 2XX o el request falla, la notificación se reintenta automáticamente:
- con intervalos crecientes (1, 2, 4 … hasta 60 minutos) durante unas 4 horas;
- después deja de reintentarse y se concilia a mano.
Una notificación fallida no bloquea ni revierte la operación subyacente.
La entrega es al menos una vez: la misma notificación puede llegar más de una vez (por ejemplo, si tu endpoint la procesó pero la respuesta no llegó a Allaria). Usá activity_id para ignorar duplicados.
Cada intento se firma de nuevo, con un X-Allaria-Timestamp nuevo.