APIs Integração Sistemas de Terceiros v. 0.0.9

Nossas APIs são aplicações REST e retornam os dados no formato JSON utilizando o charset UTF-8.

Utilizamos SSL (https) 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.

TODAS as requisições devem informar o A (id do aplicativo).

TODOS os endpoints e parâmetros são case-sensitive.

https://gas4us1.txfuel.com.br/api
https://gas4us2.txfuel.com.br/api

https://teste.txfuel.com.br/API_GAS4US/api

Tipos de dados

* caso você envie um parâmetro com valor e/ou formato inválido o mesmo será processado com seu valor padrão

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/terceiro/status?CNPJ={CNPJ do estabelecimento}&SENHA={SENHA do dia}&A={id do aplicativo}

* você também pode utilizar este endpoint para validar suas credenciais (CNPJ + SENHA do dia)

https://gas4us1.txfuel.com.br/api/v1/terceiro/status?CNPJ=25337354000157&SENHA=08642b70c3f06d8650c32ae8279db86b&A=1
https://gas4us2.txfuel.com.br/api/v1/terceiro/status?CNPJ=25337354000157&SENHA=08642b70c3f06d8650c32ae8279db86b&A=1

https://teste.txfuel.com.br/API_GAS4US/api/v1/terceiro/status?CNPJ=25337354000157&SENHA=08642b70c3f06d8650c32ae8279db86b&A=1

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            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 deixa 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

Como obter o A (id do aplicativo)?

Você deve solicitar o A (id do aplicativo) ao usuário master do estabelecimento.

Paginação

Algumas de nossas APIs tem um limite de retorno de 50 registros, caso o retorno desejado exceda o limite, você deverá enviar uma nova requisição para cada página, até conseguir todos os registros.

"param": {
        "_size": 50,
        "_pages": 3,
        "_page": 1,
        "_count": 107
    }

* No exemplo podemos observar que existem 107 registros, que ocupam 3 páginas e a página retornada é a de número 1.

Todas as APIs que suportam paginação irão retornar o objeto param, nele você encontra os dados abaixo:

_size indica o tamanho máximo do retorno

_pages indica a quantidade de páginas

_page indica a página retornada

_count indica a quantidade total de registros

* Você pode alterar o tamanho máximo, basta enviar na requisição o parâmetro size={tamanho do retorno} com um valor entre 1 e 50.

Preço bomba

Utilize esse endpoint para consultar e alterar o preço de bomba dos combustíveis

{
    "data": [
        {
            "preco_bomba": 0,
            "nome_comb": "Diesel S10 Adit",
            "id_comb": 7,
            "data_hora_atu": "1980-01-01 00:00:00"
        },
        {
            "preco_bomba": 6.44,
            "nome_comb": "Diesel S10 Comum",
            "id_comb": 5,
            "data_hora_atu": "2022-09-23 14:41:01"
        }
    ],
    "status": "ok"
}

{
    "data": [
        {
            "nome_comb": "Diesel S10 Comum",
            "data_hora_fim": "2022-12-01 23:59:00",
            "id_comb": 5,
            "preco_aplicativo": 6.39,
            "data_hora_inicio": "2022-11-25 00:32:00"
        },
        {
            "nome_comb": "Gasolina Comum",
            "data_hora_fim": "2022-11-25 23:59:00",
            "id_comb": 1,
            "preco_aplicativo": 4.49,
            "data_hora_inicio": "2022-11-25 00:30:00"
        }
    ],
    "status": "ok"
}

CONSULTAR uma agenda

{
    "data": [
        {
            "hora_final": "03:59:59",
            "valor": 0,
            "dia_da_semana": 0,
            "id_promocao_agenda": 261977,
            "hora_inicial": "00:00:00"
        },
        {
            "hora_final": "03:59:59",
            "valor": 0,
            "dia_da_semana": 1,
            "id_promocao_agenda": 258176,
            "hora_inicial": "00:00:00"
        },
        {
            "hora_final": "03:59:59",
            "valor": 0,
            "dia_da_semana": 2,
            "id_promocao_agenda": 259784,
            "hora_inicial": "00:00:00"
        },
        {
            "hora_final": "23:59:59",
            "valor": 0,
            "dia_da_semana": 6,
            "id_promocao_agenda": 258658,
            "hora_inicial": "20:00:00"
        }
    ],
    "status": "ok"
}

VALIDAR ou REGISTRAR uma agenda

VALIDAR ou REGISTRAR uma venda

Você pode utilizar qualquer token válido OU utilizar um dos tokens abaixo:

