La API de Movidesk ofrece funcionalidades que permiten consultar información de la Base de Conocimientos directamente a través de peticiones HTTP. Con esta API, es posible integrar la búsqueda de artículos en su sistema, automatizando las consultas y recuperando contenidos específicos.

Administración de la API

Para utilizar la API, un Token de autenticación, que debe enviarse en todas las solicitudes a través de la cabecera. Este token se puede obtener desde el panel de control de Movidesk siguiendo los siguientes pasos:

1. Ve al menú Configuración.

2. Vá ené Cuenta > Parâmetros.

3. En la pestaña Ambiente, desplázate hasta el final de la página para encontrar el Token. Copie la clave proporcionada. 

Este token debe tratarse como una clave de seguridad, para evitar que se comparta sin autorización.

Con la clave de autenticación en la mano, elija una herramienta para probar la API. En Movidesk, recomendamos Postman, un software muy utilizado para probar y manipular APIs con facilidad.

Para realizar la prueba, siga las instrucciones:

1. Abre el Postman y crea una nueva solicitud.

2. En el campo URL, introduce el punto final de la API que quieres consultar. Por ejemplo, para listar un solo artículo, el endpoint sería https://api.movidesk.com/public/v1/article/:id

3. En la pestaña Autorización, introduzca el token de autenticación en la cabecera o como parámetro en la consulta, según sea necesario.

4. Pega la clave que has copiado antes en el campo Token.

5. Elige el método HTTP apropiado (por ejemplo, GET para consultar datos).

6. Haz clic en Enviar para enviar la solicitud à API. 

Límites y seguridad

La API tiene un límite de 10 solicitudes por minuto para garantizar un rendimiento estable. Si tu escenario requiere un volumen mayor de solicitudes, por favor contacta a nuestro equipo de soporte para un análisis de viabilidad.

La consulta de un artículo concreto puede realizarse a través de su ID. 

El punto final de esta operación es:

URL: /public/v1/article/:id
Método: GET

Propiedad	Tipo	Descripción
id	int	Identificador del artículo

Ejemplo de solicitud en Postman:

GET https://api.movidesk.com/public/v1/article/12345/kb
Autorización: SEU_TOKEN

Esta petición devolverá el artículo con el ID proporcionado, incluyendo su contenido HTML y otra información como adjuntos y categorías.

Respuesta de ejemplo

La respuesta de éxito (Estado HTTP 200) tendrá el siguiente formato:
{
.	"id": 12345,
 "articleStatus": 1,
 "contentHtml":
"Contenido del artículo</p>",
 "categories": ["Soporte", "Documentación"],
 "createdDate": "2023-01-01T12:00:00Z",
 "updatedDate": "2023-01-10T15:00:00Z"
}

• Si el token no se introduce correctamente, la API devolverá un error HTTP Estado 401.
• Si no se encuentra el ID, el retorno será HTTP Status 404.
• Si se encuentra el Id, se devolverá un Estado HTTP 200 y un Content-type en formato JSON con los diseños:

Propiedad	Tipo	Tamaño	Descripción
id	int	64	Identificador del artículo.
articleStatus	int	1	Estado del artículo: 1 - Publicado; 2 - Supendido.
attachments	array		Lista de adjuntos.
categories	array		Lista de categorías.
contentHtml	string	max	Contenido del artículo en formato HTML.
contentText	string	max	Contenido del artículo sin formato.
createdDate	datetime		Fecha de creación del artículo.
updatedDate	datetime		Fecha de actualización del artículo.
menu	object		Menú el artículo está en.
relateds	array		Lista de artículos relacionados.
revisionId	int	64	Id de la reseña del artículo publicado.
services	array		Lista de servicios vinculados al artículo.
slug	string	256	Lista de servicios vinculados al artículo.
summary	string	max	Resumen del artículo
tags	array		Lista de etiquetas de artículos
title	string	512	Título del artículo.
readingTime	time		Tiempo aproximado para leer el artículo

article.attachments[n] 

Propiedad	Tipo	Tamaño	Descripción
id	int	64	Identificador del archivo.
name	string	255	Nombre del archivo.
hash	string	32	Hash de identificación del archivo.

article.categories[n]

Propiedad	Tipo	Tamaño	Descripción
id	int	64	Identificador de la categoría
name	string	128	Nombre de la categoría.

article.menu 

Propiedad	Tipo	Tamaño	Descripción
id	int	64	Identificador del menú.
name	string	128	Nombre del menú.

article.relateds[n]

Propiedad	Tipo	Tamaño	Descripción
id	int	64	Identificador del artículo relacionado.
title	string	512	Título del artículo relacionado.
path	string	max	URL del artículo relacionado.

article.services[n]

