65

Documentação da API

Mogg
Versão v1

Plataforma web para criação de produtos customizados utilizando arquitetura de

microserviços com Docker

Desenvolvido por:
Anderson Barberini

ERECHIM – RS
2017
 66

SUMÁRIO

A.1 INTRODUÇÃO ........................................................................................................... 67

A.2 AUTENTICAÇÃO ...................................................................................................... 68
A.3 EMPRESAS ................................................................................................................. 73
A.4 CLIENTES ................................................................................................................... 80
A.5 PEDIDOS ..................................................................................................................... 87
 67

A.1 INTRODUÇÃO

A Mogg foi desenvolvida baseada em um conjunto de APIs criadas através de uma

arquitetura de microserviços. Sua comunicação é baseada no protocolo HTTP e utiliza o
conjunto de princípios do modelo REST para integrar as APIs com a aplicação Web. As
informações contidas na requisição são informadas através de parâmetros e o retorno dos dados
utiliza somente o formato JSON. Seu acesso é realizado através do Kong API Gateway.
A API utiliza uma interface uniforme onde é necessário definir a ação de uma solicitação
através dos métodos oferecidos pelo protocolo HTTP. Segue a seguir os métodos utilizados:

 GET: usado para buscar e retornar um determinado recurso;

 POST: usado para criar um determinado recurso;

 PUT: usado para alterar um recurso específico;

 DELETE: usado para deletar um recurso específico.

Todas as solicitações enviadas à API irão retornar uma resposta com um código HTTP
correspondente ao resultado obtido na requisição. Através desse código é possível identificar o
status da solicitação, sendo ela sucesso ou falha. A Tabela A.1 descreve os códigos HTTP
utilizados pela API, juntamente com o status de cada código e sua descrição.

Tabela A.1 – Códigos HTTP das requisições

Código Status Descrição

200 Sucesso Padrão para solicitações realizadas com sucesso
201 Sucesso Entidade criada
204 Sucesso Sem conteúdo, entidade ou recurso excluído
400 Erro de cliente Erro ao processar a solicitação
401 Erro de cliente Acesso não autorizado, usuário deve informar o token
404 Erro de cliente Entidade ou recurso não existe
422 Erro de cliente Falha na validação dos parâmetros
500 Erro no servidor Erro crítico na aplicação ou no servidor
Fonte: Autor

Nas próximas sessões serão apresentadas as APIs da aplicação, contendo os recursos

disponíveis, parâmetros necessários e retornos de dados.
 68

A.2 AUTENTICAÇÃO

API responsável por manter as credenciais dos usuários e também de realizar as funções
de login e logout. A seguir estão mapeadas as rotas da API de autenticação.

Path: /v1/auth/companies
Descrição: Cria as credenciais para a empresa, conforme parâmetros descritos na Tabela A.2.
Método: POST

Tabela A.2 - Parâmetros do recurso POST /v1/auth/companies

Parâmetro Tipo Descrição

company_id Integer ID da empresa
login String | E-mail Login de acesso, com validação de e-mail.
password String Senha de acesso
Fonte: Autor

As figuras representadas pela Figura A.1, Figura A.2 e Figura A.3 representam os
possíveis retornos da solicitação do recurso POST /v1/auth/companies.

Figura A.1 - HTTP 201 Credenciais da empresa criadas com sucesso

{
"company_id": "1",
"login": "email@empresa.com.br",
"id": 1
}

Fonte: Autor
 69

Figura A.2 - HTTP 422 Erro na validação dos parâmetros

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"company_id": [
"O campo company id é obrigatório."
],
"login": [
"O campo login é obrigatório."
],
"password": [
"O campo senha é obrigatório."
]
}
}

Fonte: Autor

Figura A.3 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/auth/clients
Descrição: Cria as credenciais para o cliente, através dos parâmetros descritos na Tabela A.3.
Método: POST

Tabela A.3 - Parâmetros do recurso POST /v1/auth/clients

Parâmetro Tipo Descrição

