# Níveis de integração

Cupom, Venda e Completo, com o fluxo de cada um.

Cada nível acrescenta chamadas ao anterior. Subir de nível nunca reescreve o que já funciona.

## Nível 1 · Cupom (Em breve)

Para PDV sem rede no caixa: o QR assinado leva a venda ao GIRO pelo celular do cliente. Exige PDV com servidor ou instalado com armazenamento protegido; PDV de navegador usa o nível 2.

### O que o PDV usa

- Sem chamada de API no caixa

### Fluxo: Cupom

Para PDV sem rede no caixa. O PDV não chama a API na venda. Se a mesma venda chegar também pela API, vale a venda da API.

1. Seu PDV: Fecha a venda sem chamar a API. O caixa funciona mesmo sem internet.
2. Seu PDV: Gera um QR assinado. O PDV assina o QR com o segredo de assinatura da loja, diferente do token: loja, venda, valor e data.
3. Seu PDV: Imprime o QR no cupom. O QR sai no cupom, como no nível Venda.
4. Cliente: Escaneia e informa o telefone. O cliente abre o QR no celular.
5. API do GIRO: Confere e credita. O GIRO confere a assinatura, o uso único, a validade de 7 dias, o teto por QR e o limite diário da loja, e credita o selo.

## Nível 2 · Venda (Disponível)

O PDV avisa o GIRO de cada venda e imprime a imagem do GIRO no cupom. Uma chamada por venda, sem guardar segredo de assinatura.

### O que o PDV usa

- GET /v1/program
- POST /v1/sales
- POST /v1/sales/{external_id}/cancel
- GET /v1/sales/{external_id}
- GET /v1/connection

### Fluxo: Cliente identificado

O cliente já aceitou o GIRO e informa o telefone no caixa. O selo entra na hora.

1. Cliente: Informa o telefone. No caixa, o cliente diz o telefone. O campo é opcional.
2. Seu PDV: Fecha a venda e chama a API. O PDV envia a chave da venda, o total, a hora e o telefone. (POST /v1/sales)
3. API do GIRO: Aplica a regra da loja. O GIRO confere o programa, o valor mínimo e o teto, e acha o cliente pelo telefone.
4. API do GIRO: Credita o selo e responde. A resposta traz o crédito efetivado, a cartela e o bloco do GIRO, em texto e em imagem. (credit.state = efetivado)
5. Seu PDV: Imprime o bloco do GIRO. O PDV imprime receipt.lines ou receipt.image no fim do cupom. (receipt.lines · receipt.image)
6. Cliente: Vê o progresso no cupom. O cupom mostra quantos selos faltam para a recompensa.

### Fluxo: Cliente não identificado

O cliente não informa o telefone ou ainda não aceitou o GIRO. O selo fica guardado até o cliente ativar pelo QR.

1. Cliente: Compra sem se identificar. O cliente não informa o telefone, ou o telefone ainda não tem aceite no GIRO.
2. Seu PDV: Fecha a venda e chama a API. O PDV envia a venda do mesmo jeito. Não há fluxo separado. (POST /v1/sales)
3. API do GIRO: Guarda o selo como pendente. O GIRO cria um QR de ativação, com validade definida pela loja. (credit.state = pendente)
4. API do GIRO: Responde com o QR. A resposta traz o claim e o bloco do GIRO com o QR de ativação e o código curto. (claim · receipt.qr · receipt.short_code)
5. Seu PDV: Imprime o QR no cupom. O PDV imprime o bloco do GIRO. No texto, o QR entra depois da primeira linha; na imagem, já vem desenhado. (receipt.lines · receipt.image)
6. Cliente: Escaneia e ativa. O cliente abre o QR no celular, informa o telefone e aceita o programa. O GIRO credita o selo.

### Fluxo: Cartela completa

A venda completa a cartela do cliente identificado. O cupom avisa o prêmio, e o cliente pede o prêmio no caixa.

1. Cliente: Informa o telefone. O cliente se identifica no caixa.
2. Seu PDV: Fecha a venda e chama a API. O PDV envia a venda como sempre. (POST /v1/sales)
3. API do GIRO: Completa a cartela. O selo desta venda completa a cartela. A resposta traz card.completed_now = true. (card.completed_now)
4. Seu PDV: Imprime o bloco do GIRO. O cupom avisa o prêmio que o cliente ganhou. (receipt.image)
5. Cliente: Pede o prêmio. O cliente pede o prêmio no caixa, agora ou numa próxima visita.

### Fluxo: Cancelamento

A venda foi desfeita no PDV. O GIRO desfaz o selo, mesmo que o cancelamento chegue antes da venda.

1. Seu PDV: Cancela a venda no PDV. O operador desfaz a venda no caixa.
2. Seu PDV: Avisa o GIRO. O PDV usa a mesma chave da venda. (POST /v1/sales/{external_id}/cancel)
3. API do GIRO: Desfaz o crédito. Se a venda já chegou, o GIRO tira o selo. Se ainda não chegou, guarda o cancelamento.
4. API do GIRO: Fecha o ciclo. Uma venda que chega depois de cancelada já nasce cancelada, sem selo e sem cupom. (status = cancelada)

## Nível 3 · Completo (Em breve)

O nível 2 mais a identificação do cliente e o resgate do prêmio no caixa, com o resgate na nota fiscal.

### O que o PDV usa

- Tudo do nível 2
- Consulta de cliente e carteira pelo Open Delivery (Customer e Loyalty)
- Resgate em duas fases (extensão do GIRO): reservar e confirmar
- Na nota: pagamento de fidelidade (tPag 19) com o ID do resgate

### Fluxo: Completo

Além da venda, o caixa identifica o cliente e troca a recompensa na hora.

1. Cliente: Informa o telefone. O cliente se identifica no caixa.
2. Seu PDV: Consulta o cliente. O PDV consulta o cliente e a carteira pelo Open Delivery (Customer e Loyalty): selos e prêmio disponível. (Open Delivery Loyalty)
3. Cliente: Pede a recompensa. O cliente quer usar a recompensa nesta compra.
4. Seu PDV: Reserva o resgate. O PDV cria a referência do resgate e reserva a recompensa.
5. API do GIRO: Segura a recompensa. A recompensa fica reservada, sem ser gasta, até a confirmação.
6. Seu PDV: Registra a venda e confirma. Com a venda paga, o PDV confirma o resgate. Na nota, o resgate sai como pagamento de fidelidade (tPag 19), com o ID do resgate. Se a venda cai, o PDV cancela a reserva.

Fonte: https://developers.giro.app.br/niveis.html