> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qcobro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leer la recuperación

> Lee con client.recovery cuánto se recuperó en un período, su desglose por campaña, canal, resultado o días desde la última gestión, y la lista de recuperaciones detectadas.

El recurso `client.recovery` responde a una pregunta: **¿cuánto se recuperó en un período, y
qué lo explica?** Expone tres métodos de solo lectura: `summary`, `breakdown` y `list`.

Todos los métodos están **acotados al workspace activo** y validan su entrada en el cliente
antes de enviar la petición: una entrada inválida lanza un `ValidationError` y nunca llega a la
red. Un período son dos fechas `from` y `to` en formato `YYYY-MM-DD`, **ambas incluidas**, en la
zona horaria del workspace. `from` debe ser igual o anterior a `to`.

## Qué cuenta como una recuperación

QCobro registra una recuperación cuando una sincronización de cuentas muestra que se pagaron
cuotas vencidas. Hay tres tipos (`kind`):

| `kind` | Cuándo se registra | Importe |
| - | - | - |
| `PARTIAL` | Una cuenta sigue en el lote con menos `missedInstallments` que en la sincronización anterior. | Las cuotas que bajaron × el `termsAmount` de la cuenta. |
| `CAUGHT_UP` | Envías la cuenta en `exits` con `reason: "CAUGHT_UP"` (se puso al día). | `missedInstallments × termsAmount` de la salida. |
| `PAID_OFF` | Envías la cuenta en `exits` con `reason: "PAID_OFF"` (saldó la deuda). | `missedInstallments × termsAmount` de la salida. |

