POST /movement/history

Devuelve un listado paginado de las transacciones de tu comercio en un rango de fechas determinado. Soporta filtrado por punto de cobro.

Request — sin filtros

POST {{BASE_URL}}/movement/history
api-key: {tu-api-key}
secret-key: {tu-clave-secreta}
authorization: {token-jwt}
Content-Type: application/json

{
  "body": {
    "pagination": {
      "start_date": "2026-06-01",
      "end_date":   "2026-06-15",
      "limit": 10
    }
  }
}

Request — con filtro por punto de cobro

{
  "body": {
    "pagination": {
      "start_date": "2026-06-01",
      "end_date":   "2026-06-15",
      "limit": 10
    },
    "filter": [
      {
        "id": "COLLECTION_ALIAS",
        "value": "Sitio web"
      }
    ]
  }
}

En este ejemplo “Sitio web” es el nombre del Botón de Pago creado en la plataforma web de Yappy Comercial.

Parámetros del request

Campo	Tipo / formato	Req	Descripción
`body.pagination.start_date`	string · `YYYY-MM-DD`	sí	Fecha de inicio del rango a consultar.
`body.pagination.end_date`	string · `YYYY-MM-DD`	sí	Fecha de fin del rango. Máximo 90 días desde `start_date`.
`body.pagination.limit`	number	sí	Número máximo de resultados por página (UAT: 250 y PROD: 500).
`body.pagination.token`	string	no	Token de paginación para avanzar a la página siguiente. Omitir en la primera consulta.
`body.filter`	array	no	Filtros a aplicar. Soporta `COLLECTION_ALIAS`.
`body.filter[].id`	string	sí*	Tipo de filtro. `“COLLECTION_ALIAS”`.
`body.filter[].value`	string	sí*	Nombre exacto del punto de cobro (case-sensitive). Obtenlo con `/collection-method`.

* Requerido solo cuando se incluye el array filter.

Ventana máxima de 90 días

El rango entre start_date y end_date no puede superar 90 días. Consultas con rangos más amplios recibirán un error de validación.

El valor de COLLECTION_ALIAS es exacto

El campo value del filtro COLLECTION_ALIAS debe coincidir exactamente con el nombre del punto de cobro tal como aparece en Yappy Comercial (incluyendo mayúsculas y espacios). Puedes obtener los nombres exactos con el endpoint GET /collection-method.

Response — 200 OK

{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "pagination": {
      "limit": 10,
      "token": "BH/ytDLG1hzQ9xTx...",
      "end_date": "2026-06-15",
      "start_date": "2026-06-01",
      "has_next_page": false
    },
    "transactions": [
      {
        "id": "FCIZK-90454086",
        "number": "MOCK-g80ijzik",
        "type": "TXN-ECOM",
        "status": "COMPLETED",
        "description": "Por pedido: xJoK02cTOEUI",
        "role": "CREDIT",
        "category": "INTRABANK",
        "fee": {
          "currency": "USD",
          "amount": 0.16
        },
        "charge": {
          "currency": "USD",
          "tax": 0,
          "tip": 0,
          "amount": 10.11,
          "partial_amount": 10.11
        },
        "debitor": {
          "alias": "+50768994657",
          "complete_name": "Kallie Keeling",
          "alias_type": "P",
          "bank_name": "Banco General"
        },
        "creditor": {
          "alias": "Sitio web",
          "complete_name": "Mi Comercio S.A.",
          "alias_type": "C",
          "bank_name": "Banco General"
        },
        "cut_off_date": "2026-06-10",
        "payment_date": "2026-06-10T14:31:11.173Z",
        "bill_description": "",
        "registration_date": "2026-06-10T14:31:10.000Z"
      }
    ]
  }
}

Diccionario de campos por transacción

Campo	Tipo	Descripción
`id`	string	ID único de la transacción. Úsalo en `/movement/{id}` y `/transaction/{id}`.
`number`	string	Número de referencia adicional.
`type`	string	Tipo de transacción — ver catálogos.
`status`	string	Tipo de estado — ver catálogos.
`description`	string	Descripción de la transacción, generada por el flujo de pago original.
`role`	string	`CREDIT` — el comercio recibe el pago. `DEBIT` — el comercio paga.
`category`	string	`INTRABANK` (mismo banco) o `INTERBANK` (bancos distintos).
`fee.amount`	number	Comisión cobrada por Yappy en USD.
`charge.amount`	number	Monto total cobrado al cliente en USD.
`charge.tip`	number	Propina incluida en el cobro.
`debitor.alias`	string	Teléfono o identificador del cliente que pagó.
`debitor.complete_name`	string	Nombre completo del cliente.
`creditor.alias`	string	Alias del punto de cobro del comercio.
`creditor.complete_name`	string	Nombre del comercio.
`cut_off_date`	string · date	Fecha de liquidación de la transacción.
`payment_date`	string · ISO 8601	Fecha y hora exacta del pago.
`registration_date`	string · ISO 8601	Fecha y hora de registro en Yappy.

Paginación: cómo recorrer todo el historial

La respuesta incluye dentro de body.pagination los campos token y has_next_page para navegar entre páginas.

Lógica de recorrido:

Primera página: envía el request sin pagination.token — solo start_date, end_date, limit y opcionalmente filter.
Páginas siguientes: si has_next_page es true, toma el token recibido en la respuesta e inclúyelo como pagination.token en el siguiente request.

{
  "body": {
    "pagination": {
      "start_date": "2026-06-01",
      "end_date":   "2026-06-15",
      "limit": 10,
      "token": "BH/ytDLG1hzQ9xTx..."
    }
  }
}

Fin del historial: cuando has_next_page sea false, ya obtuviste todos los resultados del rango de fecha consultado.

Errores posibles

Código	Significado
`YP-0001`	No se encontraron transacciones para el rango/filtro indicado.
`YP-0039`	El número de alias en el filtro supera el máximo de 25.
`YP-0040`	El `limit` está fuera del rango permitido.
`YP-0010`	Uno o más campos del body no tienen valores válidos.
`YP-0008`	Faltan headers obligatorios.

¿Te fue útil esta página?