Requisitos técnicos

La integración Webhooks permite a YOM enviar notificaciones automáticas a los sistemas de nuestros clientes en tiempo real. Para implementar esta integración, es necesario cumplir con los siguientes requisitos técnicos:

🌐 Endpoint de Recepción del Webhook

El cliente debe proporcionar una URL que actuará como el endpoint de recepción del webhook. Este endpoint debe ser capaz de recibir solicitudes HTTP POST desde YOM.

URL de Recepción: <tu_dominio>/webhooks/yom
Ejemplo de uso: POST <tu_dominio>/webhooks/yom

🔒 Autenticación y Seguridad hacia YOM

Para acceder a los endpoints de YOM, es necesario crear un token en base a un client_id y client_secret que serán entregados a nuestros clientes.

Los detalles del endpoint para generar el token es la siguiente:

URL
- Staging
  - https://api.solopide.me/api/v2/auth/tokens/grant
- Producción
  - https://api.youorder.me/api/v2/auth/tokens/grant
Método
- POST
Encabezados (Headers):
- Content-Type: application/json

Cuerpo de la Solicitud (Request Body):

Se envía en formato JSON. Ejemplo:

{
    "client_id": "nkguw0p01dafkQoRPTXO6",
    "client_secret": "IeC2SSfZEdFb8hASD#faskSADT83Y0tGN2CJmZWHY",
    "grant_type": "client_credentials"
}

Ejemplo de la respuesta:

{
	"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2NzJlMDUwYTBiMzFlY2UyYzhlMzkxOGYiLCJyb2xlcyI6WyJhZG1pbiJdLCJkb21haW4iOiJpMmJ0ZXN0LnNvbG9waWRlLm1lIiwiY3VzdG9tZXJJZCI6IjY3MmUwNTA3MGIzMWVjZTJjOGUzOTE3YiIsInBlcm1pc3Npb25zIjpbImNhdGVnb3J5OnJlYWQiLCJjYXRlZ29yeTpidWxrIiwiY29tbWVyY2U6d3JpdGUiLCJjdXN0b21lcjpyZWFkIiwiZGlzY291bnQtbGltaXRzOnJlYWQiLCJkaXNjb3VudC1saW1pdHM6d3JpdGUiLCJkaXNjb3VudC1saW1pdHM6YnVsayIsImRpc2NvdW50LWxpbWl0czpkZXN0cm95IiwiZG9tYWluOnJlYWQiLCJkb21haW46YnVsayIsImdyb3VwOnJlYWQiLCJncm91cDp3cml0ZSIsImdyb3VwOmRlc3Ryb3kiLCJncm91cDpidWxrIiwiaW1wb3J0OndyaXRlIiwiaW50ZWdyYXRpb24taW5mbzpyZWFkIiwiaW50ZWdyYXRpb24taW5mbzp3cml0ZSIsIm9yZGVyOnJTpyZWFkIiwib3ZlcnJpZGU6d3JpdGUiLCJvdmVycmlkZTpidWxrIiwicGF5bWVudDpyZWFkIiwicGVuZGluZy1kb2N1bWVudDpidWxrIiwicHJvbW90aW9uOnJlYWQiLCJwcm9tb3Rpb246d3JpdGUiLCJwcm9tb3Rpb246YnVsayIsInNhbGVzbWFuOnJlYWQiLCJzYWxlc21hbjp3cml0ZSIsInNhbGVzbWFuOmJ1bGsiLCJzZWdtZW50OnJlYWQiLCJzZWdtZW50OndyaXRlIiwic2VnbWVudDpidWxrIiwic2VnbWVudDpidWxrLWRlc3Ryb3kiLCJzZWxsZXI6cmVhZCIsInNlbGxlcjpidWxrIiwic2t1OnJlYWQiLCJza3U6YnVsayIsInN1cGVydmlzb3I6YnVsayIsInN0b3JlOnJlYWQiLCJzdWdnZXN0aW9uOnJlYWQiLCJzdWdnZXN0aW9uOmJ1bGsiLCJ1cGxvYWRlcjpyZWFkIiwidXBsb2FkZXI6d3JpdGUiXSwidmVyaWZpZWQiOnRydWUsImJsb2NrZWQiOmZhbHNlLCJ0eXBlIjoiYXBwbGljYXRpb24iLCJjb25uZWN0aW9uSWQiOiI2N2M3MWZhNmU1NzcyMmY2NGU3NjdiZDYiLCJpYXQiOjE3NDExMTI4NjksImV4cCI6MTc0MTExMzc2OX0.lTklbBucJ6o-CFAdSGeO5rfJM-VUmw_xEbQVdoIaUKE",
	"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2NzJlMDUwYTBiMzFlY2UyYzhlMzkxOGYiLCJyb2xlcyI6WyJhZG1pbiJdLCJkb21haW4iOiJpMmJ0ZXN0LnNvbG9waWRlLm1lIiwiY3VzdG9tZXJJZCI6IjY3MmUwNTA3MGIzMWVjZTJjOGUzOTE3YiIsInBlcm1pc3Npb25zIjpbImNhdGVnb3J5OnJlYWQiLCJjYXRlZ29yeTpidWxrIiwiY29tbWVyY2U6d3JpdGUiLCJjdXN0b21lcjpyZWFkIiwiZGlzY291bnQtbGltaXRzOnJlYWQiLCJkaXNjb3VudC1saW1pdHM6d3JpdGUiLCJkaXNjb3VudC1saW1pdHM6YnVsayIsImRpc2NvdW50LWxpbWl0czpkZXN0cm95IiwiZG9tYWluOnJlYWQiLCJkb21haW46YnVsayIsImdyb3VwOnJlYWQiLCJncm91cDp3cml0ZSIsImdyb3VwOmRlc3Ryb3kiLCJncm91cDpidWxrIiwiaW1wb3J0OndyaXRlIiwiaW50ZWdyYXRpb24taW5mbzpyZWFkIiwiaW50ZWdyYXRpb24taW5mbzp3cml0ZSIsIm9yZGVyOnJTpyZWFkIiwib3ZlcnJpZGU6d3JpdGUiLCJvdmVycmlkZTpidWxrIiwicGF5bWVudDpyZWFkIiwicGVuZGluZy1kb2N1bWVudDpidWxrIiwicHJvbW90aW9uOnJlYWQiLCJwcm9tb3Rpb246d3JpdGUiLCJwcm9tb3Rpb246YnVsayIsInNhbGVzbWFuOnJlYWQiLCJzYWxlc21hbjp3cml0ZSIsInNhbGVzbWFuOmJ1bGsiLCJzZWdtZW50OnJlYWQiLCJzZWdtZW50OndyaXRlIiwic2VnbWVudDpidWxrIiwic2VnbWVudDpidWxrLWRlc3Ryb3kiLCJzZWxsZXI6cmVhZCIsInNlbGxlcjpidWxrIiwic2t1OnJlYWQiLCJza3U6YnVsayIsInN1cGVydmlzb3I6YnVsayIsInN0b3JlOnJlYWQiLCJzdWdnZXN0aW9uOnJlYWQiLCJzdWdnZXN0aW9uOmJ1bGsiLCJ1cGxvYWRlcjpyZWFkIiwidXBsb2FkZXI6d3JpdGUiXSwidmVyaWZpZWQiOnRydWUsImJsb2NrZWQiOmZhbHNlLCJ0eXBlIjoiYXBwbGljYXRpb24iLCJjb25uZWN0aW9uSWQiOiI2N2M3MWZhNmU1NzcyMmY2NGU3NjdiZDYiLCJpYXQiOjE3NDExMTI4NjksImV4cCI6MTc0MTExMzc2OX0.lTklbBucJ6o-CFAdSGeO5rfJM-VUmw_xEbQVdoIaUKE",
	"token_type": "bearer",
	"expires_in": 900
}

