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
- 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:
Búsqueda por Email
curl --location '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%40hotmail.com&filters%5B2%5D%5Boperation%5D=EQUAL&filters%5B3%5D%5Bfield%5D=collector_id&filters%5B3%5D%5Bvalue%5D=8814&filters%5B3%5D%5Boperation%5D=EQUAL' \ --header 'accept: application/json, text/plain, */*' \ --header 'authorization: Bearer TOKEN' \ --header 'origin: https://entidad.paypertic.com' \ --header 'referer: https://entidad.paypertic.com/'
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:
Búsqueda por Número de Socio (Referencia Externa)
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:
Búsqueda por Nombre del Pagador
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.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 reintegrado.
Cómo especificar el dato:
- Campo:
status - Operación:
EQUAL(igual a) - Valor:
- rejected: Pagos rechazados.
- refunded: Pagos reintegrado.
- approved: Pagos aprobados.
Ejemplo de URL:
Búsqueda de Pagos Rechazados (Status: "rejected"):
Búsqueda de Pagos Rechazados (Status: "rejected")
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=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"):
Búsqueda de Pagos Reintegrados (Status: "refunded")
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=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"):
Búsqueda de Pagos Aprobados (Status: "approved")
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=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:
Respuesta
{ "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
Este error indica que el campo no está dispobible para ser filtrado
{
"code": 400,
"message": "<nombre del campo> can not be filter.",
"extended_code": 4601
}
Este error indica que el campo no pertenece al modelo de la entidad a ser filtrada
{
"code": 400,
"message": "Invalid field \"<nombre del campo>\".",
"extended_code": 4601
}
Este error indica que la operación proporcionada es inexistente
{
"code": 400,
"message": "No enum constant com.paypertic.filter.util.enums.Operation.<OPERACIÓN>",
"extended_code": 4601
}
Este error indica que la operación no se encuentra disponible para el campo
{
"code": 400,
"message": "<nombre_del campo> can not be filtered with <OPERACIÓN>.",
"extended_code": 4601
}