Fluxo no caixa

O roteiro de uma integração completa com sistema de vendas, PDV ou agenda: identificar o cliente, registrar a venda, mostrar o progresso e aceitar a recompensa — sem travar o atendimento.

1. 1

   Identificar

   acha ou cadastra o cliente
2. 2

   Registrar

   a venda vira visita e pontos
3. 3

   Mostrar

   quanto falta para o benefício
4. 4

   Resgatar

   o código que o cliente mostra

1. Identifique o cliente pelo ID do seu sistema

Use o código do cliente no seu sistema como external_id. Assim você não precisa guardar o ID do Loy: busca por ele e, se não existir, cadastra.

curl "https://loynow.com/api/v1/customers?external_id=ERP-991" \
  -H "Authorization: Bearer $LOY_API_KEY"

Se data vier vazio, cadastre — com uma Idempotency-Key derivada do seu cliente, para que uma repetição não duplique:

curl -X POST https://loynow.com/api/v1/customers \
  -H "Authorization: Bearer $LOY_API_KEY" \
  -H "Idempotency-Key: cliente-ERP-991" \
  -H "Content-Type: application/json" \
  -d '{"customer": {
        "name": "Ana Souza",
        "phone": "48999990000",
        "external_id": "ERP-991"
      }}'

Se dois caixas cadastrarem o mesmo cliente ao mesmo tempo, um deles recebe 409 customer_external_id_taken: busque de novo pelo external_id e siga.

2. Registre a venda como visita

Quando a venda for paga, registre a visita. Use o número da venda na Idempotency-Key: se a rede cair e você reenviar, o Loy devolve a mesma resposta e não soma pontos duas vezes.

curl -X POST https://loynow.com/api/v1/visits \
  -H "Authorization: Bearer $LOY_API_KEY" \
  -H "Idempotency-Key: venda-8812" \
  -H "Content-Type: application/json" \
  -d '{"visit": {
        "customer_id": "cus_4fRk9P2xQ",
        "service_id": "svc_8Lm3Tq1Z",
        "price": "49.90",
        "notes": "Pedido #8812"
      }}'

Os service_id vêm de GET /services; guarde a correspondência com os produtos ou serviços do seu sistema. Sem price ou points, valem os do serviço cadastrado no Loy.

3. Mostre o progresso no comprovante ou na tela

A resposta da visita já traz o que mostrar ao cliente — sem outra chamada:

{
  "id": "vis_7Hc2Wn5R",
  "customer_id": "cus_4fRk9P2xQ",
  "paid": true,
  "…": "…",
  "loyalty": {
    "rewards_earned": [],
    "programs": [
      {
        "program_id": "lp_5Tz1Kw9M",
        "points": 3,
        "required": 10,
        "remaining": 7
      }
    ]
  }
}

Se rewards_earned vier preenchido, o cliente acabou de ganhar um benefício: mostre o description e o code. Por padrão o Loy também avisa o cliente, como no app; se a empresa preferir que só o seu sistema avise, isso é combinado na liberação do acesso.

4. Aceite a recompensa no caixa

O cliente mostra o código no celular. Consulte, confira o status e resgate:

curl "https://loynow.com/api/v1/rewards/lookup?code=LOY-8KD2QZ" \
  -H "Authorization: Bearer $LOY_API_KEY"

# status "available"? Entregue o benefício e resgate:
curl -X POST https://loynow.com/api/v1/rewards/rwd_2Pq8Xs4K/redeem \
  -H "Authorization: Bearer $LOY_API_KEY" \
  -H "Idempotency-Key: resgate-LOY-8KD2QZ"

Não trave a venda se o Loy não responder

A fidelidade nunca deve impedir o caixa de fechar uma venda. O padrão recomendado:

• Espere no máximo 5 segundos. Passou disso, conclua a venda normalmente.
• Guarde a chamada numa fila do seu sistema e reenvie depois, com a mesma Idempotency-Key — ela vale por 48 horas.
• Reenvie com espera crescente (por exemplo 30 s, 2 min, 10 min) em 429, 500, 503 e falhas de rede. Em 429, respeite o Retry-After.
• Não reenvie respostas 4xx de dados (404, 422): corrija o dado antes.
• O resgate é a exceção: só entregue o benefício depois do 200.

Quer saber o que acontece sem consultar?

Com webhooks, o Loy avisa o seu sistema quando um cliente ganha ou usa uma recompensa — inclusive as que acontecem pelo app, fora do seu caixa.