cliente_id Integer ID do cliente
company_id Integer ID da empresa
login String | E-mail Login de acesso, com validação de e-mail.
password String Senha de acesso
Fonte: Autor

As figuras representadas pela Figura A.4, Figura A.5 e Figura A.6 representam os
possíveis retornos da solicitação do recurso POST /v1/auth/clients.
 70

Figura A.4 - HTTP 201 Credenciais do cliente criadas com sucesso

{
"client_id": "1",
"company_id": "1",
"login": "email@empresa.com.br",
"id": 2
}

Fonte: Autor

Figura A.5 - HTTP 422 Erro na validação dos parâmetros

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"client_id": [
"O campo client id é obrigatório."
],
"company_id": [
"O campo company id é obrigatório."
],
"login": [
"O campo login é obrigatório."
],
"password": [
"O campo senha é obrigatório."
]
}
}

Fonte: Autor

Figura A.6 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/auth/login
Descrição: Realiza o processo de login, retornando um token para o usuário. Os parâmetros
necessários estão descritos na Tabela A.4.
Método: POST
 71

Tabela A.4 - Parâmetros do recurso POST /v1/auth/login

Parâmetro Tipo Descrição

login String Login de acesso
password String Senha de acesso
role String | client, company, partner Tipo de usuário
company_id Integer. Obrigatório caso role for client ID da empresa
Fonte: Autor

As figuras representadas pela Figura A.7, Figura A.8 e Figura A.9 representam os
possíveis retornos da solicitação do recurso POST /v1/auth/login.

Figura A.7 - HTTP 200 Login realizado com sucesso

{
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3ODJmY2NkODgzMGI0NjQxYWY1NTIzMWYyYjcwYTB
lNSIsImp0aSI6IjZlOGY3OTc4LWQxZTEtNDkyZS1iODIzLTczN2Y2YTBhZjkyZiIsImV4cCI6MTUxMTI4OTA0Niwi
cm9sZSI6ImNsaWVudCIsImNpZCI6ImJiNjNmYmFkLWFlNWQtNDY4Ni1iMmFjLTZlOTRiYmIxOTI4YyIsImNsaWVud
F9pZCI6IjMiLCJjb21wYW55X2lkIjoiMSJ9.djd8e_Jpu62jU9bQBtn0Y8CmjnOmrHI2j4puZYu7d_8"
}

Fonte: Autor

Figura A.8 - HTTP 422 Erro na validação dos parâmetros

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"login": [
"O campo login é obrigatório."
],
"password": [
"O campo senha é obrigatório."
],
"role": [
"O campo role é obrigatório."
]
}
}

Fonte: Autor
 72

Figura A.9 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/auth/logout
Descrição: Realiza o processo de logout, excluindo o token do usuário. O token deve ser
informado no Header, conforme a Tabela A.5.
Método: POST

Tabela A.5 - Parâmetros extras do recurso POST /v1/auth/logout

Header Tipo Descrição

Authorization String | Bearer Token JWT utilizado no acesso
Fonte: Autor

Ao finalizar a requisição, se tudo ocorreu bem, o logout foi realizado com sucesso e o retorno
será com um HTTP 204, caracterizado por não ter nenhuma informação na resposta. A Figura
A.10 e
Figura A.11 representam os possíveis retornos recurso /v1/auth/logout em casos de
ocorrer algum erro.

Figura A.10 - HTTP 422 Erro na validação dos parâmetros

{
"message": "Token não encontrado",
"status_code": 422
}

Fonte: Autor

Figura A.11 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor
 73

A.3 EMPRESAS

API responsável por manter as informações das empresas cadastradas. Toda solicitação
deve contar um header extra, informando o token de acesso, através do campo Authorization
Bearer, descrito na Tabela A.6.

Tabela A.6 - Parâmetros extras do header da API de Empresas

Header Tipo Descrição

Authorization String | Bearer Token JWT utilizado no acesso
Fonte: Autor

Path: /v1/companies
Descrição: Busca ou retorna as empresas. A busca é feita através do parâmetro path. Os
parâmetros disponíveis estão listados na Tabela A.7.
Método: GET

