Documentação API

Esta página descreve a API do ISILIST. Ela deve ser utilizada por clientes ou aplicações de terceiros que desejem realizar consultas e alterações de dados, como carga de produtos ou obter as listas criadas para uma determinada loja.

A API do ISILIST pode ser acessada por meio de serviços RESTful, ideal para aplicações web e servidores de aplicação, ou por meio de um Android ContentProvider, voltado para aplicações de terceiros Android.

Utilize o guia Integração para obter uma visão geral do processo de integração de uma aplicação de terceiro ao ISILIST.

Entre em contato com a equipe de suporte (suporte@isilist.com.br) caso tenha dúvidas na utilização da API.

Serviços RESTful

Os seguintes recursos podem ser consultados e alterados por meio dos serviços RESTful:

Esquema

Os dados devem ser acessados utilizando o protocolo HTTPS, por meio do endereço https://api.isilist.com.br. É empregado o formato JSON para envio e recebimento dos dados.

Nas requisições de atualização de dados, todos as propriedades de um recurso devem ser informadas. Propriedades vazias devem ser ser informadas com valor null em vez de omitidos.

Datas e horas devem ser codificadas segundo a ISO 8601, no formato YYYY-MM-DDTHH:MM:SSZ. Podem ser informadas datas em fusos horários distintos do UTC, no entanto as datas retornadas pelos serviços do ISILIST normalmente serão no fuso horário UTC.

Erros

Verbos HTTP

Sempre que possível, os serviços RESTful tratam os seguintes verbos HTTP.

Verbo Descrição
GET Obtém os recursos indicados pela URL
POST Utilizado para criar novos recursos
PUT Utilizado para atualizar recursos existentes
DELETE Utilizado para excluir recursos

Operações em bloco

Além de receber um único recurso, os verbos POST, PUT e DELETE também aceitam o envio de um conjunto de recursos por meio de um array de objetos JSON. A resposta a uma requisição de um array de recursos é um array de objetos JSON de mesmo tamanho da requisição, contento as respostas associadas a cada item, na mesma ordem da requisição.

Caso ocorra uma falha no processamento de um recurso, a requisição inteira será abortada e o erro será retornado como resposta. É sugerido que cargas de dados de tamanho elevado sejam quebradas em várias requisições menores, caso a atomicidade da transação não seja importante para a aplicação.

Autenticação

A maioria das requisições do ISILIST exige a identificação do usuário requisitante. O ISILIST suporta dois mecanismos de autenticação.

Autenticação básica

O email e a senha do usuário devem ser informados no cabeçalho da requisição. Mais detalhes em: http://en.wikipedia.org/wiki/Basic_access_authentication.

$ curl -u isilist@mycompany.com https://api.isilist.com.br/v1/search/users

Tokens OAuth2

O token de acesso pode ser enviado no cabeçalho ou como parâmetro da requisição. Exemplos:

$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.isilist.com.br/v1/search/users

$ curl https://api.isilist.com.br/v1/search/users?access_token=OAUTH-TOKEN

Leia mais sobre tokens OAuth2.

Android ContentProvider

O aplicativo ISILIST para Android disponibiliza um ContentProvider para que outras aplicações Android consultem os dados do usuário autenticado no ISILIST. Mais detalhes podem ser obtidos aqui.