01
Introdução
02
Cadastro de campanhas
03
Cadastro de campanhas para Card Issuer e Merchant
04
Apuração da Campanha
05
Cadastro de Condições
Cadastro de Blacklist e Whitelist
06
Cadastro de Prêmios
07
Cadastro de Ganhadores
08
Consulta de Prêmios
09
Referências
Para gerenciar sua campanha ou fazer consultas na HUB de Promoções da Elo , é necessário ter um usuário cadastrado na plataforma de APIs e estar registrado como Card Issuer ou Merchant.
Em todas as chamadas descritas é necessário informar o client_id do aplicativo e, dependendo da integração, também o access_token obtido no login da plataforma de APIs da Elo no header da requisição.
A API HUB de Promoções segue a arquitetura REST e, no final desta documentação, há a seção de Referências com o Swagger desta API. Os possíveis base paths são:
Homologação:
https://hml-api.elo.com.br/hub-promotion/v2
Produção:
https://api.elo.com.br/hub-promotion/v2
O cadastro de campanhas consiste em receber as seguintes informações relacionadas a uma campanha que será realizada na Elo.
Nome
Titulo
Tipo
T&C Terms and Conditions (Termos e condições) utilizado pela API de User. Deve ser um Id.
Vigência Início e fim de vigência da campanha.
Apuração Frequência de apuração da campanha.
Status [ DRAFT, ACTIVE, INACTIVE ]
Origem Qual área da Elo originou a campanhas
É possível cadastrar, alterar, excluir, editar e consultar uma campanha. Os status das campanhas devem ser controlados da seguinte forma:
Não deve ser permitido alterar uma campanha com o status ACTIVE.
Exemplo do body da chamada POST /partners/me/promotions
:
{
"title": "ELO TEST QA",
"promotionTypeId":1,
"description": "ELO TEST QA",
"status": "DRAFT",
"rankable": true,
"agreementTermId": "58f5b6a4-8cc3-46f2-864e-802517fd18b0",
"startValidity": "2020-01-28T14:10:42.520Z",
"endValidity": "2020-01-28T14:10:42.520Z",
"frequency": "string",
"type": "CASHBACK",
"inputType": "VOX",
"requiredInfo": [
"string"
],
"restrictedUsers": true,
"validityRequired": true,
"slug": "teste",
"optInRequired": true,
"budget": 22.22
}
O cadastramento de promoções pelas entidades da plataforma de APIs da Elo, sendo elas Card Issuer ou Merchant deve ser feito através da criação de um usuário (createUser) e associação a algum tipo de usuário da plataforma. Para saber mais sobre a criação e associação do usuário, acesse a documentação do Cadastro do Portador.
Não será permitido o cadastramento de promoções para usuários do tipo cardHolder.
Existem 2 tipos de campanha: PUBLIC e PRIVATE.
PUBLIC – Todos podem ver, somente a Elo e o parceiro dono podem alterar.
PRIVATE – Somente a Elo e o parceiro dono podem ver e alterar.
A apuração da campanha pode ser feita através condições cadastradas pelo parceiro (na próxima seção, tem mais informações sobre), mas para entender este cadastro é preciso conhecer o funcionamento do motor de apuração. Atualmente, a Elo utiliza o Linked offer e o base path para acessá-lo é:
https://dev-api.elo.com.br/linked-offers/v1
A primeira coisa que é preciso fazer é adquirir o promotionTypeId
, ou seja, o identificador do tipo da campanha que será apurada. É possível listar todos os tipos através da chamada GET /promotion-types
, enviando o client_id
como cabeçalho da requisição ao motor. Exemplo de retorno:
[
{
"promotionTypeId": 6914954,
"promotionTypeName": "deserunt consequat qui anim Excepteur",
"promotionTypeDescription": "Ut labore id",
"insertDateTime": "2003-08-30T22:15:18.272Z",
"prizeType": {
"prizeTypeId": -74830975,
"prizeTypeName": "reprehenderit",
"prizeTypeDescription": "magna ut"
}
},
{
"promotionTypeId": 96958761,
"promotionTypeName": "id Ut mollit dolore",
"promotionTypeDescription": "amet",
"insertDateTime": "1954-11-05T07:11:15.807Z",
"prizeType": {
"prizeTypeId": -12807611,
"prizeTypeName": "adipisicing reprehenderit",
"prizeTypeDescription": "ex veniam elit incididunt"
}
}
]
Como descrito na próxima seção, uma condição tem um KeyId
, um KeyType
, um operationId
e values
. Para adquirir estas informações, é necessário acessar a rota GET /promotion-types/{promotionTypeId}/fields
do motor, enviando seu client_id
nos headers da requisição. Exemplo de retorno:
[
{
"fieldId": 89002749,
"fieldName": "qui consequat",
"fieldDescription": "amet nulla ut aute laboris",
"fieldType": "nisi",
"insertDateTime": "2013-09-12T22:52:55.104Z",
"activeDateTime": "1979-03-03T11:36:21.787Z",
"origin": "quis",
"location": "non aute commodo",
"linkedFields": [
{
"value": "<Circular reference to #/components/schemas/Fields detected>"
},
{
"value": "<Circular reference to #/components/schemas/Fields detected>"
}
],
"operators": [
{
"operatorId": 41028278,
"operatorName": "eu",
"operatorSymbol": "Lorem cupidatat in commodo",
"insertDateTime": "1962-03-06T15:42:44.566Z"
},
{
"operatorId": 4777555,
"operatorName": "ullamco labore Excepteur",
"operatorSymbol": "id",
"insertDateTime": "2018-03-17T05:03:39.547Z"
}
]
}
]
No retorno desta chamada, os campos fieldId
e fieldDataType
são correspondentes, respectivamente, ao KeyId
e ao KeyType
. No field
retornado, há os operators
e é onde encontramos o operatorId
. Com estes dados em mãos é possível efetuar o cadastro de condições
As Campanhas são definidas por Regras. Uma campanha pode ter N regras e são identificadas por atributos específicos como:
KeyId: Identificador único da regra.
KeyType: Tipo da regra que está sendo cadastrada, pode ser Numérico, String ou outros.
operationId: Identificador do operador que define a regra. Este id faz referência ao operador, que pode ser < (menor), > (maior), = (igual), entre outros.
values: Lista de valores que serão aplicados à regra.
Exemplo de body da requisição para o cadastro de condições, POST /partners/me/promotions/{promotionId}/conditions
:
{
"keyId": "2",
"operationId": "2",
"startValidity": "2020-01-20T12:55:44.817-03:00",
"endValidity": "2020-01-21T12:55:44.817-03:00",
"values": [
"100,00",
"200,00"
],
"slug": "slug"
}
O conceito de blacklist e whitelist se faz necessário devido ao requisito de inserir dados de usuário específicos que podem ( whitelist ) ou não ( blacklist ) participar de uma promoção. Para determinadas promoções da Elo, pode ser necessário cadastrar uma lista de CPFs, BINs, ou qualquer outra informação que possa distinguir a participação ou não em uma promoção.
Para resolver esse problema, vamos criar um novo recurso dentro de /conditions para identificar os valores de blacklist e whitelist. Devemos criar as seguinte operações:
POST /partners/me/promotions/{id}/condition/{conditionId}/value
GET /partners/me/promotions/{id}/condition/{conditionId}/value
GET /partners/me/promotions/{id}/condition/{conditionId}/value/{valueId}
DELETE /partners/me/promotions/{id}/condition/{conditionId}/value/{valueId}
O atributo value é um valor atributo ao conteúdo que pode ser permitido (blacklist) ou liberado (whitelist) de acordo as regras da promoção. Cada registro de value está diretamente relacionado a uma condition do tipo blacklist ou whitelist.
Pensando em um caso de uso onde há uma lista muito extensa, fica muito custoso enviar essa lista toda em apenas uma única requisição POST. Por esse motivo a elo permite gerenciar os values um por um através do recurso /value
. Os verbos disponíveis para este recurso foram listados acima
Exemplo de adição de uma condição com a chamada POST /partners/me/promotions/{id}/condition/{conditionId}/value
{
"value": "300,00"
}
As chamadas dos demais verbos do recurso /partners/me/promotions/{id}/condition/{conditionId}/value
não necessitam de um body na requisição.
O cadastro de prêmios consiste em receber os prêmios relacionados a uma campanha . Os prêmios podem variar por posição do ganhador da campanha, por exemplo, o primeiro ganhador/sorteado receberá um prêmio diferente do segundo ganhador/sorteado. Por esse motivo devemos receber as informações de prêmio juntamente com sua relevância de premiação. Para cadastrar um prêmio em uma campanha devemos receber as seguinte informações:
Id campanha
Descrição
Tipo
Exemplo de cadastro de prêmios passando o id da promoção com a chamada POST /partners/me/promotions/{id}/prizes
{
"name": "Jogada Feliz",
"description": "ganhou 3 prêmios de chocolate",
"prizeTypeId": 1,
"rank": "1",
"startValidity": "2020-01-21T12:55:44.817-03:00",
"endValidity": "2020-01-21T12:55:44.817-03:00",
"slug": "slug",
"status": "status",
"value": 132,
"precedenceOrder": 132
}
Para efetuar o cadastro de ganhadores para as campanhas, basta realizar uma chamada POST ao endpoint /partners/me/promotions/{id}/prizes/{prizeId}/winners
, passando o id da campanha, o id da premiação e no corpo da requsição passar as informações do vencedor.
Exemplo de body da chamada POST /partners/me/promotions/{id}/prizes/{prizeId}/winners
para adição de um ganhador:
{
"name": "name1",
"userId": "1732b7c7-b339-4c29-a984-f81e9a0108be",
"legalId": {
"cpf": "12345678910"
},
"slug": "slug1",
"cardSha256": "fcdb4b423f4e5283afa249d762ef6aef150e91fccd810d43e5e719d14512dec7"
}
GET promotions{id}/prizes
Incluir filtros para consultar as premiações diárias tendo como referência do atributo referenceDate (referencestartDate e referenceendDate ) e retornar aquelas que o atributo referenceDate está contido entre essas datas.
GET partners/me/promotions{id}/prizes
Incluir filtros para consultar as premiações diárias tendo como referência do atributo referenceDate (referencestartDate e referenceendDate )e retornar aquelas que o atributo referenceDate está contido entre essas datas.