Nova Nuvem de Recompensas

A Nuvem de Recompensas v2 chega com um endpoint mais estruturado, suporte a projeção de campos, novos atributos e uma resposta muito mais completa, organizada em alianças, grupos, categorias, regras e muito mais.

Mais flexibilidade, mais dados e mais controle sobre a experiência de resgate.

Comparativo de versões

Aspecto	GET /v1/prizes	GET /v2/clouds/{name}/prizes
Endpoint	`/prizes`	`/clouds/{name}/prizes`
Parâmetros	Apenas `faceValue` (filtro por valor)	filtro por `names` e projeção por `fields` + expansível
Estrutura de resposta	Lista simples de alianças e prêmios	Recompensas ricas com `alliance`, `group`, `subGroup`, `billing`, `rules`, `deliveryData`, `deliveryAddress` e mais.
Dados visuais	Não disponíveis	Ícone, foto, banner amplo com suporte a `srcset`
Cobrança (billing)	`price` e `processingFee` no nível do prêmio	Objeto `billing` dedicado e mais claro
Entrega	Apenas informações básicas	`deliveryData` (prazo, orientações), `deliveryAddress` (perguntas dinâmicas), `requiredMobile`
Regras	Não disponíveis	`rules` com mínimo/máximo e outras validações
Flexibilidade	Payload fixo	Resposta personalizável via `fields`

Impactos para sua integração

Mais contexto para o consumidor final: imagens, ícones e banners oficiais disponíveis.
Mais controle sobre performance: use fields para reduzir payloads.
Mais clareza na cobrança: billing estruturado com preço + taxa separados.
Preparado para expansão: categorias e métodos de entrega mais completos.

Exemplos de Requisição

Consulta de prizes utilizando projeção.

http

curl --request GET \
  --url https://api.minu.biz/v2/clouds/cloud/prizes?fields=name,title,faceValue,photo \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'

Consulta de prizes buscando por nome.

http

curl --request GET \
  --url https://api.minu.biz/v2/clouds/cloud/prizes?names=cupom-ifood-20,uber-desconto-r20,deezer-assinatura-semestral,bonus-r20 \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'

Exemplo de Resposta

json

[
  {
    "name": "cupom-ifood-20",
    "title": "Cupom iFood R$20",
    "description": "Cupom de desconto para utilizar no iFood.",
    "alliance": {
      "name": "ifood",
      "title": "iFood"
    },
    "group": {
      "name": "alimentacao",
      "title": "Alimentação",
      "subGroup": {
        "name": "delivery",
        "title": "Delivery"
      }
    },
    "faceValue": 20,
    "billing": {
      "price": 12,
      "processingFee": 0.5,
    },
    "requiredMobile": false,
    "icon": {
      "href": "https://cdn.minu.biz/icons/prize-icon.png",
      "srcset": "prize-icon.png 1x, prize-icon@1.5x.png 1.5x, prize-icon@2x.png 2x, prize-icon@3x.png 3x, prize-icon@4x.png 4x"
    },
    "wideBanner": {
      "href": "https://cdn.minu.biz/banners/wideBanner.png",
      "srcset": "wideBanner.png 1x, wideBanner@1.5x.png 1.5x, wideBanner@2x.png 2x, wideBanner@3x.png 3x, wideBanner@4x.png 4x"
    },
    "photo": {
      "href": "https://cdn.minu.biz/photos/prize-photo.png",
      "srcset": "prize-photo.png 1x, prize-photo@1.5x.png 1.5x, prize-photo@2x.png 2x, prize-photo@3x.png 3x, prize-photo@4x.png 4x"
    },
    "deliveryData": {
      "deadline": "Até 24 horas",
      "guideline": "O cupom será enviado por e-mail cadastrado."
    },
    "rules": [
      { "name": "quantidade_minima", "value": [1] },
      { "name": "quantidade_maxima", "value": [10] }
    ],
    "deliveryAddress": {
      "questions": [
        {
          "name": "email",
          "text": "Informe o e-mail para entrega do cupom",
          "required": true,
          "field": "email",
          "example": "usuario@email.com"
        }
      ]
    }
  }
]

Notas de Migração

Se você já possui integração com a Nuvem de Recompensas (v1), aqui estão os principais pontos para adaptar sua implementação:

Na v1	Agora na v2
Endpoint `/prizes`	Endpoint `/clouds/{name}/prizes`
Filtro por `faceValue` via query string	Filtro por `names`, mas agora você também pode projetar os campos desejados via `fields`
Propriedades de resposta em nível de aliança + prêmios	Estrutura detalhada com `alliance`, `group`, `subGroup` e `billing`
`price` e `processingFee` diretamente no prêmio	Agora dentro de `billing.price` e `billing.processingFee`
Sem suporte a imagens	Recompensas contam com `icon`, `wideBanner` e `photo`
Sem dados de entrega	Novos campos `deliveryData`, `deliveryAddress` e `requiredMobile`
Sem detalhes sobre regras	Campo `rules` permite visualizar restrições (ex: quantidade mínima/máxima)

Recomendações

Atualize suas integrações para consumir o novo endpoint /v2/clouds/{name}/prizes.
Ajuste seus mapeamentos para utilizar o objeto billing.
Se sua aplicação exibe imagens de recompensas, utilize as novas propriedades icon, wideBanner e photo.
Considere usar o parâmetro fields para otimizar as respostas da API conforme sua necessidade e caso de uso.

Aviso

Importante: para utilizar a nova rota /v2, é necessário solicitar novas credenciais de acesso. Para mais informações sobre credenciais, entre em contato com nossa Equipe de suporte.

Conclusão

A nova Nuvem de Recompensas traz:

Endpoint mais poderoso
Payload mais rico e organizado
Suporte a projeções e performance otimizada
Dados visuais e de entrega mais completos

Essa evolução oferece uma melhor experiência, rica e segura para empresas que desejam encantar seus consumidores.

Nova Nuvem de Recompensas ​

Comparativo de versões ​

Impactos para sua integração ​

Exemplos de Requisição ​

Exemplo de Resposta ​

Notas de Migração ​

Recomendações ​

Conclusão ​