Proxy Media

Clube de Benefícios
APIs Restful para integração

Versão 1.1
Clube Ben Versão 1.0

API de Integração 13/09/2017

Histórico de Revisões

Data Alteração Responsável Versão

13/09/2017 Elaboração do documento André Oliveira 1.0

16/02/2018 Adicionado recurso de retornar travas André Oliveira 1.1

2 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

Índice Analítico

Clube de Benefícios 1
Histórico de Revisões 2
Índice Analítico 3
Introdução 4
Finalidade 4
Escopo 4
Webservice 4
Endpoints 4
Autenticação 4
Descrição 4
Formato 5
Exemplo de Chamada 5
Requests 5
Descrição 5
Formato do Envio 5
Responses 6
Descrição 6
Códigos de Sucesso 6
Códigos de Erro 7
Erros 7
Validação dos Erros 7
Paginação 8
API de Resgates 9
Descrição 9
Filtros Aceitos 9
Exemplo de Chamada 10
API de Usuários 11
Descrição 11
Filtros Aceitos 12
Exemplo de Chamada 12

3 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

API de Integração

1. Introdução

1.1. Finalidade
Este documento descreve os serviços expostos via API na plataforma Clube
Ben.

1.2. Escopo
Todos os serviços são disponibilizados via API RESTful.
O número máximo de registros disponibilizados por chamada é de 500 por
página.

2. Webservice

2.1. Endpoints

2.1.1. Ambiente de Homologação:

[Link]

2.1.2. Ambiente de Produção:

[Link]

2.2. Autenticação

2.2.1. Descrição

A API é autenticada via ​HTTP Basic Auth​ sobre HTTPS. Qualquer solicitação
via HTTP será rejeitada.
Após efetuar a autenticação, a API retorna um token no formato ​JWT​.
O Token tem duração de 1 (uma) hora. Após o tempo, será necessário
solicitar nova autenticação.

As credenciais de acesso às APIs podem ser criadas pelo administrador do

clube.

4 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

2.2.2. Formato

Método: POST
Endereço: ​[Link]
Parâmetros:
● email: string com o usuário com permissão de acesso.
● senha: string com a senha do usuário.

Exemplo de Chamada

$ curl [Link] -d
"email=email@[Link]&senha=pass" -X POST

Retorno

Sucesso:

