---
title: "Listar los movimientos de saldo"
method: GET
path: "/transactions"
tags: ["account"]
---

# Listar los movimientos de saldo

`GET /transactions`

## Request

- Base URL: `https://api.enviadores.com.mx/api/v1`
- URL: `https://api.enviadores.com.mx/api/v1/transactions`
- Auth: HTTP bearer

El libro mayor detrás de `GET /balance`: cargos por guías, reembolsos por cancelación, recargas y ajustes manuales, del más reciente al más antiguo. Es la respuesta a "¿en qué se fue el saldo?".

**Mismo principal que `GET /balance`, por construcción.** Sin header: el saldo PERSONAL del usuario de la llave. Con `X-PDV-ID` validado (llaves admin, misma allowlist): el libro mayor de ese fondo de punto de venta. Las consultas cruzadas por `user_id` del endpoint interno NO existen aquí: una llave lee exactamente el fondo que cargarían sus envíos.

`amount` viene con SIGNO en MXN (negativo = salió dinero) y `balance_after` es el saldo tras ese movimiento. `type` usa un vocabulario público de cuatro palabras (`charge`, `refund`, `topup`, `adjustment`) que resume el enum interno; los detalles internos (qué reventa, qué pierna de una corrección, qué programa) no se exponen.

En modo de prueba el listado se DERIVA de los envíos sandbox — un cargo al crear, un reembolso al cancelar — de modo que la suma cuadra exactamente con el saldo computado del sandbox. Requiere scope `balance:read`.

## Query parameters

- `page` integer
- `limit` integer
- `type` 'charge' | 'refund' | 'topup' | 'adjustment'
- `from` string, date
- `to` string, date

## Headers

- `X-PDV-ID` string

## Response `200`

Página de movimientos.

- object
  - `success` unknown, required
  - `data` object, required
    - `transactions` Transaction[], required
      - `id` string, required: Id del movimiento (estable; el que conviene citar a soporte).
      - `type` 'charge' | 'refund' | 'topup' | 'adjustment', required: Vocabulario público: cargo, devolución, recarga en línea, o cualquier otro abono.
      - `amount` number, required: Importe en MXN CON SIGNO: negativo si salió saldo, positivo si entró.
      - `balance_after` number, nullable, required: Saldo del principal después de este movimiento.
      - `shipment_id` string, nullable, required: Envío relacionado, cuando el movimiento nació de uno.
      - `description` string, nullable, required: Texto del movimiento. Las correcciones de cargo (cuando reasignamos un cobro al fondo correcto) se reportan siempre como `Ajuste`: el detalle interno describe nuestra propia contabilidad y nombra al operador que la hizo, y nada de eso viaja a esta superficie.
      - `created_at` string, date-time, nullable, required: ISO-8601 en UTC (Z).
    - `pagination` Pagination, required
      - `page` integer, required
      - `limit` integer, required
      - `total` integer, required
  - `requestId` string, required: Correlación de logs; también en el header `X-Request-Id`.

## Other responses

- `401`: `UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).
- `403`: `INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).
- `404`: `NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).
- `422`: `VALIDATION_ERROR` — `type` fuera del enum, fecha mal formada o `from` posterior a `to` (campos en `details.fields`).
- `429`: `RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.
- `500`: `SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.

---

[API](https://skmtc.dev/enviadores/apis/enviadores-public-api.md) · [All operations](https://skmtc.dev/enviadores/apis/enviadores-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/enviadores/apis/enviadores-public-api/revisions/3633f08c889c?raw)