A continuación se listan los requisitos técnicos necesarios para implementar una integración API Programada con YOM.
El cliente debe exponer endpoints que permitan a YOM realizar requests GET para obtener los datos. Los endpoints requeridos se listan en la siguiente sección. Debe indicar la URL Base a la cual se dirigirán las requests.
<tu_dominio><tu_dominio>/api/commercesLos endpoints deben estar protegidos mediante uno de los siguientes mecanismos de autenticación para asegurar la seguridad de los datos:
Todos los endpoints deben ser accesibles únicamente a través de HTTPS para asegurar la transmisión cifrada de los datos.
El cliente debe configurar una whitelist de IPs, permitiendo acceso solo a las IPs especificadas por YOM.
<aside> 💡 Solicitar IPs de YOM a incluir en la whitelist al momento de implementar.
</aside>
Se debe implementar paginación. Esto permite extraer grandes volúmenes de datos de manera incremental. Se necesita en todos los endpoints de extracción de datos.
page → número de páginalimit → número de resultados por página/api/commerces?page=1&limit=50En el cuerpo de la respuesta, se debe incluir el detalle de la paginación con los siguientes campos:
current_page → número de la página actual.per_page → número de resultados por página.total_pages → número total de páginas disponibles.total_items → número total de resultados disponibles.next_page → URL para la siguiente página (si aplica).prev_page → URL para la página anterior (si aplica).Ejemplo de respuesta:
{
"data": [
{
"id": "123",
"name": "Comercio A",
"category": "Retail"
},
{
"id": "124",
"name": "Comercio B",
"category": "Food"
}
// ... más resultados
],
"pagination": {
"current_page": 1,
"per_page": 50,
"total_pages": 10,
"total_items": 500,
"next_page": "/api/commerces?page=2&limit=50",
"prev_page": null
}
}
El tiempo de respuesta máximo permitido para las requests GET es de 100 segundos.
La respuesta debe estar en formato JSON. Se recomienda utilizar UTF-8 para todas las respuestas.
Los endpoints deben ser altamente disponibles y capaces de manejar el tráfico de consultas periódicas de YOM.
Los endpoints deben proporcional acceso al histórico completo de datos. Esto significa que deben estar diseñados para incluir tanto entidades activas como inactivas, permitiendo a YOM acceder a la información completa en cualquier momento, independientemente del estado actual.
Los endpoints deben soportan filtro por fecha de creación y actualización:
created_from → Fecha y hora desde la cual se quieren obtener los registros creados.created_to → Fecha y hora hasta la cual se quieren obtener los registros creados.updated_from → Fecha y hora desde la cual se quieren obtener los registros actualizados.updated_to → Fecha y hora hasta la cual se quieren obtener los registros actualizados.<aside> 💡
Estas fechas corresponden a los datos originales en la fuente de datos externa desde donde se consume la información.
</aside>
/api/transactions?**created_from**=2024-01-01T00:00:00-04:00&**updated_from**=2024-07-05T23:59:59-04:00
Su formato debe ser ISO 8601 con la posibilidad de manejar zona horaria.
Fecha → YYYY-MM-DD
Hora → hh:mm:ss
Fecha y Hora combinadas → YYYY-MM-DDThh:mm:ss
Zona Horaria
UTC → Z
UTC+ → +hh:mm
UTC- → -hh:mm
Ejemplos
Fecha sin zona horaria → YYYY-MM-DD
Fecha y hora sin zona horaria → YYYY-MM-DDThh:mm:ss
Fecha y hora en UTC → YYYY-MM-DDThh:mm:ssZ
Fecha y hora con desplazamiento positivo → YYYY-MM-DDThh:mm:ss+hh:mm
Fecha y hora con desplazamiento negativo → YYYY-MM-DDThh:mm:ss-hh:mm
Se requiere el manejo de parámetros de consulta específicos. Estos se detallan en la siguiente sección.
/api/transactions?date_from=14032024&date_to=14042024