HUB de Promoções 2.0

O Hub 2.0 é uma camada de integração que é composta por um conjunto de APIs cuja finalidade é realizar o cadastro de promoções, condições para cada promoções, prêmios e ganhadores de promoções. Além disso, é possível realizar a gestão das promoções como alterações e consultas.

Feito para:  Estabelecimentos ComerciaisEmissores

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.