API do Movidesk - Consulta de Artigos da base de conhecimento

A API do Movidesk oferece funcionalidades que permitem consultar informações da Base de Conhecimento diretamente via requisições HTTP. Com essa API, é possível integrar a busca de artigos ao seu sistema, automatizando consultas e recuperando conteúdos específicos.

Administração de APIs .

Para utilizar a API, é necessário um Token de Autenticação, que deve ser enviado em todas as requisições via cabeçalho. Esse token pode ser obtido no painel de controle do Movidesk, seguindo os seguintes passos:

Acesse o menu Configurações.
Vá até Conta > Parâmetros.
Na aba Ambiente, role até o final da página para encontrar o Token. Copie a chave fornecida.

Esse token deve ser tratado como uma chave de segurança, evitando compartilhamentos não autorizados.

Com a chave de autenticação em mãos, escolha uma ferramenta para testar a API. No Movidesk, recomendamos o Postman, um software amplamente utilizado para testar e manipular APIs com facilidade.

Para teste, siga as instruções:

Abra o Postman e crie uma nova requisição.
No campo da URL, insira o endpoint da API que você deseja consultar. Por exemplo, para listar um único artigo, o endpoint seria https://api.movidesk.com/public/v1/article/:id
Na aba Authorization, informe o token de autenticação no header ou como um parâmetro na query, conforme necessário.
Cole a chave que você copiou anteriormente no campo de Token.
Escolha o método HTTP adequado (por exemplo, GET para consultar dados).
Clique em Send para enviar a requisição à API.

Limites e segurança

A API possui um limite de 10 requisições por minuto para garantir um desempenho estável. Se o seu cenário exigir um volume maior de requisições, entre em contato com nosso suporte para análise de viabilidade. Saiba mais sobre horários e limites das API's

Integração com a API: Listar um único artigo

A consulta de um artigo específico pode ser realizada através do seu ID.

O endpoint para essa operação é:

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

Propriedade	Tipo	Descrição
id	int	Identificador do artigo

Exemplo de requisição no Postman:

GET https://api.movidesk.com/public/v1/article/ID_DO_ARTIGO?token={{TOKEN_DA_BASE}}

Essa requisição retornará o artigo com o ID fornecido, incluindo seu conteúdo em HTML e outras informações como anexos e categorias.

Exemplo de Resposta

A resposta de sucesso (HTTP Status 200) terá o seguinte formato:
{
     "id": 12345,
     "articleStatus": 1,
     "contentHtml": "<p>Conteúdo do artigo</p>",
     "categories": ["Suporte", "Documentação"],
     "createdDate": "2023-01-01T12:00:00Z",
     "updatedDate": "2023-01-10T15:00:00Z"
}

Se o token não for informado corretamente, a API retornará um erro HTTP Status 401.
Caso o ID não seja encontrado, o retorno será HTTP Status 404.
Caso o Id seja encontrado, será retornado um HTTP Status 200 e um Content-type no formato JSON com os layouts:

article

Propriedade	Tipo	Tamanho	Descrição
id	int	64	Identificador do artigo.
articleStatus	int	1	Status do Artigo: 1 - Publicado; 2 - Suspenso.
attachments	array		Lista de anexos.
categories	array		Lista de categorias.
contentHtml	string	max	Conteúdo do artigo em formato HTML.
contentText	string	max	Conteúdo do artigo sem formatação.
createdDate	datetime		Data de criação do artigo.
updatedDate	datetime		Data de atualização do artigo.
menu	object		Menu em que o artigo se encontra.
relateds	array		Lista de artigos relacionados.
revisionId	int	64	Id da revisão do artigo publicada.
services	array		Lista de serviços vinculados ao artigo.
slug	string	256	Lista de serviços vinculados ao artigo.
summary	string	max	Resumo do artigo
tags	array		Lista das tags do artigo
title	string	512	Titulo do artigo.
readingTime	time		Tempo aproximado de leitura do artigo.

article.attachments[n]

Propriedade	Tipo	Tamanho	Descrição
id	int	64	Identificador do arquivo.
name	string	255	Nome do arquivo.
hash	string	32	Hash de identificação do arquivo.

article.categories[n]

Propriedade	Tipo	Tamanho	Descrição
id	int	64	Identificador da categoria.
name	string	128	Nome da categoria.

