Integração com a Linx (App do Consumidor/POS e AutoSystem): validação do código do cliente, pós-venda, cancelamento e preços. Rotas /v1/integracao/, com corpo e respostas no formato da Linx (sem o envelope status) e acesso alternativo pelo prefixo /linx com o cabeçalho Authorization. Perfis e senha do dia seguem o manual geral das APIs de terceiro.
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 |
|---|---|---|
integracao/validarcodigo/lista |
POST | Linx: valida o código (token) do cliente e calcula o desconto da venda |
integracao/posvenda |
POST | Linx: confirma a venda (pós-venda) |
integracao/cancelarvenda |
POST | Linx: cancela a venda do token |
integracao/produto/lista |
POST | Linx: envia os preços de bomba dos produtos do posto |
Linx: valida o código (token) do cliente e calcula o desconto da venda. Chamado pelo POS/AutoSystem da Linx antes de fechar a venda: confere o token do cliente (codigoValidacao), calcula preço com desconto e quanto o saldo do app paga, e deixa a venda PENDENTE (P) para a pós-venda confirmar. O token pode vir normal, em base64 ou como o JSON do QR "completo" da Linx. Como em terceiro/venda, o token vale para o posto e para o total da venda (soma dos valorVenda) informado no app. Autenticação como as demais (APP/REDE/CNPJ/CPF + SENHA + A na query; para a Linx, CNPJ do posto). Alternativa usada pela Linx: chamar o mesmo caminho com o prefixo /linx (…/linx/api/v1/integracao/…, fora do /api) com o cabeçalho Authorization: Basic .. (texto puro, sem base64); o servidor calcula a senha do dia e repassa para a rota normal. O tokenIntegracao do corpo só precisa existir (não é conferido).
/v1/integracao/validarcodigo/listaValida o código e registra a venda pendente
Perfis: App, Rede, Posto, Cliente, Pessoa
Corpo (JSON lista)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
codigoValidacao |
string | sim | Token do cliente (12 dígitos, base64 ou JSON do QR). Use o mesmo em todos os itens. |
codigoEmpresa |
string | sim | CNPJ do posto, só números. |
identificadorExternoProduto |
string | sim | Código numérico do produto na Linx (de-para cadastrado no GAS4US). Produto sem de-para entra como outros (sem desconto). |
valorVenda |
number | sim | Valor do item a preço cheio (> 0). |
quantidade |
number | sim | Litros (0 = calcula por valorVenda / preço de bomba). |
dataVenda |
string | sim | Data da venda (só precisa existir). |
parametroOpcional |
string | sim | Devolvido como veio. |
codigoColaborador |
string | não | Código interno do caixa ou frentista no GAS4US (grava o CPF dele na venda). |
regraInterna |
boolean | não | true = item sem desconto do app e fora das validações. |
curl -s -X POST "$BASE/v1/integracao/validarcodigo/lista?$AUTH" \
-H 'Content-Type: application/json' \
-d '[{"codigoValidacao": "123456789012", "codigoEmpresa": "00000000000100", "identificadorExternoProduto": "101", "valorVenda": 120.0, "quantidade": 20.0, "dataVenda": "2026-11-12T10:15:00", "parametroOpcional": "1"}]'
Resposta:
[
{
"codigoValidacao": "123456789012",
"valorPorUnidade": 6.0,
"valorPorUnidadeDesconto": 5.8,
"valorDescontoTotal": 20.0,
"valorVendaTotal": 100.0,
"quantidade": 20.0,
"nomeCliente": "CLIENTE EXEMPLO",
"chaveAutenticacao": "123456789012",
"placa": "",
"cpf": "00000000000",
"isAceitaCPF": false,
"isEmitenteDocumentoFiscal": false,
"parametroOpcional": "1",
"identificadorExternoProduto": "101",
"tipoCodigo": "DESCONTO",
"formaPagamento": "",
"quantidadeParcela": 0
}
]
Erros específicos: 400 — campos ausentes: 'Codigo nao enviado', 'Valor da venda nao pode ser nulo ou zero', 'Quantidade invalida', 'Empresa Invalida', 'Identificador externo produto invalido', 'Data venda invalida', 'Parametro opcional invalido'.; 400 — 'Token Invalido' (token inválido, expirado, de outra pessoa ocupada, promoção ausente…), 'Empresa Invalida' (posto não encontrado pelo CNPJ), 'Codigo Bloqueado' (cliente bloqueado), 'Limite de codigo utilizados foi excedido' (token já usado). O motivo detalhado fica só no log do servidor.; 500 — identificadorExternoProduto não numérico.; Erros da regra seguem o formato da Linx: {"status": 400, "message": "<1º erro>", "erros": ["…"]}; erro inesperado = 500 no mesmo formato; corpo que não é JSON = 400 "JSON invalido: …"..
Linx: confirma a venda (pós-venda). Chamado pela Linx depois de concluir a venda: confirma (P → C) a venda pendente do token no posto e devolve os itens. Reenvio da mesma pós-venda devolve os mesmos dados sem gravar de novo; reenvio de venda confirmada há mais de 1 dia devolve 400 (chave inválida), para o POS descartar a pendência. O posto é o do acesso (CNPJ do posto); no acesso de app, id_posto na query. Autenticação como as demais (APP/REDE/CNPJ/CPF + SENHA + A na query; para a Linx, CNPJ do posto). Alternativa usada pela Linx: chamar o mesmo caminho com o prefixo /linx (…/linx/api/v1/integracao/…, fora do /api) com o cabeçalho Authorization: Basic .. (texto puro, sem base64); o servidor calcula a senha do dia e repassa para a rota normal. O tokenIntegracao do corpo só precisa existir (não é conferido).
/v1/integracao/posvendaConfirma a venda pendente do token
Perfis: App, Rede, Posto, Cliente, Pessoa
Corpo (JSON objeto)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
chaveAutenticacao |
string | sim | chaveAutenticacao devolvida na validação (token de 12 dígitos; aqui não é normalizado). |
tokenIntegracao |
string | sim | Precisa existir; não é conferido. |
curl -s -X POST "$BASE/v1/integracao/posvenda?$AUTH" \
-H 'Content-Type: application/json' \
-d '{"tokenIntegracao": "<token da Linx>", "chaveAutenticacao": "123456789012"}'
Resposta:
[
{
"codigoValidacao": "123456789012",
"valorPorUnidade": 6.0,
"valorPorUnidadeDesconto": 5.8,
"valorDescontoTotal": 20.0,
"valorVendaTotal": 100.0,
"quantidade": 20.0,
"nomeCliente": "CLIENTE EXEMPLO",
"chaveAutenticacao": "123456789012",
"identificadorExternoProduto": "101"
}
]
Erros específicos: 400 — 'Token Invalido' / 'Chave de Autenticacao Invalida': tokenIntegracao ou chaveAutenticacao ausentes.; 400 — 'Chave de Autenticacao Invalida': não há venda pendente nem confirmada desse token no posto, ou foi confirmada há mais de 1 dia.; Erros da regra seguem o formato da Linx: {"status": 400, "message": "<1º erro>", "erros": ["…"]}; erro inesperado = 500 no mesmo formato; corpo que não é JSON = 400 "JSON invalido: …"..
Linx: cancela a venda do token. Cancela (situação X) a venda do token feita há no máximo 30 minutos e libera o token e a trava da pessoa. Autenticação como as demais (APP/REDE/CNPJ/CPF + SENHA + A na query; para a Linx, CNPJ do posto). Alternativa usada pela Linx: chamar o mesmo caminho com o prefixo /linx (…/linx/api/v1/integracao/…, fora do /api) com o cabeçalho Authorization: Basic .. (texto puro, sem base64); o servidor calcula a senha do dia e repassa para a rota normal. O tokenIntegracao do corpo só precisa existir (não é conferido). Só cancela venda feita em posto do escopo do acesso (o próprio posto, ou os postos da rede); se vier codigoEmpresa, também tem de ser desse posto.
/v1/integracao/cancelarvendaCancela pelo token
Perfis: App, Rede, Posto, Cliente, Pessoa
Corpo (JSON objeto)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
chaveAutenticacao |
string | sim | Token da venda (chaveAutenticacao da validação). |
tokenIntegracao |
string | sim | Precisa existir; não é conferido. |
curl -s -X POST "$BASE/v1/integracao/cancelarvenda?$AUTH" \
-H 'Content-Type: application/json' \
-d '{"tokenIntegracao": "<token da Linx>", "chaveAutenticacao": "123456789012"}'
Resposta:
{
"status": "200",
"message": "Ok"
}
Erros específicos: 400 — 'Venda nao encontrada ou fora do periodo de cancelamento.': nenhuma venda desse token nos últimos 30 minutos.; 400 — 'Token Invalido' (sem tokenIntegracao); sem chaveAutenticacao = 400 'JSON invalido: …'.; Erros da regra seguem o formato da Linx: {"status": 400, "message": "<1º erro>", "erros": ["…"]}; erro inesperado = 500 no mesmo formato; corpo que não é JSON = 400 "JSON invalido: …"..
Linx: envia os preços de bomba dos produtos do posto. A Linx envia a lista de produtos com preço; para cada produto com de-para no GAS4US, grava o novo preço de bomba quando mudou (ATIVO) ou zera o preço (INATIVO). Autenticação como as demais (APP/REDE/CNPJ/CPF + SENHA + A na query; para a Linx, CNPJ do posto). Alternativa usada pela Linx: chamar o mesmo caminho com o prefixo /linx (…/linx/api/v1/integracao/…, fora do /api) com o cabeçalho Authorization: Basic .. (texto puro, sem base64); o servidor calcula a senha do dia e repassa para a rota normal. O tokenIntegracao do corpo só precisa existir (não é conferido).
/v1/integracao/produto/listaAtualiza os preços de bomba
Perfis: App, Rede, Posto, Cliente, Pessoa
Corpo (JSON lista)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
codigoEmpresa |
string | sim | CNPJ do posto (a pontuação é retirada). |
identificadorExternoProduto |
string | sim | Código numérico do produto na Linx (de-para). |
descricaoProduto |
string | sim | Devolvido como veio. |
modalidadeProduto |
string | sim | Precisa existir; não é usado. |
valor |
number | sim | Preço de bomba por litro. |
status |
string | sim | ATIVO (grava o preço) ou INATIVO (zera o preço). |
tokenIntegracao |
string | sim | Precisa existir; não é conferido. |
codigoBarras / ncm / anp |
string | não | Só devolvidos (se faltar um dos três, os três voltam vazios). |
curl -s -X POST "$BASE/v1/integracao/produto/lista?$AUTH" \
-H 'Content-Type: application/json' \
-d '[{"codigoEmpresa": "00000000000100", "identificadorExternoProduto": "101", "descricaoProduto": "GASOLINA COMUM", "modalidadeProduto": "COMBUSTIVEL", "valor": 6.09, "status": "ATIVO", "tokenIntegracao": "<token da Linx>"}]'
Resposta:
[
{
"identificadorExternoProduto": "101",
"descricaoProduto": "GASOLINA COMUM",
"ncm": "",
"anp": "",
"codigoBarras": "",
"valor": 6.09,
"status": "ATIVO",
"acao": "CREATE"
}
]
Erros específicos: 400 — campo ausente em algum item: 'Valor invalido', 'Status invalido', 'Descricao produto invalida', 'Modalidade produto invalida', 'Identificador externo produto invalido', 'Token Invalido', 'Empresa Invalida' (nada é processado a partir desse item).; Erros da regra seguem o formato da Linx: {"status": 400, "message": "<1º erro>", "erros": ["…"]}; erro inesperado = 500 no mesmo formato; corpo que não é JSON = 400 "JSON invalido: …"..