> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pay-me.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API de Consulta Masiva de Devolución
> Consulta una o más solicitudes de devolución mediante filtros.
El **API de Consulta Masiva de Devolución** permite consultar mediante filtros una o más solicitudes de devolución generadas anteriormente por el **API de Devoluciones**.
[https://api.preprod.alignet.io/refund](https://api.preprod.alignet.io/refund)
[https://api.alignet.io/refund](https://api.alignet.io/refund)
Esta consulta trabaja por filtros. `date_start` y `date_end` son obligatorios, mientras que el resto de parámetros ayudan a acotar la búsqueda para conciliación y seguimiento operativo.
***
## Request
### Query Params
| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :-------------------------- | :----------------------------------------- | :------------------------------------------------- | :----- | :---------- |
| `date_start` | Fecha de cuando se realizó el refund | `2025-05-26` | String | SI |
| `date_end` | Fecha final de cuando se realizó el refund | `2025-05-26` | String | SI |
| `merchant_code` | Código único del comercio | `41bb301e-3c37-4332-accb-ed5ec19081e4` | String | NO |
| `merchant_operation_number` | Número de operación de un pedido | `239766` | String | NO |
| `transaction_id` | UUID único de una transacción | `bko66gpi8czns4tcde93q96vd` | String | NO |
| `refund_state` | Estado del refund | `REGISTERED`, `IN_PROCESS`, `RESOLVED`, `REJECTED` | String | NO |
### Headers
| Campo | Descripción | Valor | Tipo | Obligatorio |
| :------------------------- | :------------------------------------------------------------------------------ | :---------------------- | :----- | :---------- |
| `Authorization` | Token de identificación para uso del API creado previamente en API de Seguridad | `Bearer ` | String | SI |
| `ALG-API-VERSION` | Versión del API a usar | `1709847567` | String | SI |
| `payment-facilitator-code` | Identificador del PF, obligatorio para Payment Facilitator | Cadena alfanumérica | String | NO |
***
## Response
| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :---------------------------------------- | :----------------------------------------------------------------------- | :------------------------------------------------- | :--------- | :---------- |
| `success` | Indica si el proceso se realizó correctamente | `true`, `false` | String | SI |
| `merchant_code` | Identificador del comercio | `41bb301e-3c37-4332-accb-ed5ec19081e4` | String | SI |
| `operations_count` | Cantidad de operaciones encontradas | `1` | String | SI |
| `operations` | Array que contiene objetos de transacciones a devolver | Array | Array | SI |
| `operations[].refund_id` | UUID único de la devolución | UUID | String | SI |
| `operations[].state` | Estado de la solicitud | `REGISTERED`, `IN_PROCESS`, `RESOLVED`, `REJECTED` | String | SI |
| `operations[].refund_reason` | Motivo o detalle asociado al estado | `Solicitud recibida y validada` | String | SI |
| `operations[].merchant_operation_number` | Número de pedido de la operación | `239766` | String | SI |
| `operations[].type` | Tipo de devolución | `TOTAL`, `PARTIAL` | String | SI |
| `operations[].transaction_id` | Código alfanumérico de la transacción | `bko66gpi8czns4tcde93q96vd` | String | SI |
| `operations[].refund_amount` | Monto a devolver en centavos | `1050` | String | SI |
| `operations[].transaction_amount` | Monto original de la transacción en centavos | `1050` | String | SI |
| `operations[].currency` | Código ISO 4217 de la moneda de la transacción | `604` | String | SI |
| `operations[].additional_fields` | Diccionario para enviar campos y valores personalizados como `key:value` | Dictionary | Dictionary | NO |
| `operations[].payment_method` | Objeto relacionado al medio y procesador de pago | Object | Object | SI |
| `operations[].payment_method.name` | Nombre del método de pago | `CARD`, `YAPE`, `CUOTEALO` | String | SI |
| `operations[].payment_method.brand` | Marca de la tarjeta | `VISA`, `MSCD`, `AMEX`, `DINC` | String | SI |
| `operations[].payment_method.masked_pan` | Tarjeta enmascarada | `447411******2240` | String | SI |
| `operations[].lifecycle` | Array que contiene listado de los estados por los que pasó la devolución | Array | Array | SI |
| `operations[].lifecycle[].state` | Estado de la devolución | `REGISTERED`, `IN_PROCESS`, `RESOLVED`, `REJECTED` | String | SI |
| `operations[].lifecycle[].date` | Objeto que contiene la fecha en la que se realizó el cambio de estado | Object | Object | SI |
| `operations[].lifecycle[].date.utc_time` | Fecha en UTC | `2025-05-26T06:06:45` | String | SI |
| `operations[].lifecycle[].date.unix_time` | Fecha en unix time | `1748239605` | Integer | SI |
| `meta` | Objeto que contiene metadatos del flujo ejecutado | Object | Object | SI |
| `meta.status` | Objeto que contiene el resultado del flujo ejecutado | Object | Object | SI |
| `meta.status.code` | Código que representa el resultado del flujo ejecutado | `00` | String | SI |
| `meta.status.message_ilgn` | Objeto que contiene el mensaje resultante del flujo | Object | Object | SI |
| `meta.status.message_ilgn[].locale` | Localidad a nivel de lenguaje para el mensaje del flujo ejecutado | `es_PE` | String | SI |
| `meta.status.message_ilgn[].value` | Mensaje resultante del flujo ejecutado | `Se procesó correctamente la petición` | String | SI |
### Ejemplo (JSON)
```json theme={"system"}
{
"success": "true",
"merchant_code": "41bb301e-3c37-4332-accb-ed5ec19081e4",
"operations_count": "1",
"operations": [
{
"refund_id": "922178aa-ce4c-4c5f-8190-82fa7e009425",
"state": "REGISTERED",
"refund_reason": "Solicitud recibida y validada",
"type": "TOTAL",
"merchant_operation_number": "239766",
"transaction_id": "bko66gpi8czns4tcde93q96vd",
"refund_amount": "1050",
"transaction_amount": "1050",
"currency": "604",
"payment_method": {
"name": "CARD",
"brand": "VISA",
"masked_pan": "447411******2240"
},
"additional_fields": {
"canal": "WEB",
"reason": "cliente no reconoció el consumo",
"description": "solicitud por desconocimiento"
},
"lifecycle": [
{
"state": "REGISTERED",
"date": {
"utc_time": "2025-05-26T06:06:45",
"unix_time": 1748239605
}
}
]
}
],
"meta": {
"status": {
"code": "00",
"message_ilgn": [
{
"locale": "es_PE",
"value": "Se procesó correctamente la petición"
}
]
}
}
}
```
***
## Siguiente paso
Usa la consulta unitaria cuando ya conozcas el `merchant_operation_number` exacto.
Revisa cómo interpretar `meta.status.code` para todas las APIs del módulo.