# Guias

Do início rápido à homologação.

- [Início rápido](#inicio)
- [Experiência no caixa](#caixa)
- [Cupom e QR](#cupom)
- [Cliente e consentimento](#cliente)
- [Token no PDV do balcão](#token-balcao)
- [Autenticação](#auth)
- [Idempotência e repetição](#idem)
- [Erros e limites](#erros)
- [Testes no sandbox](#testes)
- [Conectar uma loja](#loja)
- [Ativação e desligamento](#corte)
- [Open Delivery](#od)
- [Homologação](#homolog)
- [Histórico de mudanças](#changelog)

## Início rápido

Do cadastro à primeira venda no sandbox, em 15 minutos.

Prefere usar um agente de código? Use o prompt de integração da página MCP do desenvolvedor.

1. Crie a conta. O sandbox abre na hora, com uma loja de teste e um token de teste.
2. Guarde o endereço do sandbox em GIRO_API e o token em GIRO_TOKEN.
3. Leia o programa da loja de teste com GET /v1/program.
4. Registre uma venda com POST /v1/sales e imprima a imagem de receipt.image no fim do cupom.
5. Envie o mesmo pedido de novo, com a mesma Idempotency-Key. A resposta é a mesma, e nenhum selo novo é creditado.

```bash
curl "$GIRO_API/v1/program" \
  -H "Authorization: Bearer $GIRO_TOKEN"
```

## Experiência no caixa

Quando e como o operador pede o telefone, e o que o caixa mostra depois.

A taxa de cliente identificado nasce no caixa. Use o mesmo momento e o mesmo texto em todo PDV: o cliente reconhece o GIRO em qualquer loja.

Peça o telefone antes do pagamento, nunca depois de imprimir o cupom. Depois do cupom, o selo da venda já foi decidido.

O telefone é opcional. O caixa sempre oferece "Seguir sem telefone", e a venda nunca espera pelo GIRO.

1. Antes do pagamento, o caixa mostra: "O cliente quer juntar selos? Peça o telefone."
2. O operador digita o telefone e toca em "Confirmar", ou toca em "Seguir sem telefone".
3. Depois da venda, o caixa mostra o resultado por 3 segundos: "Selo creditado" ou "Selo pendente: o cliente ativa pelo QR do cupom".
4. O cupom sai com a imagem do GIRO no fim.

## Cupom e QR

Como imprimir o bloco do GIRO. A imagem é o padrão e o recomendado.

A resposta da venda traz o bloco do GIRO no formato pedido em receipt.format: "image" (padrão e recomendado) ou "text".

Imagem (recomendado): receipt.image é um PNG em preto e branco, com a cartela desenhada e, quando há, o QR. Imprima a imagem no fim do cupom, sem redimensionar. Na bobina de 80 mm, a imagem é horizontal; na de 58 mm, vertical, como na maquininha.

Informe a largura em receipt.width: 32 colunas na bobina de 58 mm, 42 ou 48 na de 80 mm. O padrão é 48. A imagem sai na largura em pontos: 384, 512 ou 576.

Texto: use só se a impressora não imprime imagem. Peça receipt.format = "text" e informe receipt.charset: "ascii" (padrão) ou "unicode". Imprima receipt.lines na ordem, centralizadas, sem mudar o texto. Quando há receipt.qr, imprima o QR logo depois da primeira linha. Se a impressora não imprime QR, a linha com receipt.short_code já leva o código de ativação.

O cupom mostra o saldo no momento da venda (snapshot_at). A reimpressão devolve o mesmo cupom. Para o saldo de agora, consulte à parte.

Se o seu PDV envia a venda depois, pelo servidor, ou se o GIRO não responde a tempo, a venda segue sem esperar: imprima o QR local no formato /m/{código público da loja}/{chave da venda}?v={valor em centavos}. O código público da loja vem em GET /v1/program. O selo chega quando a venda chega ao GIRO.

Quando receipt é null, não imprima nada do GIRO. Isso acontece na venda sem benefício e quando o selo fica retido (credit.state = retido), porque o selo retido pode não ser creditado.

```bash
# Imagem (recomendado): imagem rasterizada em ESC/POS (GS v 0)
1D 76 30 00 xL xH yL yH <pontos>  # xL xH = largura em bytes; 1 bit por ponto

# Texto: QR em ESC/POS (GS ( k), dados = receipt.qr
1D 28 6B 04 00 31 41 32 00        # modelo 2
1D 28 6B 03 00 31 43 06           # módulo 6
1D 28 6B 03 00 31 45 31           # correção de erro M
1D 28 6B pL pH 31 50 30 <dados>   # grava; pL pH = tamanho(dados) + 3
1D 28 6B 03 00 31 51 30           # imprime o QR
```

Recibos de exemplo no guia Cupom: veja a página Como funciona.

## Cliente e consentimento

Quando o selo entra na hora e quando fica pendente.

O telefone informado no caixa não cadastra ninguém. O selo entra na hora só se o telefone já tem aceite no GIRO.

Sem aceite, ou sem telefone, o selo fica pendente. A imagem do cupom traz um QR, e o cliente ativa o selo ao aceitar o programa pelo celular.

O QR vale pelo prazo da loja. A data aparece no cupom.

O PDV não decide nada disso. Envie a venda sempre do mesmo jeito.

## Token no PDV do balcão

Onde guardar o token quando o PDV roda no computador da loja.

Muitos PDVs rodam no computador do balcão, sem servidor. Nesse caso, o token fica no próprio computador, e o cuidado é maior.

Guarde o token no cofre do sistema operacional: no Windows, o Gerenciador de Credenciais ou a proteção de dados do Windows (DPAPI); no Linux, o chaveiro do sistema. Nunca guarde o token em arquivo de configuração aberto ou em banco local sem criptografia.

O operador nunca vê o token. A tela de configuração do PDV mostra só os 4 últimos caracteres.

Cada loja tem o seu token. Nunca copie o token de uma loja para outra.

Se o computador for roubado, trocado ou formatado, peça a troca do token em Minha conta. O token antigo deixa de valer depois de uma janela curta.

## Autenticação

Um token por conexão, enviado como Bearer.

Cada conexão liga um PDV a uma loja, em um ambiente. Cada conexão tem um token permanente, gerado pelo GIRO.

Envie o token no cabeçalho Authorization, como Bearer. A loja vem do token: não envie o código da loja.

O token de teste começa com giro_test_. O token de produção começa com giro_live_.

Guarde o token no servidor do PDV. Nunca coloque o token em código que roda no navegador.

Se o token vazar, peça a troca. Por uma janela curta, o token antigo e o novo valem juntos.

## Idempotência e repetição

Repita com segurança quando a rede falhar.

O cabeçalho Idempotency-Key identifica o pedido. Gere uma chave por pedido e repita a mesma chave quando a rede falhar. Mesma chave e mesmo corpo devolvem a mesma resposta.

Mesma chave com outro corpo devolve CHAVE_JA_PROCESSADA_COM_RESULTADO_DIFERENTE. A largura do cupom não conta como corpo.

A chave external_id identifica a venda, de forma durável. A mesma venda enviada com uma Idempotency-Key nova não gera selo novo.

Mudança de estado não cria venda nova. O cancelamento que chega antes da venda fica guardado e impede o selo.

A venda pode chegar até 7 dias depois. Guarde as vendas sem resposta e reenvie quando a rede voltar.

## Erros e limites

Catálogo de erros e limites de chamadas.

Todo erro devolve um corpo application/problem+json (RFC 9457), com o campo code estável. Trate pelo code: o texto pode mudar.

Toda resposta traz o cabeçalho X-Request-Id. Informe esse valor no chamado de suporte.

Cada conexão faz até 120 chamadas por minuto, e cada parceiro, até 600. Acima disso, respeite o cabeçalho Retry-After. Um token desconhecido conta no limite de 60 tentativas por minuto por IP; o token válido já conhecido passa.

O teto por venda é configurado pela loja. O padrão é R$ 5.000,00. Acima dele, a resposta é VALOR_ACIMA_DO_TETO.

O PDV nunca trava a venda por causa do GIRO. Quando a chamada falha, a venda segue, e o operador vê a frase da coluna "No caixa". Erro sem frase não aparece ao operador: registre no log do PDV.

| HTTP | Código | Mensagem da API | No caixa |
|---|---|---|---|
| 401 | TOKEN_INVALIDO | Token ausente, inválido ou revogado. | A fidelidade está fora do ar nesta loja. A venda segue normal. |
| 403 | CONEXAO_DESLIGADA | A conexão está desligada para esta operação. | A fidelidade está desligada nesta loja. A venda segue normal. |
| 403 | CAPACIDADE_NAO_HOMOLOGADA | A capacidade não está homologada nesta conexão. | A fidelidade ainda não está liberada nesta loja. A venda segue normal. |
| 404 | VENDA_NAO_ENCONTRADA | Venda não encontrada. | Não mostrar. Registrar no log. |
| 409 | PROGRAMA_NAO_CONFIGURADO | A loja não tem programa de selos configurado. | A loja ainda não configurou o programa de selos. A venda segue normal. |
| 409 | CHAVE_JA_PROCESSADA_COM_RESULTADO_DIFERENTE | Esta chave já foi processada com outro conteúdo. | Não mostrar. Registrar no log. |
| 409 | IDENTIFICADOR_EM_USO | O identificador da venda já está em uso na loja. | Não mostrar. Registrar no log. |
| 415 | TIPO_DE_CONTEUDO_INVALIDO | Envie o corpo como application/json. | Não mostrar. Registrar no log. |
| 422 | DADOS_INVALIDOS | Dados inválidos. | Não deu para registrar o selo desta venda. A venda segue normal. |
| 422 | VALOR_ACIMA_DO_TETO | O valor da venda passa do teto configurado pela loja. | Esta venda passa do limite da fidelidade da loja. A venda segue normal, sem selo. |
| 422 | VENDA_FORA_DA_TOLERANCIA | A data da venda está fora da tolerância de 7 dias. | Não mostrar. Registrar no log. |
| 429 | LIMITE_EXCEDIDO | Limite de chamadas excedido. Tente de novo em instantes. | Não mostrar. Registrar no log. |
| 503 | CANAL_DESLIGADO | O canal de parceiros está desligado neste ambiente. | A fidelidade está fora do ar. A venda segue normal. |

## Testes no sandbox

O que a loja de teste tem e o que testar.

O sandbox é uma instância separada, com banco próprio e dados sintéticos. Nada do sandbox chega à produção.

A loja de teste tem programa de selos configurado. Telefone real enviado por engano não dispara mensagem nem cobrança.

A suíte de conformidade roda estes 13 casos:

1. Mesma venda com Idempotency-Key nova: nenhum selo novo.
2. Mesma Idempotency-Key com corpo diferente: CHAVE_JA_PROCESSADA_COM_RESULTADO_DIFERENTE.
3. Repetição depois do prazo do cache: a venda continua única.
4. Cancelamento antes da venda.
5. Cancelamento depois da venda.
6. Venda atrasada, dentro e fora da tolerância.
7. Venda abaixo do valor mínimo do programa.
8. Cliente novo pelo QR do cupom.
9. Cliente existente pelo QR do cupom.
10. Conexão desligada.
11. Resposta perdida, seguida de consulta.
12. CNPJ numérico e alfanumérico.
13. Telefone real no sandbox: nenhuma mensagem sai.

## Conectar uma loja

Como cada loja do seu PDV passa a falar com o GIRO.

Cada loja tem a sua conexão, com o seu token de produção. A conexão nasce desligada.

Hoje, a equipe GIRO cria a conexão da loja a pedido do lojista e entrega o token ao contato técnico do PDV.

Em seguida, o lojista vai gerar no painel do GIRO um código de conexão de 8 caracteres, de uso único e válido por 15 minutos. O servidor do seu PDV troca o código pelo token da loja. O código sozinho não emite token.

A conexão nova herda as capacidades da versão do seu PDV já homologada, depois de um teste de ativação na loja.

## Ativação e desligamento

O que muda na loja quando a conexão liga ou desliga.

Cada conexão tem permissões separadas de registrar venda e de resgatar. Cada compra tem uma única fonte de selo.

Na ativação, o GIRO registra a data de corte. A partir dela, o app GIRO da maquininha deixa de registrar venda e resgate naquela loja, e o seu PDV passa a ser a fonte. A gestão do programa continua no app.

No desligamento planejado, a conexão deixa de aceitar operações novas e conclui só as vendas já iniciadas, inclusive as offline anteriores ao corte. Depois, o app volta a registrar venda e resgate.

Na revogação por incidente, o bloqueio é imediato, e as pendências vão à conciliação assistida.

Uma venda anterior ao corte que chega depois dele carrega a identidade original e não credita duas vezes.

## Open Delivery

O GIRO fala Open Delivery onde o padrão cobre. O resto são extensões do GIRO, com caminho próprio.

Onde o GIRO publica uma operação do padrão Open Delivery, método, schema, unidades, paginação e erros são os do padrão, na versão fixada. O PDV que fala o padrão conversa com o GIRO sem adaptador.

As convenções do GIRO valem só nas extensões do GIRO, com caminho próprio, e nunca mudam uma operação do padrão.

Cada operação do padrão só é publicada depois da sua matriz de conformidade, testada contra o contrato do padrão. A cartela de selos entra como extensão declarada, porque o saldo do padrão não representa cartela.

O mapa abaixo mostra, por camada, o que segue o padrão e o que é extensão do GIRO.

| Item | Descrição |
|---|---|
| Autenticação | Bearer com o token permanente da conexão. O POST /oauth/token do padrão entra como compatibilidade e devolve o mesmo token. · Em breve |
| Cliente | Modelo Customer do Open Delivery, com telefone E.164. · Em breve |
| Consulta de carteira | Host Loyalty do Open Delivery. · Em breve |
| Eventos e webhooks | Envelope e assinatura do Open Delivery. · Em breve |
| Venda de balcão | Extensão do GIRO: POST /v1/sales. · Disponível |
| Cartela de selos | Extensão do GIRO: card na resposta da venda e GET /v1/program. · Disponível |
| QR e cupom pronto | Extensão do GIRO: claim e receipt na resposta da venda. · Disponível |
| Resgate em duas fases | Extensão do GIRO: reservar, confirmar e cancelar. · Em breve |

## Homologação

A suíte de conformidade libera a produção.

A suíte de conformidade roda no sandbox e prova que o PDV trata cada caso do caixa.

A homologação vale por versão do seu PDV e por perfil. Versão nova com mudança relevante homologa de novo só o que mudou.

Quando a suíte passa, a equipe GIRO libera a credencial de produção. A primeira homologação é assistida pela equipe GIRO.

1. Mesma venda com Idempotency-Key nova: nenhum selo novo.
2. Mesma Idempotency-Key com corpo diferente: CHAVE_JA_PROCESSADA_COM_RESULTADO_DIFERENTE.
3. Repetição depois do prazo do cache: a venda continua única.
4. Cancelamento antes da venda.
5. Cancelamento depois da venda.
6. Venda atrasada, dentro e fora da tolerância.
7. Venda abaixo do valor mínimo do programa.
8. Cliente novo pelo QR do cupom.
9. Cliente existente pelo QR do cupom.
10. Conexão desligada.
11. Resposta perdida, seguida de consulta.
12. CNPJ numérico e alfanumérico.
13. Telefone real no sandbox: nenhuma mensagem sai.

```bash
npx @giro/conformidade --api "$GIRO_API" --token "$GIRO_TOKEN"
```

## Histórico de mudanças

O que mudou em cada versão da API.

Toda mudança tem data, categoria e versão.

Mudança que quebra a integração só sai numa versão nova da API, como a v2. A versão anterior continua funcionando por pelo menos 12 meses, e o aviso chega por e-mail ao contato técnico e neste histórico.

Mudança que não quebra a integração entra sem aviso prévio e aparece aqui no dia em que entra.

| Item | Descrição |
|---|---|
| 1.0.0 | Adicionado: registro, cancelamento e consulta da venda; leitura do programa; saúde da conexão. |

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