🔒 Autenticación y Seguridad API Cliente

Los endpoints deben estar protegidos mediante uno de los siguientes mecanismos de autenticación para asegurar la seguridad de los datos:

API Token 🔑

📋 Formato de Datos

Las solicitudes de Webhook enviadas por YOM estarán en formato JSON. Se recomienda utilizar UTF-8 para todas las respuestas.

Ejemplo de payload:

{
    "event": "order.created",
    "eventId": "6lpld904lsxcmfjdkeur43vx"
    "data": {
        "internalOrderId": "12345",
        "status": "created"
        ...
    }
}

#️⃣ Manejo de IDs

El cliente debe registrar y manejar los IDs asignados por YOM ante eventos de creación de entidades. Esto garantiza que cada entidad sea única e identificable a lo largo de su ciclo de vida.

Para diferenciar los IDs asignados por Yom, estos incluyen el prefijo internal. Para el ejemplo de eventos relacionados a Ordenes:

internalOrderId → ID de la Order asignado por Yom

orderId → ID de la Orden asignado por el cliente

📥 Formato de Respuesta

El cliente debe responder a los POST exitosos con un JSON que incluya el ID externo asignado al objeto en sus sistemas, especialmente para los endpoints de creación. Esto asegura que YOM tenga un registro del ID en el sistema del cliente para futuras actualizaciones.

Para el ejemplo de eventos relacionados a Ordenes:

{
    "status": "awaiting_approval",
    "orderId": "12345",
    "internalOrderId": "98765",
    ...
}

🕒 Tiempo de Respuesta

El endpoint del cliente debe responder a las solicitudes de Webhook dentro de un tiempo máximo de 5 segundos para confirmar la recepción exitosa.

🔄 Reintentos y Gestión de Errores

En caso de que la entrega del Webhook falle (por ejemplo, debido a un error de red o un tiempo de espera agotado), YOM intentará reenviar la solicitud varias veces.

Estrategia de Reintentos: YOM reintentará la entrega del webhook hasta 3 veces con un intervalo exponencial entre cada intento.
Respuesta Exitosa: El endpoint del cliente debe responder con un código de estado 2xx para confirmar la recepción exitosa.
Respuesta Fallida: Si después de varios intentos la entrega falla, YOM registrará el error y notificará al cliente.

🆙 Disponibilidad y Fiabilidad

El endpoint de recepción del Webhook debe ser altamente disponible y capaz de manejar el tráfico de notificaciones en tiempo real de YOM.

Pasos anteriores

<aside> <img src="/icons/arrow-left_gray.svg" alt="/icons/arrow-left_gray.svg" width="40px" /> Webhooks

</aside>

Siguientes pasos

<aside> <img src="/icons/arrow-right_gray.svg" alt="/icons/arrow-right_gray.svg" width="40px" /> Eventos disponibles de YOM a clientes

</aside>

Tabla de contenidos