Convenções

IDs

Cada recurso tem um ID opaco com prefixo do tipo: cus_ (cliente), svc_ (serviço), lp_ (programa de fidelidade), vis_ (visita) e rwd_ (recompensa). Guarde o ID como texto e não tente interpretá-lo. Um ID de outra empresa, ou que não existe, recebe o mesmo 404.

Para ligar o cliente ao cadastro do seu sistema, envie external_id (até 128 caracteres: letras, números e . _ : -). Ele é único por empresa, e você pode buscar por ele em GET /customers?external_id=… sem guardar o ID do Loy.

Cadastro sem duplicar (idempotência)

POST /customers exige o cabeçalho Idempotency-Key: um valor único por tentativa de cadastro (por exemplo, um UUID gerado pelo seu sistema). Se a rede cair e você reenviar com a mesma chave e o mesmo corpo, o Loy devolve a resposta original, com Idempotent-Replayed: true, sem criar outro cliente e sem contar de novo na quota.

curl -X POST https://loynow.com/api/v1/customers \
  -H "Authorization: Bearer $LOY_API_KEY" \
  -H "Idempotency-Key: 6f1c2b8e-1d0a-4c55-9a3e-2f7e7c1b9d10" \
  -H "Content-Type: application/json" \
  -d '{"customer": {"name": "Ana Souza", "phone": "48999990000", "external_id": "ERP-991"}}'

• A mesma chave com outro corpo recebe 422 idempotency_key_reused.
• As chaves valem por 48 horas.
• O cliente precisa de nome e de e-mail ou telefone; data de nascimento é opcional (sem ela, o cliente não entra nas campanhas de aniversário).
• Cadastro pela API não envia e-mail de boas-vindas nem avisa a equipe da empresa — o seu sistema decide como falar com o cliente.

Visitas e pontos

• Pontos entram só por visita (POST /visits): não existe crédito ou débito avulso.
• price e points são opcionais; sem eles, valem o preço e os pontos do serviço.
• A visita também exige Idempotency-Key: reenviar a mesma visita não soma pontos de novo.
• Quem avisa o cliente final (e-mail do atendimento, recompensa conquistada, "falta pouco") é combinado com a empresa: o Loy avisa (padrão) ou o seu sistema avisa. Em qualquer caso, a recompensa é criada e a equipe da empresa é avisada.

Resgate no caixa

1. O cliente mostra o código (LOY-…); consulte com GET /rewards/lookup?code=.
2. Se status for available, resgate com POST /rewards/{id}/redeem e uma Idempotency-Key nova.
3. Entregue o benefício só depois da resposta 200. Se a rede cair, repita com a mesma chave: você recebe a resposta original, sem risco de resgate duplo.

Listas e paginação

Listas respondem neste formato, do mais antigo para o mais novo:

{
  "data": [
    "…"
  ],
  "has_more": true,
  "next_cursor": "cus_…"
}

Use limit (1 a 100, padrão 25) e, para a próxima página, starting_after com o next_cursor recebido.