Tabela A.7 - Parâmetros do recurso GET /v1/companies

Parâmetro Tipo Descrição

path String. Opcional Path de acesso da empresa
Fonte: Autor

A Figura A.12 e Figura A.13 representam os possíveis retornos da solicitação do recurso

GET /v1/companies, sendo a primeira em caso de sucesso, e a segunda em caso de ocorrer
algum erro.
 74

Figura A.12 - HTTP 200 Empresas listadas com sucesso.

[
{
"id": 1,
"name": "Nome da empresa",
"email": "email@empresa.com.br",
"path": "empresa",
"phone_number": "(99) 9999-9999",
"home_number": null,
"about": "Texto sobre a empresa",
"product_price": 35
},
{
"id": 2,
"name": "Empresa 2",
"email": "email@empresa2.com.br",
"path": "empresa2",
"phone_number": "(99) 9999-9999",
"home_number": null,
"about": "Texto sobre a empresa",
"product_price": 45
}
]

Fonte: Autor

Figura A.13 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/companies/{id}
Descrição: Retorna uma empresa específica com base no ID. Os parâmetros disponíveis se
encontram na Tabela A.8.
Método: GET

Tabela A.8 - Parâmetros do recurso GET /v1/companies/{id}

Parâmetro Tipo Descrição

{id} Integer ID da empresa
Fonte: Autor
 75

Ao finalizar a solicitação, o retorno esperado é conforme representado pela Figura A.14.

Em caso da empresa não existir, ou seja, o ID for inválido, o retorno é e acordo com a Figura
A.15. Em caso de ocorrer algum erro na solicitação, o formato de reposta é de acordo com o
descrito na Figura A.16.

Figura A.14 - HTTP 200 Empresa retornada com sucesso.

{
"id": 1,
"name": "Nome da empresa",
"email": "email@empresa.com.br",
"path": "empresa",
"phone_number": "(99) 9999-9999",
"home_number": null,
"about": "Texto sobre a empresa",
"product_price": 35
}

Fonte: Autor

Figura A.15 - HTTP 404 Empresa não existe

{
"message": "Empresa não existe.",
"status_code": 404
}

Fonte: Autor

Figura A.16 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/companies
Descrição: Cadastra uma nova empresa. Os parâmetros e informações disponíveis estão
descritos na Tabela A.9.
Método: POST
 76

Tabela A.9 - Parâmetros do recurso POST /v1/companies

Parâmetro Tipo Descrição

name String Nome da empresa
email String | E-mail E-mail da empresa
phone_number String Telefone celular
home_number String. Opcional Telefone fixo
path String Path de acesso ao site
password String Senha
about String. Opcional Texto sobre a empresa
product_price Double Preço do produto à venda
Fonte: Autor

As figuras representadas pela Figura A.17, Figura A.18 e Figura A.19 representam os
possíveis retornos da solicitação do recurso POST /v1/companies.

Figura A.17 - HTTP 201 Empresa criada com sucesso

{
"id": 1,
"name": "Nome da empresa",
"email": "email@empresa.com.br",
"path": "empresa",
"phone_number": "(99) 9999-9999",
"home_number": null,
"about": "Texto sobre a empresa",
"product_price": 35
}

Fonte: Autor
 77

Figura A.18 - HTTP 422 Erro na validação dos parâmetros.

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"name": [
"O campo nome é obrigatório."
],
"email": [
"O campo email é obrigatório."
],
"phone_number": [
"O campo celular é obrigatório."
],
"path": [
"O campo path é obrigatório."
],
"password": [
"O campo senha é obrigatório."
]
}
}

Fonte: Autor

Figura A.19 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/companies/{id}
Descrição: Atualiza uma empresa específica com base no ID. Os parâmetros disponíveis para
a alteração de uma empresa estão listados na Tabela A.10.
Método: PUT

Tabela A.10 - Parâmetros do recurso PUT /v1/companies/{id}

Parâmetro Tipo Descrição