100100100100
200200200200
300300300300

CONSULTAR vendas

{
    "data": [{
        "total_com_desconto": 1248.13,
        "desconto_abast": 10,
        "unit_sem_desconto": 6.29,
        "perc_desconto_abast": 0.8,
        "total_sem_desconto": 1258.13,
        "unit_com_desconto": 6.24,
        "pontos_sai": 0,
        "recebimento": "app",
        "id_venda": 622297,
        "abast_sem_desconto": 1258.13,
        "perc_desconto_outros": 0,
        "desconto_total": 10,
        "nome_comb": "Diesel S500 Comum",
        "data_hora_venda": "2022-11-28 20:16:47",
        "outros_com_desconto": 0,
        "id_comb": 6,
        "outros_sem_desconto": 0,
        "pontos_ent": 200,
        "cpf_frentista": "",
        "quantidade": 200.021,
        "perc_desconto_total": 0.8,
        "cpf_caixa": "",
        "desconto_outros": 0,
        "abast_com_desconto": 1248.13
    }],
    "param": {
        "_size": 50,
        "_pages": 1,
        "_page": 1,
        "_count": 1
    },
    "status": "ok"
}

{
    "resume": {
        "taxa_meio_pagamento": 514577.85,
        "transferencia": 0,
        "caixa": 269163.6304,
        "entrada": 24845772.5704,
        "valor": 24845773.5704,
        "boleto": 605039,
        "outros": 0,
        "saida": 1,
        "deposito": 0,
        "cartao_de_credito": 23971570.94
    },
    "data": [{
        "data_hora_situacao": "2020-03-19 15:32:33",
        "taxa_meio_pagamento": 1.84,
        "tipo": "E",
        "pessoa": "FERNANDO HENRIQUES - 023.***.***-78",
        "fraude": "N",
        "meio_pagamento": "CARTÃO DE CRÉDITO",
        "valor": 100,
        "id_operacao_faturamento": 0,
        "id_tx_pessoa": 3588,
        "data_hora_operacao": "2020-03-19 15:32:28",
        "id_operacao": 5728,
        "parcelas": 0,
        "meio_pagamento_id": "ab47ea4d47bf4c10ac7fceeeccc6b644",
        "dados_pagamento": "MASTERCARD|7146|FERNANDO HENRIQUES",
        "valor_parcela": 0
    }],
    "param": {
        "_size": 50,
        "_pages": 1067,
        "_page": 1,
        "_count": 53315
    },
    "status": "ok"
}

{
    "resume": {
        "caixa_abastecimentos": 1,
        "total_outros_sem_desconto": 0,
        "desconto": 13.84,
        "total_sem_desconto": 622.17,
        "pontos_sai": 0,
        "valor_limite": 0,
        "valor_saldo": 6,
        "caixa_total": 1,
        "app_abastecimentos": 607.33,
        "desconto_abastecimento": 13.84,
        "valor_cartao": 601.33,
        "app_outros": 0,
        "total_abastecimento": 608.33,
        "perc_desconto_outros": 0,
        "total": 608.33,
        "caixa_outros": 0,
        "perc_desconto_abastecimento": 2.2,
        "perc_desconto": 2.2,
        "app_total": 607.33,
        "pontos_ent": 95,
        "total_abastecimento_sem_desconto": 622.17,
        "quantidade": 100.158,
        "total_outros": 0,
        "desconto_outros": 0
    },
    "data": [{
        "pessoa": "FULANO DE TAL - POSTO - XXX.***.***-XX",
        "fraude": "N",
        "desconto": 0,
        "pontos_sai": 0,
        "valor_limite": 0,
        "id_tx_pessoa": 3589,
        "valor_saldo": 0,
        "valor_cartao": 0,
        "id_operacao": 6410,
        "unitario": 3.199,
        "id_tx_estabelecimento": 93,
        "total": 1,
        "_count": 13,
        "caixa": "S",
        "perc_desconto": 0,
        "unitario_sem_desconto": 3.199,
        "pontos_ent": 0,
        "total_abastecimento_sem_desconto": 1,
        "quantidade": 0.313,
        "dados_cartao": "",
        "placa": "",
        "total_outros_sem_desconto": 0,
        "total_sem_desconto": 1,
        "desconto_abastecimento": 0,
        "data_hora_operacao": "2020-04-08 12:37:28",
        "id_produto": 5,
        "total_abastecimento": 1,
        "perc_desconto_outros": 0,
        "meio_pagamento_id": "",
        "produto": "Diesel S10 Comum",
        "perc_desconto_abastecimento": 0,
        "id_posto_convenio": 0,
        "estabelecimento": "ESTABELECIMENTO - UF",
        "quilometragem": 0,
        "posto_convenio": "",
        "total_outros": 0,
        "desconto_outros": 0,
        "id_operacao_cartao": 0
    }],
    "status": "ok"
}