En las salidas, `missedInstallments` son las cuotas que estaban vencidas y ahora están pagadas,
y `termsAmount` es el importe de cada cuota. Consulta
[Sincronizar cuentas](https://docs.qcobro.com/sdk/sync-accounts.md#informa-las-salidas) para enviarlas.

Al registrar una recuperación, QCobro guarda una **instantánea** de las gestiones que tuvo la
cuenta entre la sincronización anterior y la que la detectó: canal, resultado, campañas activas
y días desde la última gestión. Esa instantánea **nunca se recalcula**, aunque después edites o
elimines las campañas que nombra.

Una recuperación cuenta en el período en que se detectó. Hay una excepción: si das motivo
`CAUGHT_UP` o `PAID_OFF` a una salida que se registró **sin motivo** (`UNKNOWN`), la recuperación
cuenta en la fecha en que la cuenta salió. Por eso la cifra de un período ya cerrado puede
subir al clasificar salidas (ver [Clasifica las salidas sin motivo](https://docs.qcobro.com/sdk/portfolios.md#clasifica-las-salidas-sin-motivo)).

> [!NOTE]
>
> QCobro solo ve lo que le envían tus exportaciones. Si no envías `missedInstallments` en las filas
> ni motivos en las salidas, no detecta ninguna recuperación.

## Obtén el resumen de un período

`summary` devuelve el importe recuperado en el período, separado según la cuenta tuviera o no
una gestión entre sincronizaciones, y cuántas salidas esperan todavía un motivo.

```ts theme={null}
const summary = await client.recovery.summary({
  from: "2026-10-01",
  to: "2026-10-31",
  portfolioId: "f47ac10b-..." // opcional
});
// → { recovered: 48200, count: 31, withoutGestion: 13300, withoutGestionCount: 9, pendingExits: 7, currency: "DOP" }
```

**from** `string` *required*

Fecha de inicio, incluida (`YYYY-MM-DD`).

**to** `string` *required*

Fecha de fin, incluida (`YYYY-MM-DD`).

**portfolioId** `string`

Limita el resultado a una cartera.

**recovered** `number`

Suma de las recuperaciones detectadas en el período cuya cuenta tuvo al menos una gestión entre
sincronizaciones. Es la cifra de **Recuperado**.

**count** `number`

Número de esas recuperaciones.

**withoutGestion** `number`

Suma de las recuperaciones del período sin ninguna gestión entre sincronizaciones.

**withoutGestionCount** `number`

Número de esas recuperaciones.

**pendingExits** `number`

Salidas sin motivo (`UNKNOWN`) que siguen abiertas **ahora**, con el mismo filtro de cartera. No
depende del período.

**currency** `string`

La moneda del workspace (por ejemplo `DOP`).

## Desglosa lo recuperado

`breakdown` reparte la cifra de **Recuperado** (solo las recuperaciones con gestión) según una
dimensión `by`. Las filas vienen ordenadas de mayor a menor importe.

```ts theme={null}
const breakdown = await client.recovery.breakdown({
  by: "CHANNEL",
  from: "2026-10-01",
  to: "2026-10-31"
});
// → { additive: true, rows: [{ key: "VOICE_AI", name: null, amount: 30100, count: 18 }, …] }
```

**by** `string` *required*

Dimensión por la que agrupar. Ver la tabla de abajo.

**from** `string` *required*

Fecha de inicio, incluida (`YYYY-MM-DD`).

**to** `string` *required*

Fecha de fin, incluida (`YYYY-MM-DD`).

**portfolioId** `string`

Limita el resultado a una cartera.

| `by` | `key` de cada fila |
| - | - |
| `CAMPAIGN` | El id de cada campaña activa en la cuenta; `name` trae su nombre en ese momento. |
| `CHANNEL` | El canal de la última gestión (por ejemplo `VOICE_AI` o `WHATSAPP`). |
| `OUTCOME` | El resultado de la última gestión o, si no tuvo resultado, su camino. |
| `DAYS_SINCE_TOUCH` | Días desde la última gestión hasta la sincronización que detectó la recuperación: `0-1`, `2-3`, `4-7` u `8+`. |

**additive** `boolean`

`true` cuando la suma de las filas es el total recuperado. Es `false` solo con `CAMPAIGN`.

**rows** `array`

Una fila por valor de la dimensión, con `key`, `name` (el nombre de la campaña con `CAMPAIGN`,
`null` en las demás), `amount` (suma de importes) y `count` (número de recuperaciones).

> [!WARNING]
>
> Con `CAMPAIGN`, cada campaña activa en una cuenta recibe el importe **completo** de su
> recuperación. Una recuperación con dos campañas cuenta en las dos filas, así que no sumes las
> filas para obtener el total: usa `summary`.

## Lista las recuperaciones

`list` devuelve una página de las recuperaciones detectadas en el período, de la más reciente a
la más antigua, junto con el total.

```ts theme={null}
const { items, total } = await client.recovery.list({
  from: "2026-10-01",
  to: "2026-10-31",
  hasGestion: false,
  limit: 50
});
```

**from** `string` *required*

Fecha de inicio, incluida (`YYYY-MM-DD`).

**to** `string` *required*

Fecha de fin, incluida (`YYYY-MM-DD`).

**portfolioId** `string`

Limita el resultado a una cartera.

**kind** `string`

Solo las recuperaciones de este tipo: `PARTIAL`, `CAUGHT_UP` o `PAID_OFF`.

**hasGestion** `boolean`

`true` para solo las que tuvieron una gestión entre sincronizaciones; `false` para solo las que
no. Omítelo para todas.

**limit** `number` (default: 50)

Número máximo de recuperaciones a devolver (1–200).

**offset** `number` (default: 0)

Número de recuperaciones a omitir desde el inicio (para paginar).

Cada elemento de `items` describe una recuperación:

**id** `string`

Id de la recuperación.

**portfolioId** `string`

Id de la cartera.

**portfolioAccountId** `string`

Id de la cuenta en QCobro.

**externalId** `string`

Tu identificador de la cuenta.

**fullName** `string`

Nombre completo del titular.

**kind** `string`

`PARTIAL`, `CAUGHT_UP` o `PAID_OFF`.

**installments** `number`

Cuotas recuperadas.

**amount** `number`

Importe recuperado: `installments × termsAmount`.

**detectedAt** `string`

Cuándo se detectó (ISO 8601). En una salida clasificada más tarde, la fecha en que la cuenta
salió.

**previousSyncAt** `string`

La sincronización anterior (ISO 8601): el inicio del intervalo de la instantánea.

**context** `object`

La instantánea de las gestiones entre `previousSyncAt` y `detectedAt`:

* `hasGestion`: si hubo al menos una gestión.
* `touches`: número de gestiones.
* `activeCampaigns`: las campañas de esas gestiones, cada una con `id` y `name`.
* `lastTouch`: la última gestión (`contactLogId`, `agentType`, `delivery`, `path`,
  `outcome`, `contactedAt`), o `null` si no hubo ninguna.
* `daysSinceLastTouch`: días enteros desde la última gestión hasta la sincronización, o
  `null`.

## Siguientes pasos

> [card] [Sincronizar cuentas](https://docs.qcobro.com/sdk/sync-accounts.md)
>
> Envía las filas y las salidas de las que salen las recuperaciones.

> [card] [Gestionar carteras](https://docs.qcobro.com/sdk/portfolios.md)
>
> Lista las salidas de una cartera y clasifica las que salieron sin motivo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.