name String Nome da empresa
email String | E-mail E-mail da empresa
phone_number String Telefone celular
home_number String. Opcional Telefone fixo
 78

path String Path de acesso ao site

password String Senha
about String. Opcional Texto sobre a empresa
product_price Double Preço do produto a venda
Fonte: Autor

As figuras representadas pela Figura A.20, Figura A.21, Figura A.22 E Figura A.23
representam os possíveis retornos da solicitação do recurso PUT /v1/companies/{id}, sendo o
primeiro para caso de sucesso, e os demais para caso de erro.

Figura A.20 - HTTP 200 Empresa atualizada com sucesso

{
"id": 1,
"name": "Nome da empresa",
"email": "email@empresa.com.br",
"path": "empresa",
"phone_number": "(99) 9999-9999",
"home_number": null,
"about": "Texto sobre a empresa",
"product_price": 35
}

Fonte: Autor

Figura A.21 - HTTP 404 Empresa não existe

{
"message": "Empresa não existe.",
"status_code": 404
}

Fonte: Autor
 79

Figura A.22 - HTTP 422 Erro na validação dos parâmetros.

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"name": [
"O campo nome é obrigatório."
],
"email": [
"O campo email é obrigatório."
],
"phone_number": [
"O campo celular é obrigatório."
],
"path": [
"O campo path é obrigatório."
],
"password": [
"O campo senha é obrigatório."
]
}
}

Fonte: Autor

Figura A.23 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor
 80

A.4 CLIENTES

API responsável por manter as informações das dos clientes de uma determinada
empresa. Toda solicitação deve contar um header extra, informando o token de acesso, através
do campo Authorization Bearer, conforme representado na Tabela A.11.

Tabela A.11 - Parâmetros extras do header da API de Clientes

Header Tipo Descrição

Authorization String | Bearer Token JWT utilizado no acesso
Fonte: Autor

Path: /v1/clients
Descrição: Busca ou retorna os clientes de uma empresa. A busca é realizada através do
parâmetro search, conforme descrito na Tabela A.12.
Método: GET

Tabela A.12 - Parâmetros do recurso GET /v1/clients

Parâmetro Tipo Descrição

Termo para buscar um cliente,
search String. Opcional
através do nome ou e-mail
Fonte: Autor

As figuras representadas pela Figura A.24 e Figura A.25 representam os dois possíveis
retornos desta solicitação, sendo a primeira em caso de sucesso e a segunda em caso de erro.
 81

Figura A.24 - HTTP 200 Clientes retornados com sucesso.

[
{
"id": 1,
"company_id": "1",
"name": "Pedro",
"email": "pedro@dominio.com.br",
"phone_number": "(99) 9999-9999",
"home_number": null,
"gender": "male",
"date_birth": "1991-05-22"
},
{
"id": 2,
"company_id": "1",
"name": "Maria",
"email": "maria@dominio.com.br",
"phone_number": "(99) 9999-9999",
"home_number": null,
"gender": "female",
"date_birth": "1992-08-12"
}
]

Fonte: Autor

Figura A.25 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/clients/{id}
Descrição: Retorna um cliente específico com base no ID, conforme descrito na Tabela A.13.
Método: GET

Tabela A.13 - Parâmetros do recurso GET /v1/clients/{id}

Parâmetro Tipo Descrição

{id} String. ID do cliente
Fonte: Autor

Os retornos deste recurso estão representados pela Figura A.26, Figura A.27 e Figura
A.28, mapeando os status de sucesso e de erro.
 82

Figura A.26 - HTTP 200 Cliente retornado com sucesso.

{
"id": 1,
"company_id": "1",
"name": "Pedro",
"email": "pedro@dominio.com.br",
"phone_number": "(99) 9999-9999",
"home_number": null,
"gender": "male",
"date_birth": "1991-05-22"
}

Fonte: Autor

Figura A.27 - HTTP 404 Cliente não existe

{
"message": "Cliente não existe.",
"status_code": 404
}

Fonte: Autor

