Este documento describe cómo realizar búsquedas en la API de pagos utilizando diferentes parámetros. Los ejemplos incluyen búsquedas por email, número de socio (referencia externa), nombre del pagador y estado del pago.
1. Introducción
La API permite realizar búsquedas filtradas, paginadas y ordenadas sobre los pagos registrados. Los parámeros de búsqueda se envían como query strings en la URL.
2. Tipos de Parámetro
filters[]: Permite especificar los criterios de búsqueda.
- field: Campo sobre el cual se aplicará el filtro.
- value: Valor a buscar.
- operation: Operación que define cómo se compara el campo con el valor.
sorts[]: Define los criterios de ordenamiento.
<nombre del campo>: Campo a ordenar.- ascending/descending: Dirección del orden.
limit: Cantidad de registros por página.
page: Número de página a obtener.
3. Operaciones Disponibles
| Operación | Valor esperado | Descripción |
|---|---|---|
EXISTS | Boolean (true / false) | Consulta si el campo proporcionado existe o no en el objeto |
EQUAL | Texto, Número o Fecha | Compara por igualdad |
NOT_EQUAL | Texto, Número o Fecha | Compara por desigualdad |
GREATER_THAN | Texto, Número o Fecha | Compara por mayor estricto |
GREATER_THAN_OR_EQUAL_TO | Texto, Número o Fecha | Compara por mayor o igual |
LESS_THAN | Texto, Número o Fecha | Compara por menor estricto |
LESS_THAN_OR_EQUAL_TO | Texto, Número o Fecha | Compara por menor o igual |
IN | Lista [valor1,valor2,...] | Consulta si el valor del campo está incluído dentro del conjunto proporcionado. Incluir corchetes. |
NOT_IN | Lista [valor1,valor2,...] | Consulta si el valor del campo no está incluído dentro del conjunto proporcionado. Incluir corchetes. |
CONTAINS | String | Consulta si el valor del campo tiene como subcadena al valor proporcionado |
STARTS_WITH | String | Consulta si el valor del campo comienza con el valor proporcionado |
ENDS_WITH | String | Consulta si el valor del campo finaliza con el valor proporcionado |
4. Casos de Búsqueda
4.1. Búsqueda por Email
La búsqueda por email filtra los pagos según la dirección de correo electrónico del pagador. Esto es útil cuando necesitas encontrar todos los pagos realizados por una persona o entidad específica.
Cómo especificar el dato:
- Campo:
payer.email - Operación:
EQUAL(igual a) - Valor: Dirección de correo electrónico del pagador.
Ejemplo de URL:
curl 'https://api.paypertic.com/pagos/?filters%5B0%5D%5Bfield%5D=request_date&filters%5B0%5D%5Bvalue%5D=20250101T000000-0300&filters%5B0%5D%5Boperation%5D=GREATER_THAN_OR_EQUAL_TO&page=1&filters%5B1%5D%5Bfield%5D=request_date&filters%5B1%5D%5Bvalue%5D=20250131T235959-0300&filters%5B1%5D%5Boperation%5D=LESS_THAN_OR_EQUAL_TO&filters%5B2%5D%5Bfield%5D=payer.email&filters%5B2%5D%5Bvalue%5D=germansl@hotmail.com&filters%5B2%5D%5Boperation%5D=EQUAL' \ -H 'accept: application/json, text/plain, */*' \ -H 'authorization: Bearer <token>' \ -H 'locale: es_AR'
4.2. Búsqueda por Número de Socio (Referencia Externa)
La búsqueda por número de socio utiliza el campo payer.external_reference. Este valor corresponde a un identificador único de cada pagador o entidad en el sistema.
Cómo especificar el dato:
- Campo:
payer.external_reference - Operación:
EQUAL(igual a) - Valor: Número de referencia del socio.
Ejemplo de URL:
curl 'https://api.paypertic.com/pagos/?filters%5B0%5D%5Bfield%5D=request_date&filters%5B0%5D%5Bvalue%5D=20250101T000000-0300&filters%5B0%5D%5Boperation%5D=GREATER_THAN_OR_EQUAL_TO&page=1&filters%5B1%5D%5Bfield%5D=request_date&filters%5B1%5D%5Bvalue%5D=20250131T235959-0300&filters%5B1%5D%5Boperation%5D=LESS_THAN_OR_EQUAL_TO&filters%5B2%5D%5Bfield%5D=collector_id&filters%5B2%5D%5Bvalue%5D=8814&filters%5B2%5D%5Boperation%5D=EQUAL&filters%5B3%5D%5Bfield%5D=payer.external_reference&filters%5B3%5D%5Bvalue%5D=14984&filters%5B3%5D%5Boperation%5D=EQUAL' \ -H 'accept: application/json, text/plain, */*' \ -H 'authorization: Bearer <token>' \ -H 'locale: es_AR'
4.3. Búsqueda por Nombre del Pagador
La búsqueda por nombre del pagador permite encontrar pagos relacionados con una persona o entidad, incluso si no tienes el nombre completo. El operador LIKE permite buscar coincidencias parciales.
Cómo especificar el dato:
- Campo:
payer.name - Operación:
EQUAL(igual a) - Valor: Nombre del pagador o parte del nombre.
Ejemplo de URL:
bashcurl 'https://api.paypertic.com/pagos/?filters%5B0%5D%5Bfield%5D=request_date&filters%5B0%5D%5Bvalue%5D=20250101T000000-0300&filters%5B0%5D%5Boperation%5D=GREATER_THAN_OR_EQUAL_TO&page=1&filters%5B1%5D%5Bfield%5D=request_date&filters%5B1%5D%5Bvalue%5D=20250131T235959-0300&filters%5B1%5D%5Boperation%5D=LESS_THAN_OR_EQUAL_TO&filters%5B2%5D%5Bfield%5D=collector_id&filters%5B2%5D%5Bvalue%5D=8814&filters%5B2%5D%5Boperation%5D=EQUAL&filters%5B3%5D%5Bfield%5D=payer.name&filters%5B3%5D%5Bvalue%5D=ruiz&filters%5B3%5D%5Boperation%5D=EQUAL' \
-H 'accept: application/json, text/plain, */*' \
-H 'authorization: Bearer <token>' \
-H 'locale: es_AR'
4.4. Búsqueda por Estado del Pago (Status)
La búsqueda por estado de pago permite filtrar los pagos según si fueron aprobados, rechazados o reinvertidos.
Cómo especificar el dato:
- Campo:
status - Operación:
EQUAL(igual a) - Valor:
- rejected: Pagos rechazados.
- refunded: Pagos reinvertidos.
- approved: Pagos aprobados.
Ejemplo de URL:
Búsqueda de Pagos Rechazados (Status: "rejected"):
bashcurl 'https://api.paypertic.com/pagos/?filters%5B0%5D%5Bfield%5D=request_date&filters%5B0%5D%5Bvalue%5D=20250101T000000-0300&filters%5B0%5D%5Boperation%5D=GREATER_THAN_OR_EQUAL_TO&page=1&filters%5B1%5D%5Bfield%5D=request_date&filters%5B1%5D%5Bvalue%5D=20250131T235959-0300&filters%5B1%5D%5Boperation%5D=LESS_THAN_OR_EQUAL_TO&filters%5B2%5D%5Bfield%5D=status&filters%5B2%5D%5Bvalue%5D=rejected&filters%5B2%5D%5Boperation%5D=EQUAL' \
-H 'accept: application/json, text/plain, */*' \
-H 'authorization: Bearer <token>' \
-H 'locale: es_AR'
Búsqueda de Pagos Reintegrados (Status: "refunded"):
bashcurl 'https://api.paypertic.com/pagos/?filters%5B0%5D%5Bfield%5D=request_date&filters%5B0%5D%5Bvalue%5D=20250101T000000-0300&filters%5B0%5D%5Boperation%5D=GREATER_THAN_OR_EQUAL_TO&page=1&filters%5B1%5D%5Bfield%5D=request_date&filters%5B1%5D%5Bvalue%5D=20250131T235959-0300&filters%5B1%5D%5Boperation%5D=LESS_THAN_OR_EQUAL_TO&filters%5B2%5D%5Bfield%5D=status&filters%5B2%5D%5Bvalue%5D=refunded&filters%5B2%5D%5Boperation%5D=EQUAL' \
-H 'accept: application/json, text/plain, */*' \
-H 'authorization: Bearer <token>' \
-H 'locale: es_AR'
Búsqueda de Pagos Aprobados (Status: "approved"):
bashcurl 'https://api.paypertic.com/pagos/?filters%5B0%5D%5Bfield%5D=request_date&filters%5B0%5D%5Bvalue%5D=20250101T000000-0300&filters%5B0%5D%5Boperation%5D=GREATER_THAN_OR_EQUAL_TO&page=1&filters%5B1%5D%5Bfield%5D=request_date&filters%5B1%5D%5Bvalue%5D=20250131T235959-0300&filters%5B1%5D%5Boperation%5D=LESS_THAN_OR_EQUAL_TO&filters%5B2%5D%5Bfield%5D=status&filters%5B2%5D%5Bvalue%5D=approved&filters%5B2%5D%5Boperation%5D=EQUAL' \
-H 'accept: application/json, text/plain, */*' \
-H 'authorization: Bearer <token>' \
-H 'locale: es_AR'
5. Respuesta de la API
La API devuelve un objeto JSON con la siguiente estructura en caso de éxito:
{ "page": 1, "limit": 10, "size": 23, "rows": [ { "id": "11111111-1111-1111-1111-111111111111", "external_transaction_id": "123456789", "collector_id": "999", "collector_detail": { "name": "PRUEBA" }, "status": "approved", "request_date": "2025-01-01T06:01:30+0000" } ] }
6. Errores Comunes
{
"code": 400,
"message": "<nombre del campo> can not be filter.",
"extended_code": 4601
}
{
"code": 400,
"message": "Invalid field \"<nombre del campo>\".",
"extended_code": 4601
}
{
"code": 400,
"message": "No enum constant com.paypertic.filter.util.enums.Operation.<OPERACIÓN>",
"extended_code": 4601
}
{
"code": 400,
"message": "<nombre_del campo> can not be filtered with <OPERACIÓN>.",
"extended_code": 4601
}