article.menu

Propriedade	Tipo	Tamanho	Descrição
id	int	64	Identificador do menu.
name	string	128	Nome do menu.

article.relateds[n]

Propriedade	Tipo	Tamanho	Descrição
id	int	64	Identificador do artigo relacionado.
title	string	512	Titulo do artigo relacionado.
path	string	max	URL relativa do artigo relacionado.

article.services[n]

Propriedade	Tipo	Tamanho	Descrição
id	int	64	Identificador do serviço.
name	string	128	Nome do serviço.

Exemplo

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,
    "services": [
        {
            "id": 5711,
            "name": "SAC"
        }
    ],
    "slug": "um-novo-artigo",
    "summary": "novo artigo",
    "tags": [
        "arquivo"
    ],
    "title": "Artigo",
    "readingTime": "00:00:04"
}

Integração com a API: Pesquisa de artigos

Pesquisa por artigos publicados e/ou suspensos na base de dados a partir de parâmetros passados na URL.Retorna uma versão simplificada da listagem de um único artigo.

O endpoint para essa operação é:

URL:/public/v1/article/

Métodos: GET

Propriedade	Tipo	Descrição
q	string	Valor a ser pesquisado em titulo, resumo ou descrição.
title	string	Valor a ser pesquisado somente no titulo.
updatedDateFrom	datetime	Intervalo inicial da ultima atualização.
updatedDateTo	datetime	Intervalo final da ultima atualização.
createdDateFrom	datetime	Intervalo inicial da data de criação.
createdDateTo	datetime	Intervalo final da data de criação.
status	int	Status do artigo: 1 (Publicado); 4 (Suspenso). Por padrão traz todos os artigos publicados e suspensos.
tags	string	Nome da tag a ser pesquisado.
category	string	Nome da categoria a ser pesquisado.
menu	string	Nome do menu a ser pesquisado.
page	int	Pagina atual dos resultados de pesquisa. Valor padrão: 0.
pageSize	int	Quantidade de registros por página. Valor padrão: 30.

Exemplo de requisição no Postman

GET https://api.movidesk.com/public/v1/article/ID_DO_ARTIGO?token={{TOKEN_DA_BASE}}

Response

Caso o token não for informado no cabeçalho, será retornado um HTTP Status 401.
Caso obtenha sucesso na requisição, retorna HTTP Status 200.
Retorna sempre um JSON, com o padrão de layout abaixo:

Propriedade	Tipo	Descrição
pageSize	int	Quantidade de registros por página.
totalSize	int	Total de registros encontrados.
items	array	Caso encontrar resultados, retorna lista com uma versão simplificada do layout de article Caso contrario, retorna lista vazia
updatedDateTo	datetime	Intervalo final da ultima atualização.
createdDateFrom	datetime	Intervalo inicial da data de criação.
createdDateTo	datetime	Intervalo final da data de criação.

Exemplo

https://api.movidesk.com/public/v1/kb/article?q=artigo&updatedDateFrom=2023-01-01&updatedDateTo=2023-06-01&createdDateFrom=2023-01-01&createdDateTo=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"
            ],
            "category": [],
            "menu": {
                "id": null,
                "name": null
            }
        },
        {
            "id": 6342,
            "title": "Um outro artigo",
            "summary": null,
            "updatedAt": "2023-03-13T20:01:33.4411925Z",
            "createdAt": "2023-03-13T20:00:58.8507303Z",
            "status": 1,
            "tags": [],
            "category": [
              {
                    "id": 2713,
                    "name": "Categoria"
              }
            ],
            "menu": {
                "id": 274,
                "name": "MenuKB"
            }
        }
    ]
}

Gerenciamento de APIs

Após configurar e testar a API, é importante seguir boas práticas de gerenciamento:

Monitoramento: Acompanhe o número de requisições feitas e ajuste o volume conforme necessário.
Segurança: O Token de Autenticação deve ser armazenado em local seguro, para evitar acessos não autorizados.
Logs e Auditoria: Utilize ferramentas de monitoramento para verificar falhas e latências em tempo real.

Institucional

Conteúdo

O Software

Módulos extras

Olá, como podemos ajudar você?

Administração de APIs .

Limites e segurança

Gerenciamento de APIs