Figura A.28 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/clients/statistics
Descrição: Retorna as estatísticas de clientes de uma empresa, contendo o número total de
cadastros.
Método: GET

A requisição pode ter dois tipos de retorno, sendo um em caso de sucesso, representado
pela Figura A.29, ou pela Figura A.30, em caso de erro.
 83

Figura A.29 - HTTP 200 Estatísticas de clientes

{
"total_clients": 5
}

Fonte: Autor

Figura A.30 - HTTP 400/500 Erro ao processar a requisição.

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/clients
Descrição: Cadastra um novo cliente. Os parâmetros e informações disponíveis estão descritos
na Tabela A.14.
Método: POST

Tabela A.14 - Parâmetros do recurso POST /v1/clients

Parâmetro Tipo Descrição

name String Nome do cliente
email String | E-mail E-mail do cliente
phone_number String Telefone celular
home_number String. Opcional Telefone fixo
date_birth Date | (dd/mm/yy) Data de nascimento
gender String | male, female Gênero
password String. Opcional Senha de acesso
company_id Integer ID da empresa
Fonte: Autor

As figuras representadas pela Figura A.31, Figura A.32 e Figura A.33 representam os
três possíveis retornos desta solicitação, sendo a primeira em caso de sucesso e as demais em
caso de erro.
 84

Figura A.31 - HTTP 201 Cliente cadastrado com sucesso.

{
"company_id": "1",
"name": "João",
"email": "joao@dominio.com",
"phone_number": "(99) 9999-9999",
"date_birth": "1993-02-12",
"gender": "male",
"home_number": null,
"id": 3
}

Fonte: Autor

Figura A.32 - HTTP 422 Erro na validação dos parâmetros.

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"company_id": [
"O campo empresa é obrigatório."
],
"name": [
"O campo nome é obrigatório."
],
"email": [
"O campo email é obrigatório."
],
"date_birth": [
"O campo data de nascimento é obrigatório."
],
"phone_number": [
"O campo celular é obrigatório."
],
"gender": [
"O campo gênero é obrigatório."
]
}
}

Fonte: Autor

Figura A.33 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor
 85

Path: /v1/clients/{id}
Descrição: Atualiza um cliente específico com base no ID. Os parâmetros disponíveis para a
alteração de um cliente estão listados na Tabela A.15.
Método: PUT

Tabela A.15 - Parâmetros do recurso PUT /v1/clients/{id}

Parâmetro Tipo Descrição

name String Nome do cliente
email String | E-mail E-mail do cliente
phone_number String Telefone celular
home_number String. Opcional Telefone fixo
date_birth Date | (dd/mm/yy) Data de nascimento
gender String | male, female Gênero
Fonte: Autor

As figuras representadas pela Figura A.34, Figura A.35, Figura A.36 e Figura A.37
descrevem os possíveis retornos desta solicitação.

Figura A.34 - HTTP 200 Cliente atualizado com sucesso.

{
"company_id": "1",
"name": "João",
"email": "joao@dominio.com",
"phone_number": "(99) 9999-9999",
"date_birth": "1993-02-12",
"gender": "male",
"home_number": null,
"id": 3
}

Fonte: Autor

Figura A.35 - HTTP 404 Cliente não existe

{
"message": "Cliente não existe.",
"status_code": 404
}

Fonte: Autor
 86

Figura A.36 - HTTP 422 Erro na validação dos parâmetros.

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"name": [
"O campo nome é obrigatório."
],
"email": [
"O campo email é obrigatório."
],
"date_birth": [
"O campo data de nascimento é obrigatório."
],
"phone_number": [
"O campo celular é obrigatório."
],
"gender": [
"O campo gênero é obrigatório."
]
}
}

Fonte: Autor

Figura A.37 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor
 87

A.5 PEDIDOS

API responsável por manter as informações dos pedidos de clientes. Toda solicitação
deve contar um header extra, informando o token de acesso, através do campo Authorization
Bearer, conforme a Tabela A.16 descreve.

Tabela A.16 - Parâmetros extras do header da API de Pedidos

