Abastecimento com o token do app do cliente: validar, registrar, consultar e cancelar vendas no posto.
Autenticação em todos os exemplos: veja Autenticação. Teste no navegador pelo Swagger ou importe a coleção do Postman.
| Endpoint | Métodos | Para que serve |
|---|---|---|
venda |
GET, POST, DELETE | Abastecimento com o token do app: validar, registrar, consultar e cancelar |
Abastecimento com o token do app: validar, registrar, consultar e cancelar. Venda no posto com o token de 12 dígitos que o cliente gera no app. O token pode chegar como lido do QR Code: normal (12 dígitos, com ou sem espaços/pontuação), em base64, ou como o JSON do QR "completo" ({"codigoValidacao": …}, puro ou em base64); a API fica com os 12 dígitos. O posto vem do acesso (CNPJ do posto) ou do parâmetro id_tx_estabelecimento/id_posto nos acessos de app e rede. Até 5 combustíveis por venda (id_comb1..5 / total_abast1..5) e um valor de outros produtos (total_outros, sem desconto). O desconto vem da promoção vigente do posto (preço do app; com desconto extra até um limite de litros, quando houver) ou do convênio do cliente. O token é gerado no app para o posto e para o valor total da venda a preço cheio (combustíveis + outros) e vale por pouco tempo: o total enviado precisa ser o mesmo que o cliente informou no app, senão o token é recusado como inválido ou expirado. Informe pelo menos um combustível (id_comb1 + total_abast1) ou total_outros. Os parâmetros vão na query (ou no corpo como formulário x-www-form-urlencoded); corpo JSON não é lido.
/v1/terceiro/vendaVendas confirmadas do posto (paginada)
Lista as vendas do posto em situação confirmada ou liberada (C/L). Sem posto não há resultado.
Perfis: App, Rede, Posto, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_tx_estabelecimento |
integer | não | Posto (aceita também id_estabelecimento ou id_posto). No acesso de posto (CNPJ do posto) é fixado pelo acesso e não precisa ser enviado; nos acessos de app e rede é obrigatório na prática (sem ele não há resultado). |
id_venda |
integer | não | Uma venda. |
id_comb |
integer | não | Vendas com esse combustível em qualquer dos 5 itens (aceita id_produto). |
data_inicial |
date | não | Data da venda, AAAA-MM-DD (aceita data_inicio/data_ini). Padrão 1980-01-01. |
data_final |
date | não | AAAA-MM-DD (aceita data_fim). Padrão 2099-12-31. |
cpf_caixa |
string | não | Filtra pelo CPF do caixa. |
cpf_frentista |
string | não | Filtra pelo CPF do frentista. |
recebimento |
string | não | caixa, app ou * (padrão, todas). |
size |
integer | não | Tamanho da página (padrão e máximo 50). |
page |
integer | não | Página (padrão 1). |
curl -s -X GET "$BASE/v1/terceiro/venda?$AUTH"
Resposta:
{
"data": [
{
"id_venda": 123456,
"id_comb": 1,
"id_comb1": 1,
"id_comb2": 0,
"nome_comb": "GASOLINA COMUM",
"nome_comb1": "GASOLINA COMUM",
"quantidade": 20.0,
"quantidade1": 20.0,
"quantidade_total": 20.0,
"unit_sem_desconto": 6.0,
"abast_sem_desconto": 120.0,
"outros_sem_desconto": 0.0,
"total_sem_desconto": 120.0,
"unit_com_desconto1": 5.8,
"abast_com_desconto": 116.0,
"outros_com_desconto": 0.0,
"total_com_desconto": 116.0,
"desconto_abast": 4.0,
"desconto_abast_total": 4.0,
"desconto_outros": 0.0,
"pontos_ent": 0,
"pontos_sai": 0,
"data_hora_venda": "2026-11-12 10:15:00",
"cpf_caixa": "",
"cpf_frentista": "",
"recebimento": "app"
}
],
"param": {
"_count": 1,
"_pages": 1,
"_size": 50,
"_page": 1
},
"status": "ok"
}
Erros específicos: 401 — credencial inválida.; 403 — sem permissão ou id_tx_estabelecimento diferente do acesso..
/v1/terceiro/vendaValida (padrão) ou registra a venda
Sem acao=registrar a chamada só VALIDA: calcula descontos e forma de pagamento e devolve os valores, sem gravar nada (o token não é consumido). Com acao=registrar grava a venda: usa primeiro o saldo do cliente e o resto vai para o cartão favorito (recebimento=app) ou fica para o caixa (recebimento=caixa). Proteções ao registrar: o mesmo token não registra duas vezes (nem em reenvios até 6 h depois), e a mesma pessoa fica travada por 15 s durante a venda ("Em uso… aguarde 15 segundos"). Fora de produção (ambiente de testes) os tokens 100100100100, 200200200200 e 300300300300 passam pela validação do token (sandbox).
Perfis: App, Rede, Posto, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
token |
string | sim | Token do app (12 dígitos; aceita também base64 ou o JSON do QR, ver acima). |
id_tx_estabelecimento |
integer | não | Posto (aceita também id_estabelecimento ou id_posto). No acesso de posto (CNPJ do posto) é fixado pelo acesso e não precisa ser enviado; nos acessos de app e rede é obrigatório na prática (sem ele não há resultado). |
id_comb1 |
integer | não | Combustível 1 (id de tabelas?id_tabela=1). Aceita também id_comb ou id_produto. |
total_abast1 |
number | não | Valor do abastecimento do combustível 1 a preço de bomba (R$, até 15.000). Aceita também total_abast. |
litros_abast1 |
number | não | Litros do combustível 1. Sem ele, a quantidade é calculada por total_abast1 / preço de bomba. Aceita também litros_abast. |
id_comb2..5 / total_abast2..5 / litros_abast2..5 |
number | não | Demais combustíveis da mesma venda (até 5). |
total_outros |
number | não | Outros produtos (sem desconto do app), R$. |
acao |
string | não | validar (padrão: só simula) ou registrar (grava a venda). |
recebimento |
string | não | app (padrão: saldo + cartão favorito do cliente) ou caixa (saldo + restante pago no caixa do posto). |
placa |
string | não | Placa do veículo (validada quando enviada). |
quilometragem |
integer | não | Hodômetro; só com placa. |
cpf_caixa |
string | não | CPF do operador de caixa (validado quando enviado). |
cpf_frentista |
string | não | CPF do frentista (validado quando enviado). |
observacao |
string | não | Texto livre gravado na venda. |
gerar_pontos / gerar_cashback / gerar_sorte / gerar_cupom |
boolean | não | Só desligam benefícios que o app já daria para o cliente (false); não ligam o que o app não dá. |
curl -s -X POST "$BASE/v1/terceiro/venda?$AUTH&token=123456789012"
Resposta:
{
"id_venda": 123456,
"token": "123456789012",
"id_comb": 1,
"nome_comb": "GASOLINA COMUM",
"quantidade": 20.0,
"unit_sem_desconto": 6.0,
"abast_sem_desconto": 120.0,
"unit_com_desconto": 5.8,
"abast_com_desconto": 116.0,
"desconto_abast": 4.0,
"id_comb1": 1,
"nome_comb1": "GASOLINA COMUM",
"quantidade1": 20.0,
"unit_sem_desconto1": 6.0,
"abast_sem_desconto1": 120.0,
"unit_com_desconto1": 5.8,
"abast_com_desconto1": 116.0,
"desconto_abast1": 4.0,
"id_comb2": 0,
"nome_comb2": "",
"quantidade2": 0.0,
"unit_sem_desconto2": 0.0,
"abast_sem_desconto2": 0.0,
"unit_com_desconto2": 0,
"abast_com_desconto2": 0.0,
"desconto_abast2": 0.0,
"total_sem_desconto": 120.0,
"outros_sem_desconto": 0.0,
"total_com_desconto": 116.0,
"outros_com_desconto": 0.0,
"desconto_outros": 0.0,
"desconto_total": 4.0,
"valor_pago_caixa": 0.0,
"valor_pago_saldo": 16.0,
"valor_pago_cartao": 100.0,
"cartao": "**** 0000",
"cpf_caixa": "",
"cpf_frentista": "",
"placa": "ABC1D23",
"quilometragem": 0,
"recebimento": "app",
"acao": "registrar",
"data_hora": "2026-11-12 10:15:00",
"status": "ok"
}
Erros específicos: 400 — {token: 'Inválido… Será necessário gerar um token válido. [...]'}: token que não é do app.; 400 — {token: 'Inválido ou expirado…'}, {token: 'Já utilizado…'} ou {token: 'Já existe uma operação pendente para esse usuário com este token.'}.; 400 — {id_tx_pessoa: 'Bloqueado…'}, {id_tx_pessoa: 'Inválido…'} ou {id_tx_pessoa: 'Em uso… Aguarde 15 segundos e tente novamente.'}.; 400 — {id_tx_estabelecimento: 'Inválido…'}: posto ausente, inativo ou de outro app.; 400 — {id_promocao1: 'Inválido…'}: posto sem promoção vigente para o combustível (ou preço do app maior que o de bomba).; 400 — {total_abast1: 'Inválido…'}, {total: 'Inválido…'} (soma zerada ou acima de 15.000), {total_outros: …}, {placa: 'Inválida…'}, {quilometragem: 'Inválida…'}, {cpf_caixa: …}, {cpf_frentista: …}.; 400 — {registro: 'Falha ao registrar: CARTÃO NÃO AUTORIZADO'}: pagamento no cartão recusado (nada é gravado).; As mensagens de 400 terminam com um trecho entre colchetes com os parâmetros recebidos (para suporte)..
/v1/terceiro/vendaCancela uma venda (até 30 minutos)
Cancela (situação X) a venda feita há no máximo 30 minutos, desde que o posto da venda seja do app e, nos acessos de rede/posto, da rede/posto do acesso.
Perfis: App, Rede, Posto, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_venda |
integer | sim | Id da venda (id_venda devolvido no registro). |
curl -s -X DELETE "$BASE/v1/terceiro/venda?$AUTH&id_venda=123456"
Resposta:
{
"status": "ok"
}
Erros específicos: 400 — {registro: 'Falha ao cancelar'}: venda não existe, tem mais de 30 minutos ou está fora do escopo do acesso..