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.

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

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.

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.

# 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.