Formularios

Te explicamos como utilizar os formularios mediante Rest API.

Con nuestra Rest API de formularios podrás obtener los formularios diseñados en tu cuenta.

Los endpoints a continuación son públicos, es decir, se antepone /public/ como medio diferenciador de endpoints privados.

Para renderizar los formularios te sugerimos utilizar nuestro SDK de formulario.

Formato

Nuestros formularios están cuidadosamente diseñados para presentar un formato amigable y flexible al mismo tiempo.

Todos los formularios que se envíen deben tener el siguiente esquema:

[
    { "_id": String, "value": String || Array || Number }
]

Dentro de este Array debes añadir el listado de campos con su _id y value, siendo este último capaz de recibir tres tipos de datos: String, Number y Array.

El ID debe coincidir con los valores que se entregan al obtener un formulario, es decir, con el campo _id.

Debes considerar que los valores deben coincidir con los configurados en tu cuenta, sobre todo para los casos de selección única o múltiple.

Contamos con 3 niveles de validación:

1. Tipo de dato corresponde con el tipo de campo

2. Validación del valor por campo (built-in y/o personalizado)

3. Verificación de restricciones (máximo, mínimo, longitud, etc)

📄pageFormularios

Obtener formulario de un segmento

GET https://api.videsk.io/public/video-contact-center/forms/:segmentId

Podrás obtener el formulario de un segmento mediante su ID

Path Parameters

Name	Type	Description
segmentId*	String	ID del segmento

Query Parameters

Name	Type	Description
version*	String	Tipo de formulario "base" o "contact"

Headers

Name	Type	Description
Authorization*	String	Bearer {token}
Content-Type*	String	application/json

200: OK Formulario

{
   "form":[
      {
         "_id":"60f652f1cfa34fc3157ef5c6",
         "type":"text",
         "name":"firstname",
         "label":"Nombre",
         "properties":{
            "required":true,
            "placeholder":"Ingrese su nombre..."
         },
         "options":[],
         "hint":""
      },
      {
         "_id":"61d25bc9294d18677ce6ef6f",
         "type":"text",
         "label":"Apellido",
         "properties":{
            "placeholder":"Ingrese su apellido",
            "maxlength":"50"
         },
         "name":"lastname",
         "hint":"",
         "options":[]
      },
      {
         "_id":"60f652f1cfa34fc3157ef5c7",
         "type":"email",
         "name":"email",
         "label":"Correo electrónico",
         "properties":{
            "required":true,
            "placeholder":"Ingrese su email..."
         },
         "options":[],
         "hint":""
      },
      {
         "_id":"60f654b4cfa34fc3157ef5cc",
         "type":"text",
         "label":"Nombre de la empresa",
         "properties":{
            "placeholder":"Ingrese nombre de la empresa...",
            "maxlength":"50",
            "required":true
         },
         "name":"company",
         "hint":"",
         "options":[]
      },
      {
         "_id":"60f654b4cfa34fc3157ef5cd",
         "type":"url",
         "label":"Sitio web",
         "properties":{
            "placeholder":"Ingrese un enlace con http://",
            "required":true
         },
         "name":"website",
         "hint":"Debe anteponer http:// o https://",
         "options":[
            
         ]
      },
      {
         "_id":"61d25bc9294d18677ce6ef73",
         "type":"text",
         "label":"Industria",
         "properties":{
            "placeholder":"Ingrese la industria del negocio",
            "maxlength":"100"
         },
         "name":"industry",
         "hint":"",
         "options":[]
      },
      {
         "_id":"60f654b4cfa34fc3157ef5ce",
         "type":"textarea",
         "label":"Mensaje",
         "properties":{
            "placeholder":"Déjanos tu mensaje y te contactaremos.",
            "maxlength":"250"
         },
         "name":"message",
         "hint":"",
         "options":[]
      }
   ],
   "siteKey":"XXXXXXXXXXXXXXX",
   "resource":"https://challenges.cloudflare.com/turnstile/v0/api.js",
   "provider":"turnstile"
}

400: Bad Request Error de entidad

{
    "name": "NotFound",
    "message": "The XXXX version of form not found.",
    "code": 404,
    "className": "not-found",
    "errors": {}
}

400: Bad Request Formulario no encontrado

{
    "name": "NotFound",
    "message": "Not form found in segment provided.",
    "code": 404,
    "className": "not-found",
    "errors": {}
}

Considera que es posible que tu cuenta no tengas configurado un formulario base o de contacto.

401: Unauthorized API Key inválido

Referencia de errores en autorización.

Enviar encuesta

POST https://api.videsk.io/public/video-contact-center/forms

Podrás enviar un formulario el cuál se podrá adjuntar a una llamada o no.

Headers

Name	Type	Description
Authorization*	String	Bearer {token}
Content-Type*	String	application/json

Request Body

Name	Type	Description
segment*	String	ID del segmento
type*	String	Tipo de formulario "contact" o "pre-call"
values*	Array	Listado de campos
values._id*	String	ID del campo
values.value*	String	Valor del campo
token	String	Token captcha (no backend)

201: Created Encuesta recibida

{
   "message":"The form was saved successfully.",
   "success":true,
   "submission":"64a35822da9f12295c1d98dc"
}

400: Bad Request Captcha Inválido (no backend)

{
    "name": "Unprocessable",
    "message": "Your submit looks suspicious, not pass the captcha validation.",
    "code": 422,
    "className": "unprocessable",
    "data": {
        "extraData": "invalid-input-response"
    },
    "errors": {}
}

400: Bad Request Error en los campos enviados

{
  "name": "BadRequest",
  "message": "Some element not as field, please check or try again",
  "code": 400,
  "className": "bad-request",
  "data": "Maybe the organization has changed the form and you're submit is not valid anymore.",
  "errors": {}
}

400: Bad Request Campo inválido

{
  "name": "BadRequest",
  "message": "The maximum of value is 10 for element \"62703d9d3cf0565020ec9e3c\".",
  "code": 400,
  "className": "bad-request",
  "errors": {}
}

400: Bad Request Campo requerido

Este es un campo vació requerido que funciona como honeypot a bots.

{
  "name": "BadRequest",
  "message": "The element form \"videsk_essential\" is required, never delete.",
  "code": 400,
  "className": "bad-request",
  "errors": {}
}

401: Unauthorized API Key inválido

Referencia de errores en autorización.

400: Bad Request Captcha token requerido

{
    "name": "BadRequest",
    "message": "Please provide a valid \"token\", is mandatory.",
    "code": 400,
    "className": "bad-request",
    "errors": {}
}

400: Bad Request ID segmento inválido

{
    "name": "BadRequest",
    "message": "Please check the segment id provided.",
    "code": 400,
    "className": "bad-request",
    "errors": {}
}

400: Bad Request Tipo formulario inválido

{
    "name": "BadRequest",
    "message": "Provide a valid \"type\" form submission.",
    "code": 400,
    "className": "bad-request",
    "errors": {}
}

400: Bad Request No hay formulario configurado

{
    "name": "NotFound",
    "message": "Not form found in segment provided.",
    "code": 404,
    "className": "not-found",
    "errors": {}
}