A Suitable API é uma API REST que dá a integradores acesso, de forma programática, aos dados de uma loja no ecossistema Suitable.

Esta documentação é referente à versão 1.0.1 da API. Para começar uma integração, autenticar, entender os escopos, a paginação e os limites de uso, consulte os Guias.

Limites de requisições

Por padrão, cada loja pode fazer até 120 requisições por minuto. Veja Uso, limites e boas práticas para os detalhes.

Convenções

Identificadores: todo id é um inteiro, único dentro da loja. Os ids retornados pelas listagens são os mesmos aceitos pelos endpoints de detalhes (por exemplo, o id de /api/order/list em /api/order/details/?order_id=).

Caminhos: use os caminhos exatamente como documentados, incluindo ou não a barra final.

Paginação: a paginação é por deslocamento, se itens forem criados enquanto você percorre as páginas, um mesmo item pode aparecer em duas páginas, deduplique pelo id caso necessário.

Campos nulos: campos opcionais sem valor são retornados como null, nunca omitidos. Listas sem itens são retornadas como [].

Valores enumerados: campos como status e order_type usam códigos fixos em snake_case (em inglês, assim como os nomes dos campos), listados na descrição de cada campo. Use esses códigos para a lógica da integração e, se precisar exibi-los, traduza-os no seu sistema. Novos valores podem ser adicionados no futuro, trate valores desconhecidos para evitar quebrar a integração.

Erros

Toda resposta 4XX e 5XX tem o mesmo formato:

{
  "detail": "Nenhum pedido com esse id nesta loja.",
  "code": "not_found"
}

Use code para tratar o erro no seu código e detail apenas para logs e mensagens de diagnóstico. O endpoint de token também responde no formato OAuth 2.0 (error / error_description); veja Autenticação e permissões.

Em erros 422, detail é uma lista com um item por parâmetro inválido, indicando onde está o problema (loc) e o motivo (msg):

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["query", "page"],
      "msg": "Input should be greater than or equal to 1",
      "input": "0",
      "ctx": {"ge": 1}
    }
  ],
  "code": "invalid_parameters"
}