Servicios Metadatos¶

Obtener metadatos disponible para integraciones en tickets¶

/v2/metadata/tickets/ - GET

Permite leer la configuración de metadatos que ha sido definida en su empresa para los tickets de atención.

Este webservice le permite mantener sincronizado su sistema en caso de que los administradores realicen cambios en los formularios de clasificación de tikcets.

Adicionalmente puede conocer todas las llaves de integración y valores disponibles.

Cada metadato tendrá los siguientes campos:

Campo	Descripción	Tipo
integration_key	Llave de integración definida en la interfaz	`string`
type	Tipo de campo	`string`
label	Nombre amigable que ven los ejecutivos a la hora de completar el campo	`string`
fixed	Indica si es un campo base de Desk	`boolean`
visible	Indica si el campo es visible	`boolean`
only_read	Indica si el campo es de solo lectura de cara al ejecutivo, pero modificable solo por webservices (opcional)	`boolean`
options	Lista de opciones, aplica solo a campos de tipo `checkbox`, `radiobutton`, `select`	`list`
required	Indica si el campo es requerido para guardar el formulario de cara al ejecutivo	`boolean`
required_to_close	Indica si el campo es requerido para cerrar el ticket, de cara al ejecutivo	`boolean`

En caso de existir, cada opción contendrá la siguiente información:

Campo	Descripción	Tipo
integration_key	Llave de integración definida en la interfaz para dicha opción	`string`
value	Valor que se visualiza en sistema, de cara al ejecutivo	`string`

Campos base o fixed

Un campo fixed o base son aquellos que vienen por defecto en Desk y no pueden ser eliminados. Algunos campos base de clientes son el número de teléfono, número de cliente, dirección, género, etc.

Los tipos de campos disponibles son:

Tipo
`text`, `textarea`, `checkbox`, `radiobutton`, `select`, `list`, `boolean`, `datetime`

Ejemplo de respuesta:

{
    "status": 200,
    "metadata": [
        {
            "integration_key": "COMENTARIO_USUARIO",
            "type": "text",
            "label": "Comentarios del usuario",
            "fixed": false,
            "visible": true,
            "only_read": false,
            "options": [],
            "required": false,
            "required_to_close": false
        },
        {
            "integration_key": "TIPO_PRODUCTO",
            "type": "select",
            "label": "Tipo de producto",
            "fixed": false,
            "visible": true,
            "only_read": true,
            "options": [
                {
                    "integration_key": "SKU_123",
                    "value": "Servilletas"
                },
                {
                    "integration_key": "SKU_546",
                    "value": "Pelota"
                },
                {
                    "integration_key": "SKU_985",
                    "value": "Mantel"
                },
                {
                    "integration_key": "SKU_2915",
                    "value": "Globos"
                }
            ],
            "required": false,
            "required_to_close": false
        },
        {
            "integration_key": "SUCURSAL",
            "type": "checkbox",
            "label": "Sucursales afectadas",
            "fixed": false,
            "visible": true,
            "only_read": false,
            "options": [
                {
                    "integration_key": "S_098765",
                    "value": "Sucursal Chile"
                },
                {
                    "integration_key": "S_096283",
                    "value": "Sucursal Argentina"
                }
            ],
            "required": false,
            "required_to_close": false
        },
        {
            "integration_key": "TIPO_ALIMENTACION",
            "type": "radiobutton",
            "label": "Tipo de alimentación del cliente",
            "fixed": false,
            "visible": true,
            "only_read": false,
            "options": [
                {
                    "integration_key": "MENU_09",
                    "value": "Menú Vegetariano"
                },
                {
                    "integration_key": "MENU_07",
                    "value": "Menú sin restricciones"
                }
            ],
            "required": false,
            "required_to_close": false
        }
    ]
}

Obtener metadatos disponibles para integraciones en clientes¶

/v2/metadata/clients/ - GET

Este servicio es idéntico al web service de obtener metadata disponible para integraciones en tickets salvo que retorna los metadatos disponibles para clientes.

Para mayor información por favor revisar dicha documentación acá.

Actualizar o leer metadatos de un ticket¶

/v2/metadata/ticket/{ticket_id}/ - PUT | PATCH | GET

Probar servicio

Permite actualizar la metadata del ticket y vincular información de su empresa a los tickets de atención.

El cuerpo de la petición al realizar peticiones de tipo PUT o PATCH debe ser un objeto de tipo JSON donde las llaves deben corresponder a las llaves de integración definidas por usted en Desk.

