APIs Integração Sistemas de Terceiros v. 0.0.6
Nossas APIs são aplicações RESTful e sempre retornam os dados no formato JSON utilizando o charset UTF-8.
Utilizamos SSL em tudo e nossa autenticação é baseada em TOKEN (senha do dia).
TODAS as requisições devem informar o CNPJ do estabelecimento e a SENHA do dia.
https://gas4us.com/terceiros/api
https://gas4us.com/terceiros/sandbox
Tipos de dados
TIPO | FORMATO | EXEMPLO |
---|---|---|
text | gas4us | |
int | 1975 | |
numeric | 972.89 | |
date | aaaa-mm-dd | 2019-10-23 |
time | hh:mm:ss | 17:33:12 |
timestamp | aaaa-mm-dd hh:mm:ss | 2019-10-23 17:33:12 |
* caso você envie um parâmetro do tipo int/numeric com valor inválido o mesmo será considerado como 0 (zero)
Métodos
Nossas APIs suportam os seguintes métodos de requisição HTTP:
Retornos
Como saber o status das APIs?
Para saber o STATUS de funcionamento das APIs, você deve enviar uma requisição utilizando o método GET no formato abaixo:
{URL de produção ou testes}/v1/status?cnpj={cnpj do estabelecimento}&senha={senha do dia}
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
status | 'ok' ou 'error' | text |
* você também pode utilizar este endpoint para validar suas credenciais (cnpj + senha do dia)
https://gas4us.com/terceiros/api/v1/status?cnpj=25337354000157&senha=08642b70c3f06d8650c32ae8279db86b
https://gas4us.com/terceiros/sandbox/v1/status?cnpj=25337354000157&senha=08642b70c3f06d8650c32ae8279db86b
Como obter o CNPJ do estabelecimento?
Você deve solicitar o CNPJ ao usuário master do estabelecimento.
Como obter o identificador?
Você deve solicitar o IDENTIFICADOR ao usuário master do estabelecimento.
Como gerar a senha do dia?
Você vai gerar um md5 da concatenação do identificador, data atual no formato aaaa-mm-dd e do cnpj do estabelecimento (apenas números).
md5(identificador || aaaa-mm-dd || cnpj)
Exemplo
Identificador d563eef2d7354e1e8d080854d34574bf
Data atual 2019-10-23
CNPJ 25337354000157
Senha do dia 08642b70c3f06d8650c32ae8279db86b
A senha para o exemplo acima é válida durante o dia 23/10/2019.
Em TODAS as requisições para nossas APIs você deverá informar o CNPJ do estabelecimento e a SENHA do dia.
O identificador NUNCA é requisitado e deve ser armazenado de forma segura, você deve utilizar o identificador APENAS para gerar a senha do dia.
O estabelecimento pode TROCAR, BLOQUEAR ou CANCELAR o identificador sempre que achar necessário, ao trocar o identificador o anterior PARA de funcionar imediatamente.
Exemplos de código para gerar a senha do dia
public static String md5(String texto) { try { java.security.MessageDigest md = java.security.MessageDigest.getInstance("MD5"); md.update(texto.getBytes()); byte[] digest = md.digest(); StringBuilder sb = new StringBuilder(); for (byte b : digest) { sb.append(String.format("%02x", b & 0xff)); } return sb.toString(); } catch (java.security.NoSuchAlgorithmException e) { return null; } } public static String getSenhaDia(String identificador, String cnpj) { return md5(identificador + (new java.text.SimpleDateFormat("yyyy-MM-dd").format(new java.util.Date())) + cnpj); }
import 'dart:convert'; import 'package:convert/convert.dart'; import 'package:crypto/crypto.dart' as crypto; String md5(String texto) { return hex.encode(crypto.md5.convert(Utf8Encoder().convert(texto)).bytes); } String getSenhaDia(String identificador, String cnpj) { return md5(identificador + DateTime.now().toString().substring(0, 10) + cnpj); }
function getSenhaDia(identificador, cnpj) { return require('crypto').createHash('md5').update(identificador + new Date().toISOString().slice(0, 10) + cnpj).digest("hex"); }
import hashlib from datetime import datetime def getSenhaDia(identificador, cnpj): return (hashlib.md5((identificador + datetime.today().strftime('%Y-%m-%d') + cnpj).encode('utf-8')).hexdigest())
function getSenhaDia($identificador, $cnpj) { return md5($identificador . date("Y-m-d") . $cnpj); }
select md5( 'd563eef2d7354e1e8d080854d34574bf' || current_date || '25337354000157' ) as senha_dia
select md5( concat('d563eef2d7354e1e8d080854d34574bf', curdate(), '25337354000157') ) as senha_dia
Consultar estabelecimento
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
cnpj | cnpj do estabelecimento | text |
login | login do estabelecimento | text |
nome | nome do estabelecimento | text |
endereco1 | endereço do estabelecimento (parte 1) | text |
endereco2 | endereço do estabelecimento (parte 2) | text |
latitude | latitude do estabelecimento | numeric |
longitude | longitude do estabelecimento | numeric |
telefones | telefones do estabelecimento separados por / | text |
whatsapp do estabelecimento | text | |
e-mail do estabelecimento | text | |
site | site do estabelecimento | text |
horarios | horários de funcionamento do estabelecimento separados por / | text |
avaliacao | avaliação do estabelecimento | numeric |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
{ "data": { "whatsapp": "(41) 9 9701-1807", "latitude": -25.587666, "nome": "Posto Teste GAS4US", "cnpj": "25337354000157", "avaliacao": 4.8, "login": "GAS4US", "telefones": "(41) 9 9701-1807", "site": "https://www.gas4us.com", "horarios": "Dom: 09:00 às 14:00 / Seg a Sex: 09:00 às 17:00 / Sáb: 09:00 às 14:00", "endereco2": "Centro - Araucária/PR", "endereco1": "Avenida Doutor Victor do Amaral, 1020 - Sala 16", "data_hora": "2020-02-04 14:33:27", "email": "contato@gas4us.com", "longitude": -49.4002974 }, "status": "ok" }
Consultar preço bomba
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
id_comb (padrão: 0) | id do combustível (tabela 1) ou 0 para todos | int |
id_comb | id do combustível (tabela 1) | int |
nome_comb | nome do combustível (tabela 1) | text |
preco_bomba | preço do combustível na bomba em R$ | numeric |
data_hora_atu | data/hora da última atualização | timestamp |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
{ "data": { "precosBomba": [{ "preco_bomba": 9.99, "nome_comb": "Diesel S500 Comum", "id_comb": 6, "data_hora_atu": "2020-02-04 12:40:17" }], "data_hora": "2020-02-04 14:52:11" }, "status": "ok" }
Alterar preço bomba
Utilize este endpoint para alterar o preço de bomba de um combustível; Caso deseje retirar este combustível do aplicativo, informe o preço de bomba como 0 (zero); Após o preço de bomba ser alterado, pode levar até 10 (dez) minutos para o preço no aplicativo ser alterado.
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
id_comb (obrigatório) | id do combustível (tabela 1) | int |
preco_bomba (padrão: 0) | preço do combustível na bomba em R$ | numeric |
status | 'ok' ou 'error' | text |
* caso o preco_bomba enviado tenha mais de 3 (três) casas decimais o mesmo será arredondado
Consultar preço aplicativo
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
id_comb (padrão: 0) | id do combustível (tabela 1) ou 0 para todos | int |
id_comb | id do combustível (tabela 1) | int |
nome_comb | nome do combustível (tabela 1) | text |
preco_bomba | preço do combustível na bomba em R$ | numeric |
preco_aplicativo | preço do combustível no aplicativo em R$ | numeric |
data_hora_ini | data/hora do início deste preço | timestamp |
data_hora_fim | data/hora do término deste preço | timestamp |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
{ "data": { "precosAplicativo": [ { "preco_bomba": 9.99, "data_hora_ini": "2020-02-04 12:47:00", "nome_comb": "Diesel S500 Comum", "data_hora_fim": "2020-02-11 00:29:59", "id_comb": 6, "preco_aplicativo": 9.97 }, { "preco_bomba": 3.099, "data_hora_ini": "2020-02-04 06:00:00", "nome_comb": "GNV", "data_hora_fim": "2020-02-04 17:29:59", "id_comb": 11, "preco_aplicativo": 3.079 }, { "preco_bomba": 3.1, "data_hora_ini": "2020-01-31 00:32:00", "nome_comb": "Etanol Comum", "data_hora_fim": "2020-02-07 00:29:59", "id_comb": 9, "preco_aplicativo": 3.08 }, { "preco_bomba": 4.599, "data_hora_ini": "2020-01-29 15:22:00", "nome_comb": "Gasolina Comum", "data_hora_fim": "2020-02-05 00:29:59", "id_comb": 1, "preco_aplicativo": 4.579 } ], "data_hora": "2020-02-04 15:29:19" }, "status": "ok" }
Consultar saldo (créditos disponíveis)
Utilize este endpoint para consultar o saldo de créditos disponíveis de um usuário; O usuário deverá usar o aplicativo em seu celular para gerar o token; Este token tem validade de apenas alguns minutos e somente será válido se for gerado dentro do estabelecimento;
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
token (obrigatório) | token gerado no aplicativo pelo usuário | text |
login | login do usuário | text |
saldo | saldo de créditos disponíveis em R$ | numeric |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
{ "data": { "data_hora": "2020-02-05 09:58:12", "saldo": 1999.57, "login": "GAS4US" }, "status": "ok" }
100100100100 -> retornará R$ 45,72 200200200200 -> retornará R$ 0,00 300300300300 -> retornará R$ 999,01
Consultar limite de crédito (fiado)
Utilize este endpoint para consultar o limite de crédito concedido e disponível de um usuário; O usuário deverá usar o aplicativo em seu celular para gerar o token; Este token tem validade de apenas alguns minutos e somente será válido se for gerado dentro do estabelecimento;
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
token (obrigatório) | token gerado no aplicativo pelo usuário | text |
login | login do usuário | text |
concedido | limite de crédito concedido em R$ | numeric |
disponivel | limite de crédito disponível em R$ | numeric |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
{ "data": { "concedido": 5000, "disponivel": 1320.78, "data_hora": "2020-02-05 13:14:04", "login": "GAS4US" }, "status": "ok" }
100100100100 -> retornará R$ 1.000,00 de limite concedido e R$ 765,32 de limite disponível 200200200200 -> retornará R$ 0,00 de limite concedido e R$ 0,00 de limite disponível 300300300300 -> retornará R$ 5.000,00 de limite concedido e R$ 5.000,00 de limite disponível
Consultar ponto (fidelidade)
Utilize este endpoint para consultar a quantidade de pontos disponíveis de um usuário; O usuário deverá usar o aplicativo em seu celular para gerar o token; Este token tem validade de apenas alguns minutos e somente será válido se for gerado dentro do estabelecimento;
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
token (obrigatório) | token gerado no aplicativo pelo usuário | text |
login | login do usuário | text |
disponivel | quantidade de pontos disponíveis | int |
expirando | quantidade de pontos que irão expirar em até 30 (trinta) dias | int |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
{ "data": { "disponivel": 2251, "expirando": 131, "data_hora": "2020-02-05 13:53:34", "login": "GAS4US" }, "status": "ok" }
100100100100 -> retornará 325 pontos disponíveis e 13 pontos expirando 200200200200 -> retornará 0 pontos disponíveis e 0 pontos expirando 300300300300 -> retornará 2323 pontos disponíveis e 0 pontos expirando
Consultar colaborador
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
cpf (padrão: '') | cpf do colaborador ou em branco para todos | text |
situacao (padrão: 'ativo') | 'tudo', 'ativo' ou 'inativo' | text |
login | login do colaborador | text |
cpf | cpf do colaborador | text |
nome | nome do colaborador | text |
telefone | telefone do colaborador | text |
e-mail do colaborador | text | |
situacao | situação do colaborador | text |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
{ "data": { "colaboradores": [{ "telefone": "41997011807", "situacao": "ativo", "cpf": "99999999999", "nome": "FULANO DE TAL", "login": "FULANO", "email": "fulano@gas4us.com" }], "data_hora": "2020-02-06 09:50:00" }, "status": "ok" }
Consultar venda
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
id_venda (padrão: 0) | id da venda ou 0 (zero) para todos | int |
id_comb (padrão: 0) | id do combustível (tabela 1) ou 0 (zero) para todos | int |
data_ini (padrão: '2023-05-29') | data inicial | date |
data_fim (padrão: '2023-05-29') | data final | date |
cpf_caixa (padrão: '') | cpf do caixa ou em branco para todos | text |
cpf_frentista (padrão: '') | cpf do frentista ou em branco para todos | text |
recebimento (padrão: 'tudo') | 'tudo', 'caixa' ou 'app' | text |
id_venda | id da venda | int |
id_comb | id do combustível (tabela 1) | int |
nome_comb | nome do combustível (tabela 1) | text |
quantidade | quantidade de litros ou m³ | numeric |
unit_sem_desconto | unitário s/ desconto | numeric |
abast_sem_desconto | abastecimento s/ desconto | numeric |
outros_sem_desconto | outros s/ desconto | numeric |
total_sem_desconto | total s/ desconto | numeric |
unit_com_desconto | unitário c/ desconto | numeric |
abast_com_desconto | abastecimento c/ desconto | numeric |
outros_com_desconto | outros c/ desconto | numeric |
total_com_desconto | total c/ desconto | numeric |
desconto_abast | desconto abastecimento | numeric |
perc_desconto_abast | % desconto abastecimento | numeric |
desconto_outros | desconto outros | numeric |
perc_desconto_outros | % desconto outros | numeric |
desconto_total | desconto total | numeric |
perc_desconto_total | % desconto total | numeric |
pontos_ent | pontos (+) | int |
pontos_sai | pontos (-) | int |
data_hora_venda | data/hora da venda | timestamp |
cpf_caixa | cpf do caixa | text |
cpf_frentista | cpf do frentista | text |
recebimento | 'caixa' ou 'app' | text |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
{ "data": { "vendas": [ { "total_com_desconto": 0.01, "desconto_abast": 0, "unit_sem_desconto": 3.499, "perc_desconto_abast": 0, "total_sem_desconto": 0.01, "unit_com_desconto": 3.479, "pontos_sai": 0, "recebimento": "app", "id_venda": 1482, "abast_sem_desconto": 0.01, "perc_desconto_outros": 0, "desconto_total": 0, "nome_comb": "Etanol Comum", "data_hora_venda": "2019-12-06 16:39:50", "outros_com_desconto": 0, "id_comb": 9, "outros_sem_desconto": 0, "pontos_ent": 0, "cpf_frentista": "", "quantidade": 0.003, "perc_desconto_total": 0, "cpf_caixa": "", "desconto_outros": 0, "abast_com_desconto": 0.01 }, { "total_com_desconto": 169.29, "desconto_abast": 0.76, "unit_sem_desconto": 4.449, "perc_desconto_abast": 0.4, "total_sem_desconto": 170.05, "unit_com_desconto": 4.429, "pontos_sai": 0, "recebimento": "caixa", "id_venda": 1960, "abast_sem_desconto": 170.05, "perc_desconto_outros": 0, "desconto_total": 0.76, "nome_comb": "Gasolina Adit", "data_hora_venda": "2020-01-27 18:03:05", "outros_com_desconto": 0, "id_comb": 2, "outros_sem_desconto": 0, "pontos_ent": 38, "cpf_frentista": "", "quantidade": 38.222, "perc_desconto_total": 0.4, "cpf_caixa": "", "desconto_outros": 0, "abast_com_desconto": 169.29 } ], "data_hora": "2020-02-06 14:02:50" }, "status": "ok" }
Registrar venda
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
token (obrigatório) | token gerado no aplicativo pelo usuário | text |
id_comb (padrão: 0) | id do combustível (tabela 1) ou 0 (zero) quando tiver apenas outros | int |
total_abast (padrão: 0) | total abastecimento s/ desconto em R$ | numeric |
total_outros (padrão: 0) | total outros s/ desconto em R$ | numeric |
placa (padrão: '') | placa do veículo | text |
quilometragem (padrão: 0) | quilometragem do veículo | int |
recebimento (padrão: 'app') | 'caixa' ou 'app' | text |
cpf_caixa (padrão: '') | cpf do caixa | text |
cpf_frentista (padrão: '') | cpf do frentista | text |
acao (padrão: 'validar') | 'validar' ou 'registrar' | text |
id_venda | id da venda | int |
id_comb | id do combustível (tabela 1) | int |
nome_comb | nome do combustível (tabela 1) | text |
quantidade | quantidade de litros ou m³ | numeric |
unit_sem_desconto | unitário s/ desconto | numeric |
abast_sem_desconto | abastecimento s/ desconto | numeric |
outros_sem_desconto | outros s/ desconto | numeric |
total_sem_desconto | total s/ desconto | numeric |
unit_com_desconto | unitário c/ desconto | numeric |
abast_com_desconto | abastecimento c/ desconto | numeric |
outros_com_desconto | outros c/ desconto | numeric |
total_com_desconto | total c/ desconto | numeric |
desconto_abast | desconto abastecimento | numeric |
desconto_outros | desconto outros | numeric |
desconto_total | desconto total | numeric |
cpf_caixa | cpf do caixa | text |
cpf_frentista | cpf do frentista | text |
placa | placa do veículo | text |
quilometragem | quilometragem do veículo | int |
recebimento | 'caixa' ou 'app' | text |
acao | 'validar' ou 'registrar' | text |
token | token gerado no aplicativo do usuário | text |
cartao | cartão do usuário | text |
valor_pago_saldo | valor pago com saldo disponível do usuário | numeric |
valor_pago_cartao | valor pago com cartão de crédito do usuário | numeric |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
* caso o total_abast enviado tenha mais de 2 (duas) casas decimais o mesmo será arredondado
* caso o total_outros enviado tenha mais de 2 (duas) casas decimais o mesmo será arredondado
{ "data": { "valor_pago_saldo": 0, "desconto_total": 2.87, "outros_com_desconto": 0, "id_comb": 11, "outros_sem_desconto": 0, "quantidade": 28.665, "placa": "XXX9999", "abast_com_desconto": 54.46, "total_com_desconto": 54.46, "desconto_abast": 2.87, "unit_sem_desconto": 2, "total_sem_desconto": 57.33, "unit_com_desconto": 1.9, "recebimento": "APP", "id_venda": 0, "abast_sem_desconto": 57.33, "token": "200200200200", "cartao": "MASTERCARD *** 9999 FULANO D TAL", "valor_pago_cartao": 54.46, "nome_comb": "GNV", "data_hora": "2020-02-07 15:04:51", "quilometragem": 123456, "cpf_frentista": "99999999999", "acao": "VALIDAR", "cpf_caixa": "99999999999", "desconto_outros": 0 }, "status": "ok" }
100100100100 200200200200 300300300300
Consultar tabela
Utilize este endpoint para consultar uma tabela
cnpj (obrigatório) | cnpj do estabelecimento | text |
senha (obrigatório) | senha do dia | text |
id_tabela (obrigatório) | id da tabela | int |
data_hora | data/hora da resposta | timestamp |
status | 'ok' ou 'error' | text |
* id_tabela = 1 (combustíveis)
Tabela 1 (combustíveis)
id_comb | nome_comb |
---|---|
7 | Diesel S10 Adit |
5 | Diesel S10 Comum |
8 | Diesel S500 Adit |
6 | Diesel S500 Comum |
10 | Etanol Adit |
9 | Etanol Comum |
11 | GNV |
2 | Gasolina Adit |
1 | Gasolina Comum |
3 | Gasolina Premium |
4 | Gasolina Premium Adit |
Contato
Caso ainda tenha dúvidas ou necessite de informações adicionais, ou ainda tenha encontrado algum erro ou deseje propor alguma mudança ou melhoria, entre em contato com nosso suporte através do e-mail suporte@gas4us.com ou pelo WhatsApp (41) 9 9701-1807.
powered by TX Fuel