1️⃣ ¿Qué aprenderás en esta guía?
Conocerás los requisitos que debe cumplir un endpoint para conectarse correctamente con un flujo de Mercately mediante el paso Conectar API.
2️⃣ Requisitos del endpoint
✔️ Debe aceptar solicitudes POST.
✔️ Recibir la información en formato x-www-form-urlencoded.
✔️ Responder con una estructura JSON válida.
✔️ Debe devolver un código HTTP 200 (OK) cuando la solicitud sea exitosa.
✔️ Debe responder en menos de 10 segundos para evitar tiempos de espera.
3️⃣ ¿Cómo debe responder el endpoint?
El endpoint debe devolver una estructura JSON válida.
Mensaje simple
Si únicamente deseas responder con un mensaje al cliente, el endpoint debe retornar:
{ "message": "ID: 12345\nNombres: PEDRO PÉREZ\nEstado: ACTIVO\nDeuda: $30\nVencimiento: 25-11-2020"
}Campo requerido
Parámetro | Obligatorio | Descripción |
message | ✅ Sí | Texto que el bot mostrará al cliente. |
Respuesta con opciones dinámicas
Si deseas que el bot genere opciones para que el cliente seleccione una alternativa, el endpoint debe responder con la siguiente estructura:
{ "message": "Selecciona tu sucursal:",
"option_name": "Sucursales disponibles",
"options": [
{
"key": "SCQ01", "value": "Sucursal Quito - Centro"
},
{ "key": "SCG02", "value": "Sucursal Guayaquil - Mall del Sol"
}
]
}Campos disponibles
Parámetro | Obligatorio | Descripción |
message | ✅ Sí | Mensaje que verá el cliente. |
option_name | Opcional | Nombre del grupo de opciones. |
options | Opcional | Lista de opciones dinámicas que podrá seleccionar el cliente. |
Cada elemento de options debe contener:
key: identificador interno de la opción.
value: texto que visualizará el cliente.
4️⃣ Códigos de respuesta HTTP
El endpoint debe responder con los códigos HTTP adecuados para que Mercately pueda interpretar el resultado de la solicitud.
Código | Resultado |
200 (OK) | ✅ La solicitud fue exitosa y el flujo continuará normalmente. |
400, 401, 403, 404, 500 u otros | ❌ La solicitud será considerada como un error y el flujo actuará según la configuración establecida. |
⚠️ Recomendaciones
Utiliza autenticación mediante Headers (por ejemplo, tokens o API Keys) cuando tu endpoint lo requiera.
Verifica el funcionamiento del endpoint utilizando herramientas como Postman antes de conectarlo con Mercately.
Asegúrate de que el JSON devuelto tenga una estructura válida.
Procura que el tiempo de respuesta del endpoint sea inferior a 10 segundos para evitar errores por timeout.
🤝 ¿Necesitas ayuda?
💬 Chat en vivo: disponible dentro de tu plataforma Mercately.
📧 Correo: [email protected]
Nuestro equipo estará encantado de ayudarte. 😊