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

# Dispersiones

> Consulta lo que Cobrix transfirió a tus cuentas de los cobros por débito inmediato, para conciliar

**Qué te llegó, a qué cuenta y de qué ventas.**
Cuando tus clientes pagan por débito inmediato, Cobrix recibe el dinero y luego te lo transfiere. Cada transferencia a tus cuentas es una dispersión. Con estos tres endpoints tu sistema concilia solo, sin copiar nada del panel. Los montos son los mismos que ves en «Dispersiones».

payouts:read

## Operaciones

| Permiso del drawer | Scope | Método y ruta |
| - | - | - |
| Ver dispersiones | `payouts:read` | `GET /integrations/v1/{companyId}/payouts` |
| Ver dispersiones | `payouts:read` | `GET /integrations/v1/{companyId}/payouts/{payoutId}` |
| Ver dispersiones | `payouts:read` | `GET /integrations/v1/{companyId}/payouts/{payoutId}/payments` |

**1. Pide tus dispersiones**

`GET /payouts` sin filtros devuelve las más nuevas primero. Si quieres un periodo, agrega `createdFrom` y `createdTo`. Una fecha sola, como `2026-11-30`, cuenta el día completo en hora de Caracas. Para filtrar por estado, usa `status`.

**2. Mira a qué cuentas fue el dinero**

`GET /payouts/{payoutId}` trae una transferencia por cuenta. Cada una muestra el banco, los últimos 4 dígitos (`•••• 2345`), el estado y el `bankReference`, que es la referencia que vas a ver en tu estado de cuenta.

**3. Une cada monto con tus ventas**

`GET /payouts/{payoutId}/payments` lista las ventas de esa dispersión, cada una con el `amountMinor` que esta dispersión te envió de ella. Únela a tu venta por `paymentId`, el mismo de `payment.succeeded` y de un débito de `POST /direct-debits`, o por el `sessionId` que te respondió `POST collection-documents/checkout-sessions`.

## Los tres montos de una dispersión

| Campo | Qué es |
| - | - |
| `salesMinor` | Lo que pagaron tus clientes |
| `costMinor` | El costo del débito más la comisión del otro banco |
| `receivedMinor` | Lo que llegó a tus cuentas |

En el caso normal, `salesMinor − costMinor = receivedMinor`. Si no cuadra, es porque una parte se movió a otra cuenta o a otra dispersión: el estado `partly_redirected` y las transferencias te dicen dónde fue. Los montos van en unidades menores, como en el resto de la API.

## Estados

| Estado | En una dispersión | En una transferencia |
| - | - | - |
| `in_transit` | Va en camino | Va en camino |
| `received` | Todo llegó | Llegó; trae `bankReference` y `receivedAt` |
| `partly_redirected` | Una cuenta rechazó el dinero y esa parte fue a tu cuenta principal | No aplica |
| `refused` | No aplica | El banco rechazó esa cuenta; su parte fue a la principal |
| `retrying` | No aplica | No salió; sale en la siguiente dispersión |
| `in_review` | Cobrix la está revisando | Cobrix la está revisando |

## Errores

| HTTP | `error.code` | Qué hacer |
| - | - | - |
| 400 | `invalid_filter` | Corrige el filtro que nombra el mensaje |
| 400 | `invalid_cursor` | Usa el `nextCursor` tal como lo recibiste |
| 403 | `insufficient_scope` | Pide a quien administra tus integraciones el permiso «Ver dispersiones» |
| 404 | `payout_not_found` | Revisa el `payoutId`; las dispersiones de otra empresa tampoco se ven |
| 503 | `payouts_busy` | Espera los segundos de `Retry-After` y reintenta |

> [!NOTE]
>
> Las cuentas siempre salen enmascaradas: nunca el número completo ni el titular.


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