A documentação de APIs do Sienge Plataforma é um conteúdo técnico destinado principalmente à desenvolvedores, mas é possível de ser compreendida por usuários não técnicos seguindo os passos deste documento, que visa esclarecer os principais termos técnicos contidos na documentação.
A documentação de APIs é bem dinâmica e pode sofrer atualizações diárias, você pode acessar por este link: https://api.sienge.com.br/docs/
Definição de termos e nomenclaturas
Alguns termos técnicos comuns em integrações que são abordados na nossa documentação são:
API ou Recurso: APIs são Interfaces de Programação de Aplicações, ou um conjunto de endpoints de que formam um recurso como por exemplo: Clientes, Credores, Títulos a Receber. Podemos, por exemplo, obter dados, persistir, editar ou excluir um Cliente. O Recurso ou API é esse conjunto de algumas destas ações que podem ser feitas.
REST ou REST API: REST APIs são APIs para um uso comum transacional, ou seja, transações com um pequeno volume de dados ou registros. Posso obter uma lista limitada ao máximo de 200 clientes por vez, persistir, editar ou excluir um por vez. REST APIs são destinadas a integrações entre sistemas ou aplicativos.
BULK, BULK DATA ou BULK API: BULK APIs são recursos para transacionar um volume de dados maior, requisições massivas, onde você pode fazer uma busca sem limite* de registros. APIs BULK DATA tem uma tecnologia que permite fazer essa consulta sem onerar a sua base de dados ou afetar de forma crítica a performance do seu sistema. BULK DATA é indicada principalmente para criação de relatórios e BI (Business Intelligence).
Webhook: São gatilhos disparados por ações de algum recurso de API, como por exemplo: “Sempre ao incluir um cliente faça...”. Você pode criar eventos para ser notificado sempre que alguma alteração aconteça no seu Sienge. Essas notificações servem para que o outro sistema saiba que algo mudou e poderá buscar os dados e se atualizar com novas informações.
Base URL: É um prefixo de URL que deve ser utilizado em todas as requisições. REST APIs e BULK APIs tem base URLs diferentes, que poderão ser encontradas na documentação.
Endpoints: São especificamente como “endereços” de uma requisição. É composta por um Método HTTP (verbo) e uma URL que indica o que de qual recurso você deseja invocar. Um exemplo de endpoints seria:
[GET {baseURL}/customers] para obter uma lista de clientes.
Métodos HTTP: Esses métodos indicam o tipo de ação da requisição que será efetuada. Você pode utilizar por exemplo:
GET: Para obter algo de um recurso
POST: Para persistir algo em um recurso. Isso quer dizer, ou incluir um conjunto de dados ou invocar a execução de alguma tarefa.
PUT: Para editar um conjunto de dados completo de um recurso. Neste caso sempre utilizará o identificador único do recurso que editará, como por exemplo o ID Único do Cliente.
PATCH: Para editar ou atualizar parte dos dados de um recurso, usado por exemplo quando deseja atualizar o nome do cliente e não o seu endereço.
DELETE: Para excluir um registro completo. Neste caso sempre utilizará o identificador único do recurso que excluirá, como por exemplo o ID Único do Cliente.
Rate-Limits: São limites de requisições por um período definido que estão sujeitas cada uma das contas dos clientes. Existem dois tipos de rate-limits.
Limites de Segurança: São limites fixos que visão proteger a performance das estruturas das APIs que são impostos de forma diferente para REST APIs e BULK APIs. O intervalo de tempo considerado é (Requisições por Minuto).
Limites dos Pacotes: São limites*, bloqueantes ou não, de cada pacote de API. Na documentação tem uma lista completa destes valores e especifica se é ou não bloqueante. Os limites dos pacotes contratados visão atender melhor o perfil de consumo de cada cliente, tendo limites diferentes também para REST APIs e BULK APIs.
Basic Authetication ou basicAuth: É a forma de autenticação requerida para acessar os dados de uma conta do Sienge Plataforma. Autenticação básica requer que você tenha um usuário e uma senha de APIs, “isso não inclui usuário e senha de acesso ao Sienge Plataforma”. É um acesso especial para APIs criado no portal de Integrações.
Subdomínio, subdomain ou tenant: Cada conta de cliente que está na nuvem (Data Center), é exposta publicamente por um URL exclusiva. O Tenant é a parte inicial desta URL. Por exemplo, se sua URL é https://construtoralegal.sienge.com.br, logo seu Tenant é o construtoralegal, que deverá ser informada como parte da Base URL nas requisições.
Request ou Requisição: É cada uma das chamadas feitas nas APIs do Sienge Plataforma. Por exemplo, se você quer obter uma lista de todos os 1.000 clientes cadastrados na sua conta por um endpoint REST, você precisa fazer pelo menos 5 chamadas (requisições). Na primeira obtém os primeiros 200 registros e a quantidade total de registros, na sequência poderá passar novos parâmetros sucessivamente para buscar os demais registros.
Response ou Resposta: A cada Requisição enviada, você receberá uma resposta, seja com os dados solicitados, ou com informações de erros que podem ter ocorrido durante a requisição. Você receberá um Status Code e uma possível mensagem.
Status Code: São os códigos que representam o tipo da resposta de uma requisição. Podendo ser de várias categorias:
Respostas de informação (100-199) - Resposta provisória indica que tudo ocorreu bem até agora e que o cliente deve continuar com a requisição ou ignorar se já concluiu o que gostaria
Respostas de sucesso (200-299) – Acontece quando a requisição não obteve erros e a solicitação foi executada com sucesso.
Redirecionamentos (300-399) - Acontece quando ao se fazer uma requisição ao sistema, o link não está mais disponível naquele endereço e por isso há um redirecionamento para outra página.
Erros do cliente (400-499) – Existem muitas possibilidades diferentes, mas acontece quando cliente faz a requisições de forma inválida, tanto em relação às suas credenciais ou endpoints não encontrado.
Erros do servidor (500-599) – Erros acontecidos no lado do Sienge por motivos diversos.