Header Tipo Descrição

Authorization String | Bearer Token JWT utilizado no acesso
Fonte: Autor

Cada pedido possui um status no qual identifica a situação em que se encontra. Eles
podem assumir cinco tipos diferentes, conforme descritos na Tabela A.17.

Tabela A.17 - Status dos pedidos

Status Descrição
submitted Pedido realizado, é o status inicial da ordem
processing Em processamento, ou seja, a empresa está processando o pedido
ready O pedido está pronto, finalizado
completed O pedido já foi entregue
cancelled Pedido cancelado
Fonte: Autor

Path: /v1/orders
Descrição: Retorna os pedidos de uma empresa ou de um cliente, com base no tipo de usuário,
informação que está contida no token informado no Header.
Método: GET

Os dois possíveis retornos desta solicitação são representados pela Figura A.38, em caso
de sucesso, e pela Figura A.39 em caso de erro.
 88

Figura A.38 - HTTP 200 Pedidos retornados com sucesso.

[
{
"id": 1,
"client_name": "João",
"client_email": "joao@dominio.com.br",
"client_id": "1",
"company_id": "1",
"status": "ready",
"total_price": "35",
"created_at": "2017-11-01 15:25:00",
"updated_at": "2017-11-03 11:31:49"
},
{
"id": 2,
"client_name": "Maria",
"client_email": "maria@dominio.com.br",
"client_id": "2",
"company_id": "1",
"status": "completed",
"total_price": "105",
"created_at": "2017-10-09 20:14:22",
"updated_at": "2017-11-08 11:08:05"
}
]

Fonte: Autor

Figura A.39 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/orders/{id}
Descrição: Retorna um pedido específico com base no ID, apresentado na Tabela A.18.
Método: GET

Tabela A.18 - Parâmetros do recurso GET /v1/orders/{id}

Parâmetro Tipo Descrição

{id} String. ID do pedido
Fonte: Autor
 89

A Figura A.40, Figura A.41 e Figura A.42 apresenta os três possíveis retornos da
solicitação, sendo o primeiro em caso de sucesso e os demais caso ocorrer algum erro.

Figura A.40 - HTTP 200 Pedido retornado com sucesso.

{
"id": 1,
"client_name": "João",
"client_email": "joao@dominio.com.br",
"client_id": "1",
"company_id": "1",
"status": "ready",
"total_price": "35",
"created_at": "2017-11-01 15:25:00",
"updated_at": "2017-11-03 11:31:49",
"items": [
{
"id": 1,
"quantity": "1",
"price": "35",
"name": "Caneca padrão branca",
"file_name": "product-1509543199.png"
}
]
}

Fonte: Autor

Figura A.41 - HTTP 404 Pedido não existe

{
"message": "Pedido não existe.",
"status_code": 404
}

Fonte: Autor

Figura A.42 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/ orders/{id}/items

Descrição: Retorna os itens que compõem determinado pedido. É necessário informar o ID,
conforme descrito na Tabela A.19.
 90

Método: GET

Tabela A.19 - Parâmetros do recurso GET /v1/orders/{id}/items

Parâmetro Tipo Descrição

{id} String. ID do pedido
Fonte: Autor

A Figura A.43, Figura A.44 e Figura A.45 apresenta os três possíveis retornos desta
solicitação, sendo o primeiro em caso de sucesso e os demais caso ocorrer algum erro.

Figura A.43 - HTTP 200 Items retornados com sucesso

[
{
"id": 1,
"quantity": "1",
"price": "35",
"name": "Caneca padrão branca",
"file_name": "product-1509543199.png"
}
]

Fonte: Autor

Figura A.44 - HTTP 404 Pedido não existe

{
"message": "Pedido não existe.",
"status_code": 404
}

Fonte: Autor

Figura A.45 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor
 91

Path: /v1/orders/statistics
Descrição: Retorna as estatísticas de pedidos de uma empresa, sendo elas a quantidade de
pedidos e o valor total de vendas.
Método: GET

