EntrarCriar conta

Registrar uma venda

POST/v1/sales

Avisa o GIRO de uma venda do balcão. O GIRO aplica a regra do programa da loja e devolve o crédito e o bloco do GIRO pronto para o cupom, em texto e em imagem.

A API segue o Open Delivery onde o padrão cobre, e as rotas abaixo são extensões do GIRO. Veja o guia Open Delivery.

Envie o token da conexão no cabeçalho Authorization: Bearer. A loja vem do token. Erros voltam em application/problem+json, com o campo codigo.

Baixar o OpenAPI (YAML)
Corpo do pedido
Idempotency-Keycabeçalhoobrigatório

Chave única do pedido, gerada pelo PDV. Repita a mesma chave ao reenviar o mesmo pedido.

external_idstringobrigatório

Chave da venda no PDV. De 1 a 64 caracteres: letras, números, ponto, sublinhado, dois-pontos e hífen. É a chave de idempotência.

total_centsinteiroobrigatório

Total da venda em centavos, maior que zero.

occurred_atdata e horaobrigatório

Momento da venda, com fuso horário (ISO 8601). Aceita até 7 dias para trás e até 5 minutos para a frente.

customer.phonestringopcional

Telefone do cliente em E.164. O selo entra na hora só se o cliente já aceitou o GIRO.

customer.documentstringopcional

CPF ou CNPJ do cliente, só dígitos.

itemslistaopcional

Itens da venda.

receipt.formattextoopcional

Formato do bloco do GIRO: "image" (padrão e recomendado) ou "text". A resposta traz o formato pedido.

receipt.widthinteiroopcional

Largura do cupom em colunas: 32 (bobina de 58 mm), 42 ou 48 (80 mm). O padrão é 48. A imagem sai na mesma largura: 384, 512 ou 576 pontos.

receipt.charsettextoopcional

Só para receipt.format = "text". Caracteres que a impressora imprime: "ascii" (padrão) ou "unicode". Com "unicode", a barra de selos usa ● e ○; com "ascii", usa X e _.

Erros desta rota

HTTPCódigoMensagem da APINo caixa
409PROGRAMA_NAO_CONFIGURADOA loja não tem programa de selos configurado.A loja ainda não configurou o programa de selos. A venda segue normal.
409CHAVE_JA_PROCESSADA_COM_RESULTADO_DIFERENTEEsta chave já foi processada com outro conteúdo.Não mostrar. Registrar no log.
409IDENTIFICADOR_EM_USOO identificador da venda já está em uso na loja.Não mostrar. Registrar no log.
415TIPO_DE_CONTEUDO_INVALIDOEnvie o corpo como application/json.Não mostrar. Registrar no log.
422DADOS_INVALIDOSDados inválidos.Não deu para registrar o selo desta venda. A venda segue normal.
422VALOR_ACIMA_DO_TETOO valor da venda passa do teto configurado pela loja.Esta venda passa do limite da fidelidade da loja. A venda segue normal, sem selo.
422VENDA_FORA_DA_TOLERANCIAA data da venda está fora da tolerância de 7 dias.Não mostrar. Registrar no log.
401TOKEN_INVALIDOToken ausente, inválido ou revogado.A fidelidade está fora do ar nesta loja. A venda segue normal.
403CONEXAO_DESLIGADAA conexão está desligada para esta operação.A fidelidade está desligada nesta loja. A venda segue normal.
403CAPACIDADE_NAO_HOMOLOGADAA capacidade não está homologada nesta conexão.A fidelidade ainda não está liberada nesta loja. A venda segue normal.
429LIMITE_EXCEDIDOLimite de chamadas excedido. Tente de novo em instantes.Não mostrar. Registrar no log.
503CANAL_DESLIGADOO canal de parceiros está desligado neste ambiente.A fidelidade está fora do ar. A venda segue normal.
Pedido
curl -X POST "$GIRO_API/v1/sales" \
  -H "Authorization: Bearer $GIRO_TOKEN" \
  -H "Idempotency-Key: 6f1c2a90-3b7e-4d0a-9e51-8c2b4f7d1a33" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "venda-1042",
    "total_cents": 4590,
    "occurred_at": "2026-11-03T14:32:00-03:00",
    "customer": { "phone": "+5511987654321" },
    "receipt": { "format": "image", "width": 48 }
  }'
Resposta · 200
{
  "external_id": "venda-1042",
  "status": "registrada",
  "credit": {
    "kind": "stamps",
    "amount": 1,
    "state": "efetivado"
  },
  "card": {
    "stamps": 7,
    "goal": 10,
    "completed_now": false
  },
  "claim": null,
  "receipt": {
    "format": "image",
    "width": 48,
    "snapshot_at": "2026-02-10T17:32:00Z",
    "image": "data:image/png;base64,iVBORw0KGgo..."
  }
}