Recuerde utilizar Content-Type: application/json de lo contrario su petición será denegada.

El valor asociado a cada llave es el que se utilizará para actualizar el valor en Desk.

Definimos el tipo metadato como:

Campo	Descripción	Tipo
LLAVE_INTEGRACION	Valor asociado al metadato LLAVE_INTEGRACION, este puede ser contenido u otro nombre de llave de ingreación como se explica más adelante	`string`

El tipo metadato representa una relación de un metadato con su respectivo valor y es utilizado en la actualización y lectura de metadatos.

Actualizando metadatos, respuesta básica¶

Ejemplo de body al modificar un campo de tipo string:

1
2
3

{
    "MI_LLAVE_DE_INTEGRACION": "Valor asignado por web service"
}

Respuesta esperada:

{
    "status": 200,
    "message": "Fields updated: MI_LLAVE_DE_INTEGRACION"
}

Actualizando metadatos, múltiples campos¶

En el caso de que actualicemos más de un campo simultáneamente como en el siguiente ejemplo:

{
    "CAMPO_TIPO_STRING": "Valor asignado por webservice",
    "CAMPO_TIPO_SELECT": "S_TRES"
}

Obtendremos la siguiente respuesta:

{
    "status": 200,
    "message": "Fields updated: CAMPO_TIPO_STRING, CAMPO_TIPO_SELECT"
}

Actualizando metadatos, en el caso de campos de tipo select, radiobutton o checkbox¶

En este caso usted debe asociar el valor de la llave de integración del campo a la llave de integración de la opción que desee selecionar para dicho campo.

Como ejemplo supongamos que tenemos un campo de tipo select y los ejecutivos lo ven como Tipo de producto y tiene dos opciones: Producto A y Producto B.

Nosotros como desarrolladores, hemos definido que la llave de integración del campo Tipo de producto será TIPO_PRODUCTO y las llaves de integración de sus opciones serán P_A y P_B.

Entonces, en el escenario anterior, para actualizar estos valores debemos envíar el siguiente payload:

1
2
3

{
    "TIPO_PRODUCTO": "P_A"
}

Respuesta esperada:

{
    "status": 200,
    "message": "Fields updated: TIPO_PRODUCTO"
}

De esta manera el ejecutivo verá que en el campo Tipo de producto estará asignado el valor Producto A.

En el caso de que enviemos otro valor que no corresponde a una llave de integración de opción, entonces nuestra petición será denegada:

{
    "status": 400,
    "message": "Invalid value for key 'TIPO_PRODUCTO' of type 'select'"
}

Actualizando metadatos, metadato inexistente¶

Si quiero actualizar una llave que no existe, en este ejemplo será NO_EXISTO, utilizando este payload:

{
    "MI_LLAVE_DE_INTEGRACION": "Valor asignado por web service",
    "NO_EXISTO": "Prueba"
}

Obtendremos lo siguiente:

{
    "status": 404,
    "message": "Integration key 'NO_EXISTO' not found in ticket metadata"
}

Leyendo metadatos¶

En este caso, al realizar una petición GET a este servicio, en caso de encontrar el ticket, usted verá una respuesta como la siguiente:

{
    "status": 200,
    "ticket_id": "5b64e514ed76411a80dd3bed",
    "metadata": {
        "CAMPO_TIPO_STRING": "Esto es un texto",
        "CHECK_BOX": null,
        "RADIO_BUTTON": null,
        "CAMPO_TIPO_SELECT": "S_UNO"
    }
}

En los campos de tipo checkbox, radiobutton, select, usted verá el valor de la llave de integración definida en esta opción, como se puede ver en el campo CAMPO_TIPO_SELECT, donde el valor S_UNO, corresponde a la llave de integración de la opción seleccionada.

En caso de que la propiedad no tenga ningún valor asignado, el servicio retornará null como se observa en el ejemplo, en los campos RADIO_BUTTON y CHECK_BOX.

Una respuesta exitosa tiene la siguiente estructura:

Campo	Descripción	Tipo
status	Código de retorno de la petición. `200` si la petición fue exitosa	`integer`
ticket_id	Identificador de ticket	`string`
metadata	Lista de metadatos con sus valors	`dict metado`

Actualizar o leer metadatos de un cliente¶

/v2/metadata/client/{client_id}/ - PUT | PATCH | GET

Probar servicio

Este servicio es idéntico al web service de actualizar o leer metadata de un ticket salvo que permite actualizar o leer los metadatos específicos de un cliente particular.

Para mayor información por favor revisar dicha documentación acá.