# Transferencias

<!-- Fuente: https://docs.efipay.co/transfers -->

---

- [Transferencias](#transferencias)
  - [Qué es una transferencia](#overview)
  - [Listar transferencias](#get)
  - [Estados](#estados)

## Qué es una transferencia [#overview]

Una **transferencia** es el envío de dinero desde tu cuenta virtual de Efipay hacia una
cuenta bancaria. Es el paso final del ciclo: cobras a tus clientes, el dinero se acumula
en tu cuenta virtual como [movimientos](/movements), y de ahí sale
al banco.

:::note
**La API es de solo lectura.** No hay endpoint para *crear* una transferencia ni
una dispersión: se solicitan desde el panel de Efipay. Este endpoint existe para que
puedas conciliar lo que ya salió.
:::

## Listar transferencias [#get]

**Descripción:** Devuelve las transferencias asociadas a tus sucursales, paginadas.
Todos los filtros son opcionales; sin filtros trae todo.

`GET /api/v1/transfer`

| Nombre del campo | Descripción | Reglas |
| - | - | - |
| start_date | Desde qué fecha, sobre la fecha de creación | `['nullable', 'date_format:Y-m-d', 'before_or_equal:finish_date']` |
| finish_date | Hasta qué fecha. No puede ser futura | `['nullable', 'date_format:Y-m-d', 'before_or_equal:today', 'after_or_equal:start_date']` |
| offices | Ids de las sucursales a incluir. Sin este filtro se incluyen todas [las tuyas](/commercio) | `['nullable', 'array']` |
| offices.* | Cada id debe ser de una de tus sucursales | `['required', 'exists:offices,id']` |

:::caution
Este endpoint **no acepta `per_page`**: siempre devuelve 15 por página, y
**no garantiza un orden**. Si necesitas las más recientes primero, ordena por
`created_at` de tu lado después de recorrer todas las páginas.
:::

`GET /api/v1/transfer`

```bash
curl -X GET \
'/api/v1/transfer?start_date=2026-07-01&finish_date=2026-07-31&offices[]=1' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'
```

:::tip
Respuesta satisfactoria
:::

Código de respuesta: 200

```json
{
    "data": [
        {
            "id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
            "amount": 1500000,
            "transfer_charge": 7500,
            "gravamen": 6000,
            "total": 1486500,
            "status": "Transferido",
            "comments": null,
            "transferable_type": "Transferencia Manual",
            "transferable": {
                "amount": 1500000,
                "transfer_charge": 7500,
                "office_id": 1,
                "economic_group_id": null
            },
            "bankable": {
                "bank_name": "Bancolombia",
                "account_holder": "Comercio de Prueba S.A.S.",
                "last_four_numbers": "4321",
                "identification_number": "901234567",
                "is_approved": true
            },
            "created_at": "2026-07-15T09:00:00.000000Z"
        }
    ],
    "links": {
        "first": "https://sag.efipay.co/api/v1/transfer?page=1",
        "last": "https://sag.efipay.co/api/v1/transfer?page=3",
        "prev": null,
        "next": "https://sag.efipay.co/api/v1/transfer?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "per_page": 15,
        "to": 15,
        "total": 42
    }
}
```

**Qué es cada monto**

| Campo | Significado |
| - | - |
| amount | Lo que se solicitó transferir |
| transfer_charge | Costo de la transferencia |
| gravamen | Gravamen a los movimientos financieros (4×1000), cuando aplica |
| total | **Lo que efectivamente llegó al banco**: `amount − transfer_charge − gravamen` |
| comments | Nota interna. Cuando una transferencia se cancela, aquí suele estar el motivo |

**De dónde salió: `transferable_type`**

| Valor | Qué fue |
| - | - |
| `Transferencia Manual` | La solicitaste tú desde el panel |
| `Transferencia Programada` | Salió de una programación recurrente |
| `Transferencia a terceros` | Una dispersión hacia cuentas que no son la tuya |

El objeto `transferable` cambia de forma según ese tipo, y `bankable` describe la cuenta
de destino (`last_four_numbers` son los últimos cuatro dígitos; nunca devolvemos el
número completo).

## Estados [#estados]

| Estado | Qué significa |
| - | - |
| `Recibido` | La solicitud entró y está en cola |
| `En Proceso` | Se está enviando al banco |
| `Transferido` | El dinero salió. Es el estado final de una transferencia exitosa |
| `Cancelado` | No se realizó. El motivo suele venir en `comments` |

:::danger
Rango de fechas inválido
:::

Código de respuesta: 422

```json
{
    "message": "El campo finish_date debe ser una fecha anterior o igual a hoy.",
    "errors": {
        "finish_date": [
            "El campo finish_date debe ser una fecha anterior o igual a hoy."
        ]
    }
}
```