Referencia API MSV Service

Bienvenido a la referencia técnica de MSV Service. Nuestra API está construida bajo principios RESTful, utiliza JSON para el intercambio de datos y códigos de respuesta HTTP estándar.

¿Qué es MSV Service?

MSV Service (Multi Step Validator) es un servicio que envía mensajes a un usuario final por WhatsApp, SMS o correo electrónico, en dos modalidades:

• Notificación: entrega un mensaje informativo. Termina ahí: no genera token, no se puede consultar y no notifica nada de vuelta.
• Validación: entrega un mensaje con un enlace para que el usuario apruebe o rechace. El servicio te avisa la respuesta por webhook y puedes consultarla cuando quieras.

Entornos y base URL

Todas las solicitudes deben enviarse a las siguientes URL base, dependiendo del entorno en el que te encuentres:

Ciclo de vida de una validación

1. Creas la solicitud con POST /api/validations. El servicio envía el mensaje por los canales que indicaste. Si al menos un canal lo entrega, responde 201 con un token y la validación queda en PENDING. Si ningún canal lo entrega, responde 400 y la validación queda en FAILED.
2. El mensaje lleva al usuario a una página de confirmación alojada por msv-service, donde aprueba o rechaza. En SMS y correo el enlace se agrega automáticamente; en WhatsApp solo aparece si incluyes [URL_VALIDATION] entre los parámetros de la plantilla.
3. En cuanto responde, la solicitud pasa a APPROVED o REJECTED y se envía el webhook.
4. Si no responde dentro de minutes_by_expire (30 minutos por defecto, máximo 60), la solicitud pasa a PARTIAL_EXPIRED y también se envía el webhook.

Flujo visual

Puedes consultar el estado en cualquier momento con Consulta validación.

Resultado por canal

Las respuestas de POST /api/validations y POST /api/notifications incluyen un arreglo channels con el resultado de cada canal, en el mismo orden en que los indicaste. Un canal puede fallar aunque otro haya entregado el mensaje; en ese caso la respuesta sigue siendo exitosa.

Si el locale que envías no es soportado, se usa el idioma por defecto del servicio (en).

Motivos de falla

Webhook

Cuando el usuario responde la validación o cuando la validación expira sin respuesta, msv-service envía de forma asíncrona un POST a la url que configuraste en el campo webhook_url. Este payload NO es la respuesta síncrona del endpoint /api/validations. Llega despues, y es una notificación que tu servidor debe recibir y procesar.

Estructura del payload

{
  "status": {
    "status": "APPROVED",
    "reason": null,
    "message": "El usuario ha respondido",
    "date": "2022-08-08T17:23:49+00:00"
  },
  "token": "d5d67dcb",
  "reference": "0122333444455555",
  "kind": "horus",
  "signature": "c1c0a085837b4042ab6cce604d5a51e665aa038c2eab58a6212037b459612ca1"
}

Validación de la firma

Antes de procesar el webhook, recalcula el hash SHA-256 y compáralo con el valor recibido en el campo signature. Si la firma calculada coincide con la firma proporcionada, se valida la autenticidad de la respuesta y se procede a persistir el registro en la base de datos:

$calculated = hash('sha256', $token . $status . $date . $secret_token);
// Ejemplo: hash('sha256', 'd5d67dcbAPPROVED2022-08-08T17:23:49+00:00ABCD1234')

if (!hash_equals($calculated, $signature)) {
    // Rechazar — no auténtico
    http_response_code(400);
    exit;
}

// Procesar el webhook
http_response_code(200);

Códigos de respuesta

Servicios disponibles

Explora los endpoints disponibles:

• Login: Permite obtener un token para realizar peticiones a la API.
• Validación: Crea una solicitud de validación (respuesta síncrona: HTTP 201 o 400).
• Consulta validación: Consulta el estado actual de una validación previamente creada.
• Notificación: Crea una solicitud de notificación.