Esta solicitação pode ter dois tipos de retorno, sendo um em caso de sucesso,
representado pela Figura A.46, e outro em caso de erro, conforme apresenta a Figura A.47.

Figura A.46 - HTTP 200 Estatísticas retornadas com sucesso.

{
"total_orders": 2,
"total_price": 140
}

Fonte: Autor

Figura A.47 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/orders
Descrição: Cria um novo pedido. As informações da ordem estão descritas na Tabela A.20.
Os produtos que compões a ordem são informados através do campo items, parâmetro do tipo
lista onde cada item possui suas informações, representados através da Fonte: Autor

Tabela A.21.
Método: POST

Tabela A.20 - Parâmetros da ordem do recurso POST /v1/orders

Parâmetro Tipo Descrição

client_name String Nome do cliente
client_email String | E-mail E-mail do cliente
cliente_id Integer ID do cliente
 92

company_id Integer ID da empresa

Lista de itens do pedido. Fonte: Autor
items Array
Tabela A.21
Fonte: Autor

Tabela A.21 - Parâmetros do item da ordem, do recurso POST /v1/orders

Parâmetro Tipo Descrição

name String Nome do produto
price Double Preço do produto
quantity Integer Quantidade
file_name String Nome do arquivo para impressão
Fonte: Autor

As figuras representadas pela Figura A.48, Figura A.49 e Figura A.50 demonstram os
possíveis retornos desta solicitação, sendo em caso de sucesso ou erro.

Figura A.48 - HTTP 201 Pedido criado com sucesso.

{
"id": 1,
"client_name": "João",
"client_email": "joao@dominio.com.br",
"client_id": "1",
"company_id": "1",
"status": "ready",
"total_price": "35",
"created_at": "2017-11-01 15:25:00",
"updated_at": "2017-11-03 11:31:49",
"items": [
{
"id": 1,
"quantity": "1",
"price": "35",
"name": "Caneca padrão branca",
"file_name": "product-1509543199.png"
}
]
}

Fonte: Autor
 93

Figura A.49 - HTTP 422 Erro na validação dos parâmetros

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"client_name": [
"O campo nome do cliente é obrigatório."
],
"client_email": [
"O campo e-mail do cliente é obrigatório."
],
"client_id": [
"O campo id do cliente é obrigatório."
],
"company_id": [
"O campo company id é obrigatório."
],
"items": [
"O campo items é obrigatório."
]
}
}

Fonte: Autor

Figura A.50 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor

Path: /v1/orders/{id}/status
Descrição: Atualiza o status de um pedido específico. Os parâmetros necessários estão
descritos na Tabela A.22.
Método: PUT

Tabela A.22 - Parâmetros do recurso PUT /v1/orders/{id}/status

Parâmetro Tipo Descrição

{id} String. ID do pedido
status String Status do pedido
Fonte: Autor
 94

As figuras representadas pela Figura A.51, Figura A.52, Figura A.53 e Figura A.54
descrevem os possíveis retornos desta solicitação, sendo a primeira em caso se sucesso na
alteração e as demais em caso de falha.

Figura A.51 - HTTP 200 Status alterado com sucesso.

{
"id": 1,
"client_name": "João",
"client_email": "joao@dominio.com.br",
"client_id": "1",
"company_id": "1",
"status": "completed",
"total_price": "35",
"created_at": "2017-11-01 15:25:00",
"updated_at": "2017-11-03 11:31:49"
}

Fonte: Autor

Figura A.52 - HTTP 404 Pedido não existe

{
"message": "Pedido não existe.",
"status_code": 404
}

Fonte: Autor

Figura A.53 - HTTP 422 Erro na validação dos parâmetros

{
"message": "Alguns dados informados estão inválidos.",
"status_code": 422,
"errors": {
"status": [
"O campo status é obrigatório."
]
}
}

Fonte: Autor
 95

Figura A.54 - HTTP 400/500 Erro ao processar a requisição

{
"message": "Ocorreu um erro ao processar o pedido.",
"status_code": 400
}

Fonte: Autor