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:

Copiarhttps://hml-api.elo.com.br/hub-promotion/v2

Produção:

Copiarhttps://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:

Copiar{
  "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 é:

Copiarhttps://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:

Copiar{
    "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 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

Copiar{
    "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:

Copiar{
  "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.