POST/api/validations

Validación

Crea una solicitud de validación: msv-service envía al usuario un mensaje por los canales que indiques, con un enlace para aprobar o rechazar.

La respuesta 201 confirma únicamente que la solicitud se creó y los mensajes se enviaron; el estado siempre es PENDING. La respuesta del usuario llega después por webhook, o puedes consultarla con el token en Consulta validación.

Solicitud

  • Name
    locale
    Type
    string
    is optional
    Description

    Define el idioma a usar en formato ISO 639-1

    Valores permitidos:esenptit
    Ejemplo:es
    Longitud máxima:2
    Longitud mínima:2
  • Name
    reference
    Type
    string
    is Required
    REQUERIDO
    Description

    identificador del item a validar

    Ejemplo:ref-12548
    Longitud máxima:50
  • Name
    message
    Type
    string
    is Required
    REQUERIDO
    Description

    Mensaje que se visualizará en el correo electrónico y en vista de aprobación.

  • Name
    kind
    Type
    string
    is optional
    Description

    Campo para clasificar una solicitud

    Ejemplo:Horus
    Longitud máxima:50
  • Name
    webhook_url
    Type
    string
    is Required
    REQUERIDO
    Description

    URL de tu servidor a la que msv-service enviará por POST el resultado, cuando el usuario responda o cuando la solicitud expire.

    Ejemplo:https://example-url.com/
    Longitud máxima:255
  • Name
    minutes_by_expire
    Type
    integer
    is optional
    Description

    Minutos que el usuario tiene para responder. Al vencerse, la solicitud pasa a PARTIAL_EXPIRED y se envía el webhook con ese estado (mínimo 1, máximo 60).

    Valor por defecto:30
    Ejemplo:20
  • Name
    buttons
    Type
    object
    is optional
    Description

    Estructura que indica el mensaje de las opciones de aprobación o rechazo

  • Name
    channels
    Type
    object
    is Required
    REQUERIDO
    Description

    Estructura requerida para definir el detalle del canal a utilizar

Solicitud

POST
/api/validations
curl -X "POST" {{baseURl}}/api/validations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "locale": "es",
    "reference": "ref-12548",
    "message": "Example Validation",
    "kind": "Horus",
    "webhook_url": "https://example-url.com/",
    "minutes_by_expire": 10,
    "buttons": {
      "approve": "aceptar",
      "reject": "rechazar"
    },
    "channels": {
      "sms": {
        "phone_number": "+573124567890",
        "short_message": "SMS Message"
      },
      "whatsapp": {
        "phone_number": "+573124567890",
        "template": {
          "name": "hello_world",
          "lang": "en_US",
          "parameters": [
            "name"
          ]
        }
      },
      "email": {
        "email": "[email protected]",
        "subject": "email subject"
      }
    }
  }'

Respuesta

La solicitud de validación se creó y los mensajes se enviaron.

  • Name
    status
    Type
    object
    is optional
    Description
  • Name
    reference
    Type
    string
    is optional
    Description

    identificador del item a validar

    Ejemplo:0122333444455555
  • Name
    token
    Type
    string
    is optional
    Description

    identificador de la solicitud (8 caracteres hexadecimales)

    Ejemplo:d5d67dcb
  • Name
    kind
    Type
    string
    is optional
    Description

    Clasificación de la solicitud

    Ejemplo:horus

Respuesta

{
  "status": {
    "status": "PENDING",
    "reason": null,
    "message": "Transacción pendiente de aprobación",
    "date": "2022-07-08T09:34:48-05:00"
  },
  "reference": "ref-12548",
  "token": "d5d67dcb",
  "kind": "Horus"
}

Importante: una respuesta 400 en /api/validations no revierte la solicitud ya creada. Los canales que alcanzaron a enviarse permanecen activos y el usuario podría aprobar o rechazar la solicitud.