Loy API · piloto com parceiros Documentação para quem desenvolve a integração.

Novidades

O que mudou na Loy API, da mais recente para a mais antiga.

Outubro de 2026

Recompensa por indicação

  • Recompensas ganham a origem referral (Indique um amigo). Trate valores de origin que você não conhece como genéricos.
Outubro de 2026

Documentação mais prática

  • Novo guia Fluxo no caixa: do cliente ao resgate, sem travar a venda.
  • Cada endpoint da referência traz a requisição pronta para colar no terminal e exemplos com dados realistas.
  • Contrato OpenAPI para download, para Postman, Insomnia e assistentes de código.
Outubro de 2026

Webhooks

  • Eventos customer.created, visit.recorded, reward.earned e reward.redeemed, assinados com HMAC.
  • Cadastro, teste (ping), reativação e remoção de endereços em /webhook_endpoints.
  • Liberação gradual no piloto. Veja Webhooks.
Outubro de 2026

Recompensas e resgate

  • GET /rewards/lookup?code=: encontra a recompensa pelo código que o cliente mostra no caixa.
  • POST /rewards/{id}/redeem (com Idempotency-Key): resgata; segundo resgate recebe 409, recompensa vencida recebe 422.
  • GET /rewards/{id} e GET /customers/{id}/rewards (filtro por status).
Outubro de 2026

Visitas

  • POST /visits (com Idempotency-Key): registra uma visita paga; a resposta traz as recompensas conquistadas e o progresso atualizado.
  • GET /visits/{id} e GET /customers/{id}/visits.
  • Pontos só entram por visita — mesmas regras do app.
  • A empresa pode escolher se o Loy avisa o cliente final ou se o seu sistema faz isso.
Outubro de 2026

Clientes, saldo e catálogo

  • Cadastro (POST /customers, com Idempotency-Key), consulta, atualização e busca por external_id, e-mail ou telefone.
  • GET /customers/{id}/balance: pontos em cada programa e recompensas disponíveis.
  • GET /services e GET /loyalty_programs.
  • IDs opacos (cus_, svc_, lp_), paginação por cursor e erros com type, param e errors.
Outubro de 2026

Início do piloto

  • Autenticação por chave de API no cabeçalho Authorization.
  • GET /me: empresa da chave, escopos, limites e uso do mês (não conta na quota).
  • Limites de velocidade e quota mensal com cabeçalhos padrão e Retry-After.

O acesso é liberado pela equipe do Loy. Pedir acesso.