Princípios básicos

Bem-vindo ao guia da API da Betalabs! Usando esta API que você integra o seu sistema ao nosso.
A seguir, algumas convenções da nossa API:

Quando usar a API Principal

A API Principal serve para requisições vindas de outros sistemas, fora do contexto do e-commerce, e sua principal característica é que ela não guarda estado, ou seja, uma requisição acontece de forma totalmente independente das demais, mesmo tendo como origem o mesmo sistema. Exatamente por isso, essa API não conta com interações em sessão de usuário.
Por essas características, essa API consta com um maior número de funcionalidades e endpoints disponíveis, de forma que praticamente todos os módulos do sistema podem ser acessados e manipulados por ela.

Endpoint base

https://nome-do-seu-projeto.api.betalabs.net/api/
Onde nome-do-seu-projeto deverá ser editado com os dados do seu projeto.

Formatos de requisições e respostas

Para receber respostas em JSON, use os cabeçalhos Content-Type e Accept para informar à API o conteúdo que deseja enviar e receber como resposta. Para esses cabeçalhos, use o valor application/json.

Autenticação

Como obter o seu access token

Entre em contato com o time de sucesso do cliente e informe um usuário do sistema que servirá para a geração do token.

Como usar o seu access token

Informe o seu access token nas suas requisições como valor do cabeçalho da requisição Authorization e com o prefixo Bearer. Exemplo: "Bearer <<seu access token>>".

Paginação

Há muitas rotas de listagem de entidades na API. Em todas elas é necessário lidar com um sistema de paginação para percorrer todos os registros. Esse sistema refere-se aos parâmetros _limit e _offset a serem informados no query string da rota, onde:

• _limit representa quantos resultados por página deverão ser retornados — se não for informado um valor, o padrão é 100, e seu limite é 100.
• _offset é a página a ser retornada e se não for informado um valor, o padrão é 0.

Exemplo:

Carregando 24 registros da entidade a partir do registro 48
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?_limit=24&_offset=48

Ordenação

Nas rotas de listagem é possível ordenar os registros a serem respondidos pela API. Para isso informe o parâmetro _sort no query string com todos os campos a serem considerados para ordenação separados por vírgula. Para ordenação descendente, incluir um hífen como prefixo do nome do campo e para ordenação ascendente informe somente o nome do campo. Para ordenação de campos extras, atentar-se às regras descritas abaixo.

Exemplo:

Ordenando os registros pelo campo ID de forma descendente
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?_sort=-id

Ordenando os registros pelo campo ID de forma ascendente e depois pelo campo extra de forma descendente
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?_sort=id,-slug_11_9

Filtros

Nas rotas de listagem é possível filtrar os registros a serem obtidos como resposta dessas rotas. Para isso informe cada campo com o seu valor para filtro no query string. As cláusulas para comparações poderão ser informadas para filtrar por campos iguais a valor ou semelhante a um valor ou diferente de um valor, maior que um valor, entre outras possibilidades de comparação. Para filtro de campos extras, atentar-se às regras descritas abaixo.

Comparadores

Para igual a, usar somente o nome do campo:
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?campo=valor
Para semelhante a, usar o sufixo "lk" e asterisco como caractere coringa:
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?campo-lk=*valor*
Para diferente de, usar o sufixo "not":
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?campo-not=valor
Para menor que
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?campo-st=valor
Para menor ou igual a
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?campo-max=valor
Para maior que
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?campo-gt=valor
Para maior ou igual a
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?campo-min=valor
Para informar uma lista de valor que o campo deve estar dentro
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?campo-in=valor1,valor2,valor3

Metadados

Alguns meta dados podem ser requisitados para a API para trazer informações sobre a consulta como o total de registros disponíveis para a entidade, a quantidade de registros solicitados, a página atual, a última página, entre outros. Para isso, informar o parâmetro _config no query string e o valor deve ser preenchido com todos os metadados separados por vírgula. Os metadados disponíveis são:

• meta-total
  Valor inteiro correspondente ao total de registros disponíveis para a entidade.
• meta-per-page
  Valor inteiro correspondente à quantidade de registros por página, informado pelo parâmetro _limit ou o padrão se não informado.
• meta-current-page
  Valor inteiro correspondente à página atual, calculado a partir dos parâmetros _limit e _offset ou usando os valores padrões se não informados.
• meta-last-page
  Valor inteiro correspondente à última página disponível para consulta, calculado a partir dos parâmetros _limit e _offset ou usando os valores padrões se não informados.
• meta-has-more-pages
  Valor booleano que informa se a consulta corresponde à última página disponível.

Exemplo:

https://nome-do-seu-projeto.api.betalabs.net/api/entidade?_config=meta-current-page,meta-last-page,meta-has-more-pages

Corpo da resposta em JSON

Os registros das entidades solicitadas serão retornados sempre dentro de um índice data dentro do objeto de resposta, que representa um array com todos os registros da entidade consultada. Os metadados, se solicitados, serão retornados sempre dentro de um índice meta, objeto com somente os metadados solicitados:

{
      "data": [
          {...},
          {...},
          {...}
      ],
      "meta": {
      	  "meta-total": 123,
          "meta-per-page": 123,
          "meta-current-page": 1,
          "meta-last-page": 123,
          "meta-has-pages": false,
          "meta-has-more-pages": false
      }
  }

Códigos de resposta

Nossa API usa como retorno os códigos HTTP padrão para indicar tanto o sucesso de uma requisição, quanto para indicar falha. Segue:

Lidando com campos extras

Campos extras podem ser criados em formulários extras em todas as entidades disponíveis no sistema. Para referenciá-los na API, o nome do campo será composto pelo seu slug + id do formulário a que ele pertence + id do campo extra, intercalados por underline. Exemplo:

meu_campo_extra_123_321

Para campos extras que relacionam a outra entidade, deve-se acrescentar o sufixo "_id" no final do nome do campo para informar seu valor em rotas de criação e edição (POST e PUT, respectivamente) e o sufixo "->id" para filtros em listagens. Exemplos:

Filtragem:
https://nome-do-seu-projeto.api.betalabs.net/api/entidade?meu_campo_extra_123_321->id=999

Criação e edição:

{
    'campo': 'valor',
    'meu_campo_extra_referencia_de_entidade_123_321_id': 999,
    'meu_campo_extra_texto': 'valor'
}