Nessa seção descreveremos o que será necessário para utilizar a nossa API.
Orientações Gerais
Temos rotas de API para consulta, inclusão, alteração e exclusão de dados. As rotas disponibilizadas estão divididas em três módulos:
• Processos: Instâncias, Definições e Categorias;
• Documentos: Arquivos e Templates;
• Admin: Usuários, Grupos, Departamentos e Funções.
A utilização de cada rota que disponibilizamos, sempre serão necessárias duas informações fundamentais para que elas sejam executadas, que são: apikey e X_Server.
Além disso, o padrão utilizado é API RESTful.
Pré-Requisitos
Para o desenvolvimento e a utilização das API's serão necessários:
- Plataforma atualizada
A versão mínima que possui recurso de API é a 5.50 RTM 1.06. Entretanto, recomendamos que seja utilizada a versão mais recente para poder usufruir de todos os recursos.
- Endereço (URL) para chamada dos serviços da API
A URL para todas as chamadas dos serviços é: https://api.lecom.com.br. Para identificar essa informação, clique aqui.
- Identificador do ambiente (X-Server)
Em todas as chamadas de API, é necessário passar um parâmetro no cabeçalho da chamada que identifica o ambiente do cliente. Esse parâmetro é o X-Server. Para identificar essa informação, clique aqui.
- Chave de segurança (apikey)
Para o consumo de qualquer API, é necessário passar uma chave de segurança que é denominada apikey. Essa chave é vinculada a um usuário da Plataforma. Para identificar essa informação, clique aqui.
Métodos HTTP para serviços RESTful
No padrão API RESTful, o protocolo HTTP define um conjunto de métodos de requisição responsáveis por indicar a ação a ser executada para um dado recurso. Esses métodos são conhecidos como verbos HTTP.
Segue abaixo a relação desses métodos e as suas respectivas ações:
| Método | Descrição |
|---|---|
| GET | Obter dados. |
| POST | Criar recursos. |
| PUT | Atualizar recursos. |
| DELETE | Remover recursos. |
| PATCH | Atualizar parcialmente os recursos. |
Embora esses métodos executem as ações descritas no geral, algumas rotas podem utilizá-los com outra finalidade. Por exemplo, na rota de consulta de processos, que pode ter uma quantidade significativa de parâmetros, o método GET não suporta esse volume. Por isso é utilizado o método POST.
Respostas da API (Status Code)
Os códigos de Status da resposta HTTP indicam se uma requisição foi concluída com sucesso ou não. No geral, os códigos de Status no intervalo 2xx indica sucesso. Já o intervalo 4xx indica que houve erro nas informações fornecidas, enquanto que o intervalo 5xx indica erro no lado do servidor.
| Códigos de Status | Descrição |
|---|---|
| 200 | Sucesso. |
| 204 | Sucesso e sem retorno de conteúdo. |
| 400 | Requisição não processada. |
| 401 | Não autenticado. |
| 403 | Usuário sem permissão no recurso. |
| 404 | Recurso não localizado. |
| 500 | Erro interno ao processar requisição. |
| 502 | Erro de direcionamento de requisição entre servidores. Geralmente pode ocorrer devido ao servidor intermediário (Gateway) não conseguir direcionar a requisição ao servidor destino. |
Orientação sobre a documentação
Organizamos a documentação das rotas de API em duas partes, uma que descreve a visão de negócio e a outra que é a descrição técnica, também conhecida como "API Reference".
Recomendamos que a leitura seja sempre iniciada pela visão de negócio, pois nela terá orientação para que serve a rota de API, com alguns exemplos de utilização e o "link" de acesso para à documentação técnica.