Padrões

Headers

Todas as requisições devem ter o header:

'Content-type: application/json; charset=utf-8'

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:

Código	Significado
200	Tudo ocorreu como deveria e sua requisição foi processada com sucesso.
400	Algum parâmetro obrigatório não foi passado, ou os parâmetros passados não estão corretos.
401	Falta de autorização para acessar este endpoint.
404	Endpoint não encontrado, revise a URL passada.
500	Erro interno do Tonolucro, tente sua requisição novamente. Caso o erro continue, entre em contato com [e-mail]

Erros

Os possíveis erros retornados pela API Tonolucro são:

Tipo do erro	Significado
invalid_parameter	Quando algum parâmetro passado está incorreto/faltando.
action_forbidden	Quando o usuário não tem permissão para fazer determinada ação.
internal_error	Quando algum erro interno em nosso servidor ocorreu.
not_found	Quando o recurso procurado não foi encontrado/não existe.

RESPONSE

{
    "errors": [
        {
            "status": 400,
            "title": "Objeto não encontrado",
            "code": "not_found"
        }
    ]
}

Listagem e Paginação

Para requisições de listagem de recursos o seguinte modelo é utilizado:

RESPONSE

{
    "items": [...],
    "meta": {
        "page": {
            "total": 430,
            "currentPage": 3,
            "lastPage": 429,
            "perPage": 1
        }
    },
    "links": {
        "first": "/merchant/orders/done?start=2018-07-01&end=2018-07-31&page%5Bnumber%5D=0&page%5Bsize%5D=1",
        "last": "/merchant/orders/done?start=2018-07-01&end=2018-07-31&page%5Bnumber%5D=429&page%5Bsize%5D=1",
        "prev": "/merchant/orders/done?start=2018-07-01&end=2018-07-31&page%5Bnumber%5D=2&page%5Bsize%5D=1",
        "next": "/merchant/orders/done?start=2018-07-01&end=2018-07-31&page%5Bnumber%5D=4&page%5Bsize%5D=1"
    }
}

Atributo	Utilização
items	Uma lista com a representação individual dos recursos.
meta.page.total	Quantidade total de registros encontrados.
meta.page.currentPage	Página atual da navegação.
meta.page.lastPage	Índice da última página da navegação.
meta.page.perPage	Quantidade de itens por página.
links.first	URI da primeira página de resultados, se houver.
links.last	URI da última página de resultados, se houver.
links.prev	URI da página anterior de resultados, se houver.
links.next	URI da próxima página de resultados, se houver.

Paginação

Recomendação de paginação JSONAPI (http://jsonapi.org/format/#fetching-pagination)

/products?page[number]=1&page[size]=100

{
    "links": {
        "first": "/products?page%5Bnumber%5D=0&page%5Bsize%5D=1",
        "last": "/products?page%5Bnumber%5D=429&page%5Bsize%5D=1",
        "prev": "/products?page%5Bnumber%5D=2&page%5Bsize%5D=1",
        "next": "/products?page%5Bnumber%5D=4&page%5Bsize%5D=1"
    }
}

Filtros

Recomendação de filtragem do JSONAPI (http://jsonapi.org/recommendations/#filtering).

/products?filter[sales_category_id]=980&filter[title]=pizza