API integration

The Scheduled API integration lets YOM automatically retrieve up-to-date data from our customers' systems. This option suits companies that have the technical capacity to expose their data through endpoints.

📤 What does it involve?

The Scheduled API integration means YOM sends periodic requests to the endpoints the customer provides in order to retrieve the data it needs. This method keeps the data in our systems always up to date, reflecting changes made in the customer's systems.

⚙️ Technical requirements

The technical requirements for implementing a Scheduled API integration with YOM are listed below.

🌐 Endpoints REST API

The customer must expose endpoints that let YOM make GET requests to retrieve the data. The required endpoints are listed in the Endpoints to make available section. You must specify the Base URL that the requests will be sent to.

Base URL: <tu_dominio>
Example: GET <tu_dominio>/api/commerces

🔒 Authentication

The endpoints must be protected by one of the following authentication mechanisms to keep the data secure:

API Token 🔑

Username and Password 👤

🦺 Security

All endpoints must be accessible only over HTTPS to ensure encrypted data transmission.

The customer must configure an IP whitelist, allowing access only to the IPs specified by YOM.

<aside> 💡

Request YOM's IPs to add to the whitelist at implementation time.

</aside>

📄 Pagination

Pagination must be implemented. This makes it possible to extract large volumes of data incrementally. It is required on all data extraction endpoints.

Required pagination parameters:
Example: /api/commerces?page=1&limit=50

The response body must include the pagination details with the following fields:

current_page → current page number.
per_page → results per page.
total_pages → total number of pages available.
total_items → total number of results available.
next_page → URL for the next page (if applicable).
prev_page → URL for the previous page (if applicable).

Example response:

{
    "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
    }
}

⏱️ Response time

The maximum allowed response time for GET requests is 100 seconds.

📋 Data format

The response must be in JSON format. We recommend using UTF-8 for all responses.

🆙 Availability and reliability

The endpoints must be highly available and able to handle the traffic from YOM's periodic queries.

🟢 Data completeness

The endpoints must provide access to the complete data history. This means they must be designed to include both active and inactive entities, letting YOM access the full information at any time, regardless of current status.