{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwv
XC9ob21vbG9nLmNsdser3d3S57J9FDOfiivvIJ71Moy3lVvfus9-HoMy8"}

Erro de Autenticação (400):

{"message":"Email or password is wrong.","error":"No user found."}

2.3. Requests

2.3.1. Descrição

A base da URL de chamada da API é ​[Link]

onde ​clube​ deve ser substituído pelo clube desejado.

2.3.2. Formato do Envio

A requisição deve ser realizada via GET codificado como JSON e deve
possuir o cabeçalho ​“Content-Type”​ como ​“application/json”.​ Caso o formato

5 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

enviado não esteja correto a API retornará o erro ​“415 Unsupported Media
Type”.

$ curl [Link] \
-X GET \
-H "x-authorization:
eyJ0eXAiOiJKcxzcV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvX
C9ob21vbG9nLmNsdWJlYmVuLnByb3h5Lm1lZGlhIiwiaWF0IjoxNTA1NDk
wNTY3LCJuYmYiOjE1MDU0OTA1NxcxcjcsImV4cCI6MTUwNTQ5NDE2Ny
wiaWQiOiI4Nzxcc0OSIsImVtYWlsIjoiYW5kcmVAcHJveHltZWRpYS5jb20u
YnIiLCJjbHViZV9pZCI6IjMwIn0.zADIxcxccPYJ64a2mRYdbJs5ow2zJtWzV
WR-dZbrlW4vA0s" \
-H "Content-Type: application/json"

2.4. Responses

2.4.1. Descrição

Toda resposta válida é formatada como JSON.

{
“rows”: “value”,
“pages”: “value”,
“ṕage: “value”,
“service”:
[
{
“field1”: “value”,
“field2”: “value”,
“field3”: []
},
{...}
]}

2.4.2. HTTP Status Codes

[Link]. Códigos de Sucesso

● 200 OK -​ Requisição bem sucedida. Resposta inclusa.

● 204 No Content​ - Requisição bem sucedida, mas sem
resposta inclusa.

6 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

[Link]. Códigos de Erro

● 400 Bad Request​ - Não foi possível processar a requisição.
● 401 Unauthorized​ - Autenticação não aceita ou não enviada.
● 403 Forbidden​ - Usuário não possui acesso a API.
● 404 Not Found​ - Recurso inexistente.
● 405 Method Not Allowed​ - Quando um método HTTP que
não é permitido para o usuário está sendo solicitado.
● 415 Unsupported Media Type​ - Se o content type incorreto
foi fornecido como parte da solicitação.
● 422 Unprocessable Entity​ - Usado para validação de erros.
● 429 Too Many Requests​ - Quando o pedido é rejeitado
devido ao número excedido de acessos ao serviço.
● 500, 501, 502, etc​ - Um erro interno ocorreu no servidor.

[Link]. Erros

Toda série de erros 400 serão retornadas com um JSON no corpo e

“Content Type” como “application/json”.

{
“message”: “Not Found”
}

Erros 500 não retornarão um JSON no corpo.

[Link]. Validação dos Erros

No caso de erros de validação (422), um JSON será retornado com a

crítica do erro

{
“message”: “Validation Failed”,
“errors”: [
{
“message”:”Field is not valid”
},
{...}
]
}

7 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

2.4.3. Paginação

O total de registros retornados poderá ser de até 500 por página.

Toda chamada enviada para a API receberá no retorno a quantidade total de
registros, páginas disponíveis e a página atual.

{
“rows”:”1000”,
“pages”: “2”,
“page”:”1”,[...]
}

8 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

2.5. API de Resgates

2.5.1. Descrição

Serviço que lista os resgates realizados no clube solicitado.

Campos disponíveis no serviço:

Campo Tipo Notas

id integer Id do Resgate

beneficio_id integer Id do Benefício

beneficio_titulo string Título do Benefício

categoria_id integer ID da categoria do Benefício

categoria_titulo string Título da Categoria

usuario_id integer ID do Usuário que efetuou o resgate

usuario_nome string Nome do Usuário

usuario_email string Email do Usuário

datahora datetime Data e Hora do resgate YYYY-MM-DD

hh:mm:ss

parceiro_id integer Id do parceiro fornecedor do benefício

parceiro_titulo string Nome do parceiro

2.5.2. Filtros Aceitos

● ID: Identificação do resgate.

GET /api/redeem/1001

● Período: start, end. Formato: YYYY-MM-DD

GET /api/redeem?start=2017-01-01&end=2017-10-10

9 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

● Campos desejados: fields

GET /api/redeem?fields=datahora,usuario_nome,parceiro_nome

Exemplo de Chamada

GET /api/redeem?start=2017-08-20

200 OK
Content-Type: application/json

[
{
“rows”:”2000”,
“pages”:”4”,
“page”: “1”,
“rescues”: [
{“id”:”2121”,
“beneficio_id”:”11”,
“beneficio_titulo”: “10% de desconto na assinatura”,
“categoria_id”: “1”,
“categoria_titulo”:”Jornais e Revistas”,
“usuario_id”:”1001”,
“usuario_nome”: “Jose da Silva”,
“usuario_email”: “​josedasilva@[Link]​”,
“datahora”: “2017-09-01 [Link]”,
“parceiro_id”: “1929”,
“parceiro_titulo” “Revistas Proxy Media” },
{...}
]
}
]

10 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

2.6. API de Usuários

2.6.1. Descrição

Serviço que lista os usuários do clube solicitado.

Campos disponíveis no serviço:

Campo Tipo Notas

id integer Id do usuário

nome string Nome completo

email string E-mail de acesso ao clube

telefone string Telefone Fixo

celular string Número do celular

cpf string CPF

endereco string Endereço do usuário

numero string Número do endereço

complemento string Complemento do endereço

bairro string Bairro

cidade string Cidade

uf string Estado

cep string Código Postal

sexo string M: Masculino; F: Feminino

nascimento date Data de Nascimento YYYY-MM-DD

tempo_cadastro datetime Data do Cadastro YYYY-MM-DD hh:mm:ss

ativo integer 0: Inativo; 1: Ativo

travas array Nome e valor da trava

11 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

2.6.2. Filtros Aceitos

● ID: Identificação do usuário.

GET /api/users/212

● Período: start, end. Formato: YYYY-MM-DD

GET /api/users?start=2017-01-01&end=2017-10-10

● Campos desejados: fields

GET /api/users?fields=datahora,usuario_nome,parceiro_nome

● Travas do clube: locks

GET /api/users?locks

12 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

Exemplo de Chamada

GET /api/users?locks&fields=id,nome,email,celular,sexo

200 OK
Content-Type: application/json

[
{
“rows”:”2”,
“pages”: “1”,
“page”:”1”,
“users”: [
{
“travas”:[“key”:”1”,”value”:”98euiewdhdh”],
“id”:”10001”,
“nome”:”Jose da Silva”,
“email”: “​josedasilva@[Link]​”,
“celular”: “11987654321”,
“sexo”:”M”},
{...}
]
}
]

2.7. API de Benefícios

2.7.1 Descrição

Serviço que lista os benefícios do clube solicitado.

Campos disponíveis no serviço:

Campo Tipo Notas

id integer Id do benefício

parceiro_id integer Id do parceiro

marca_id integer Id d marca

13 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

tamanho_id integer Id do tamanho

mod_tamanho_i integer Id do módulo de tamanho

d

titulo string Título do benefício

iframe bool Se o benefício deve abrir em um iframe

inicio datetime Início da validade do benefício

YYYY-MM-DD hh:mm:ss

fim datetime Fim da validade do benefício YYYY-MM-DD

hh:mm:ss

infinito bool Se deve desconsiderar a validade do

beneficio

cupom string Cupom do benefício

link string Link para a página do benefício

valor string Texto com a chamada do benefício

preco_de string Texto com o preço antes do benefício

preco_por string Texto com preço após o benefício

preco_parcela string Parcela do benefício

ordem integer Ordem em que aparece o benefício

responsavel string Email ou pessoa responsável pelo benefício

endereco array enderecos do benefício, quando loja física

latitude string Valor para geolocalização

longitude string valor para geolocalização

ativo bool 0: inativo, 1: ativo

label string Não utilizado

parceiro object Objeto com os dados do parceiro descrito

abaixo

imagens array Array com os objetos de imagens do

benefício

opcionais array Array com os opcionais relacionados ao

14 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

benefício

categoria array array com os objetos de categoria

relacionadas ao benefício

marca array array com os objetos de marca

tamanho array array com o objeto de tamanho

url string url do beneficio no clubeben

2.7.2. Filtros Aceitos

● ID: id, Id do benefício;

GET /api/beneficios?id=1234

● Termo: busca. Formato: texto, busca textual em campos do benefício.

GET /api/beneficios?busca=10off

● Categoria: categoria_id, Formato: int, busca para uma categoria

específica

GET /api/beneficios?categoria_id=123

● Parceiros: parceiro_id, Formato: int, busca por um parceiro específico

GET /api/beneficios?parceiro_id=123

● Região: regiao_id, Formato: int, busca para uma região específica

GET /api/beneficios?regiao_id=123

● Paginação: pagination, Formato: bool (true, false),Se deve trazer os

parâmetros de paginação

GET /api/beneficios?pagination=true

15 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

Exemplo de Chamada

GET /api/beneficios?pagination=true

200 OK
Content-Type: application/json

{"total":"72",
"rpp":10,
"offset":0,
"pages":8,
"beneficios":[{"id":"9841","parceiro_id":"2567","marca_id":"0","tamanho_id":"
0","mod_tamanho_id":"0","titulo":"Dia
dos namorados","iframe":"0","descricao":"<p><strong>Dia dos namorados
L'Occitane<\/strong><\/p>\n<p>Ganhe 1 mimo \u00e0 sua escolha nas
compras acima de R$180 usando o cupom
<strong>NAMORADOS180<\/strong> .<\/p>\n<p>10% de desconto usando
o cupom <strong>PARCEIRO10<\/strong>.<\/p>\n<p>N\u00e3o cumulativo
com outras promo\u00e7\u00f5es. V\u00e1lido somente para
produtos.<\/p>","inicio":"2020-06-04 [Link]","fim":"2020-06-12
[Link]","infinito":"0","cupom":"","link":"https:\/\/[Link]
[Link]\/clube-ben","valor":"10% OFF +
Brinde","preco_de":"","preco_por":"","preco_parcela":"","ordem":"150","resp
onsavel":"b2b@[Link]","endereco":null,"latitude":null,"longitud
e":null,"ativo":"1","label":"","parceiro":{"id":"2567","titulo":"L'Occitane En
Provence","url":"https:\/\/[Link]\/","slug":"loccitaneenprovence","sl
ug_amigavel":null,"ativo":"1","imagem":"https:\/\/[Link].n
et\/parceiros\/[Link]","enderecos":[]},"i
magens":[{"id":"14698","beneficio_id":"9841","imagem":"https:\/\/ddrxgn8uci
[Link]\/beneficios\/[Link]","la
rgura":"280","altura":"280","ratio":"1.0000"}],"opcionais":[],"categoria":[{"titul
o":"Shopping","id":"4","label":"Shopping","slug":"shopping","system":"clubeb
en","icon":"beneficios_categorias\/[Link]"},{"titulo":"Bem-estar",
"id":"9","label":"Bem-estar","slug":"saude","system":"clubeben","icon":"benef
icios_categorias\/[Link]"},{"titulo":"Beleza e
Est\u00e9tica","id":"19","label":"Beleza e
Est\u00e9tica","slug":"beleza_eduk","system":"clubeben","icon":"beneficios
_categorias\/mapa-beleza_eduk.png"},{"titulo":"Compras e
Presentes","id":"56","label":"Compras e
Presentes","slug":"compras_presentes","system":"clubeben","icon":"benefic
ios_categorias\/[Link]"},{"titulo":"Bem-estar e
Sa\u00fade","id":"65","label":"Bem-estar e
Sa\u00fade","slug":"bemestar_saude","system":"clubeben","icon":"beneficio
s_categorias\/[Link]"}],"marca":[],"tamanho":[],"url":"\/loccitaneenproven
ce\/c8J-dia-dos-namorados","enderecos":[]}, … ]}

16 de 17
Clube Ben Versão 1.0

API de Integração 13/09/2017

17 de 17