{
    "resume": {
        "saldo_bloqueado": 0,
        "saldo_total": 0
    },
    "data": [{
        "estado": "UF",
        "_count": 1,
        "localidade": "LOCALIDADE",
        "bloqueado": true,
        "id_tx_pessoa": 15812,
        "celular": "(XX) X ****-XXXX",
        "apelido_nome_fantasia": "",
        "saldo": 4718.75,
        "nome_razao_social": "FULANO DE TAL",
        "cpf_cnpj": "XXX.***.***-XX",
        "email": "EMAIL@EMAIL.COM"
    }],
    "status": "ok"
}

{
    "data": [{
        "valor_promocao": 0,
        "rede": "",
        "pessoa": "FULANO DE TAL",
        "fraude": "N",
        "valor_posto_convenio": 0,
        "valor_limite": 0,
        "operacao_contrapartida_id": 0,
        "id_tx_pessoa": 3397,
        "valor_saldo": 0,
        "limite": "N",
        "manual": "N",
        "valor_cartao": 0,
        "taxas": 0,
        "id_operacao": 5733,
        "parcelas": 0,
        "id_tx_estabelecimento": 0,
        "caixa": "N",
        "litros": 0,
        "dados_pagamento": "",
        "id_tx_rede": 0,
        "id_meio_pagamento": 0,
        "bandeira": "",
        "placa": "",
        "data_hora_situacao": "2020-03-19 15:40:47",
        "nome_caixa": "",
        "meio_pagamento": "",
        "valor": 0.01,
        "saldo": 0.01,
        "data_hora_operacao": "2020-03-19 15:40:47",
        "id_produto": 0,
        "cashback": "N",
        "observacoes": "",
        "meio_pagamento_id": "",
        "meio_pagamento_proprio": "N",
        "nome_frentista": "",
        "produto": "",
        "id_posto_convenio": 0,
        "estabelecimento": "",
        "operacao": "TRANSFERÊNCIA",
        "quilometragem": 0,
        "valor_parcela": 0,
        "cpf_frentista": "",
        "posto_convenio": "",
        "cpf_caixa": "",
        "valor_bomba": 0
    }],
    "param": {
        "_size": 50,
        "_pages": 1,
        "_page": 1,
        "_count": 1
    },
    "status": "ok"
}

{
    "resume": {
        "valor": 4288.33,
        "valor_original": 4288.33
    },
    "data": [{
        "id_tx_estabelecimento": 66,
        "meio_pagamento_id": "845b686ba4534701bdbad63393e081a8",
        "data_hora_atualizacao": "2020-12-18 19:04:04",
        "banco_codigo": "341",
        "situacao": "succeeded",
        "data_hora_lancamento": "2020-12-18 14:02:03",
        "estabelecimento": "Posto Rodovia - Planalto - Governador Valadares/MG",
        "data_transferencia": "2020-12-18",
        "valor": 8.79,
        "banco_conta": "582912",
        "banco_agencia": "3180",
        "valor_original": 8.79
    }],
    "param": {
        "_size": 50,
        "_pages": 1,
        "_page": 1,
        "_count": 18
    },
    "status": "ok"
}

CONSULTAR cupom

VALIDAR ou REGISTRAR um consumo

{
    "data": [
        {
            "nome_comb": "Diesel S10 Adit",
            "id_comb": 7
        },
        {
            "nome_comb": "Diesel S10 Comum",
            "id_comb": 5
        },
        {
            "nome_comb": "Diesel S500 Adit",
            "id_comb": 8
        },
        {
            "nome_comb": "Diesel S500 Comum",
            "id_comb": 6
        },
        {
            "nome_comb": "Etanol Adit",
            "id_comb": 10
        },
        {
            "nome_comb": "Etanol Comum",
            "id_comb": 9
        },
        {
            "nome_comb": "Gasolina Adit",
            "id_comb": 2
        },
        {
            "nome_comb": "Gasolina Comum",
            "id_comb": 1
        },
        {
            "nome_comb": "Gasolina Premium",
            "id_comb": 3
        },
        {
            "nome_comb": "Gasolina Premium Adit",
            "id_comb": 4
        },
        {
            "nome_comb": "GNV",
            "id_comb": 11
        }
    ],
    "status": "ok"
}