Propiedad	Tipo	Tamaño	Descripción
id	int	64	Identificador del servicio
name	string	128	Nombre del servicio.

Ejemplo

https://api.movidesk.com/public/v1/article/1040

{
    "id": 19040,
    "articleStatus": 1,
    "attachments": [
        {
            "id": 48,
            "name": "pinboard.png",
            "hash": "358F297CE2F84F08C7B85C9EF36AFCB7"
        }
    ],
    "categories": [
        {
            "id": 6622,
            "name": "Configurações 2"
        }
    ],
    "contentHtml": "<strong>Um novo artigo<br /><br /><br /></strong>Conteudo do artigo",
    "contentText": "Um novo artigo\n\nConteudo do artigo\n",
    "createdDate": "2023-04-19T19:33:06.7051183",
    "menu": {
        "id": 6,
        "name": "Menu principal"
    },
    "updatedDate": "2023-04-19T19:33:06.7416947",
    "relateds": [
        {
            "id": 8768,
            "title": "A chave fornecida não estava presente no dicionario",
            "path": "/kb/article/8768/a-chave-fornecida-nao-estava-presente-no-dicionario-2"
        }
    ],
    "revisionId": 19126,
    "servicios": [
      {
            "id": 5711,
            "name": "SAC"
      }
    ],
    "slug": "a-new-article",
    "summary": "nuevo artículo",
    "etiquetas": [
      "file"
    ],
    "title": "Artículo",
    "readingTime": "00:00:04"
}

.

Integración con la API: Búsqueda de artículos

Busca artículos publicados y/o suspendidos en la base de datos a partir de parámetros pasados en la URL.Devuelve una versión simplificada del listado de un solo artículo.

El punto final de esta operación es:

URL:/public/v1/article/

Métodos: GET 

Propiedad	Tipo	Descripción
q	string	Valor a buscar en título, resumen o descripción.
title	string	Valor a buscar sólo en el título.
updatedDateFrom	datetime	Intervalo inicial de la última actualización.
updatedDateTo	datetime	Último intervalo de actualización.
createdDateFrom	datetime	Inicio de rango de fecha de creación.
fechaDeCreación	datetime	Fecha de fin de creación.
status	int	Estado del artículo: 1 (Publicado); 4 (Suspendido). Por defecto muestra todos los artículos publicados y suspendidos.
etiquetas	string	Nombre de la etiqueta que se va a buscar.
categoría	string	Nombre de la categoría a buscar.
menu	string	Nombre del menú a buscar.
página	int	Página actual de resultados de búsqueda. Valor por defecto: 0.
tamañoDePágina	int	Cantidad de registros por página. Valor por defecto: 30.

Ejemplo de solicitud en la Cartero

GET:https://api.movidesk.com/public/v1/article/12345/kb
Autorización: YOUR_TOKEN

Respuesta

• Si no se introduce el token en la cabecera, se devolverá un Estado HTTP 401.
• Si la solicitud tiene éxito, devuelve el estado HTTP 200.
• Siempre devuelve un JSON, con el patrón de diseño que se muestra a continuación:

Ejemplo

https://api.movidesk.com/public/v1/kb/article?q=artigo&updatedDateFrom=202 3-01-01&updatedDateTo=2023-06-01&createdDateFrom=2023-01-01&createdD ateTo=2023-06-01&status=1&pageSize=10&page=0

{
    "pageSize": 10,
    "totalSize": 2,
    "items": [
        {
            "id": 6341,
            "title": "Um novo artigo",
            "summary": "Resumo do artigo",
            "updatedAt": "2023-03-13T20:00:10.5265472Z",
            "createdAt": "2023-03-13T19:59:23.2773286Z",
            "status": 1,
            "tags": [
                "migração 01"
            ],
         

             
"menu": {
              "id": null,
              "name": null
          }
      },
        {
          "id":
6342,
            "title": "Otro artículo",
            "summary": null,
            "updatedAt": "2023-03-13T20:01:33.4411925Z",
         
  "createdAt":"2023-03-13T20:00:58.8507303Z",
            "status": 1,
            "tags": [],
         

             
  {
                  "id": 2713,
                  "name": "Categoría"
            }
          ],
         
}, "menu": {
            id: 274,
                "name": "MenuKB"
          }
     
}
    ]
}

Gestión de API

Después de configurar y probar la API, es importante seguir unas buenas prácticas de gestión:

1. Monitorización: Realiza un seguimiento del número de solicitudes realizadas y ajusta el volumen según sea necesario.

2. Seguridad: El token de autenticación debe almacenarse en un lugar seguro para evitar accesos no autorizados.

3. .Logs y Auditoría: Utilizar herramientas de monitorización para comprobar fallos y latencias en tiempo real.