APIs Integração Sistemas de Terceiros v. 0.0.2

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://pwbase1.txfuel.com.br/api
https://pwbase2.txfuel.com.br/api

https://teste.txfuel.com.br/API_PWBASE/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://pwbase1.txfuel.com.br/api/v1/terceiro/status?CNPJ=25337354000157&SENHA=08642b70c3f06d8650c32ae8279db86b&A=1
https://pwbase2.txfuel.com.br/api/v1/terceiro/status?CNPJ=25337354000157&SENHA=08642b70c3f06d8650c32ae8279db86b&A=1

https://teste.txfuel.com.br/API_PWBASE/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.

Veículo

Cadastro do veículo

{
    "validade_vistoria": "2023-01-31",
    "id_veiculo": 6126,
    "tipo": "TRUCK",
    "validade_certificado": "2021-12-04",
    "capacidade": 15000,
    "bloqueado": "N",
    "compartimentos": 4,
    "placa": "MNW9B39",
    "status": "ok"
}

{
    "validade_integracao": "2023-01-31",
    "id_motorista": 3587,
    "categoria_cnh": "AD",
    "cpf": "99999999999",
    "validade_nr20": "2022-11-11",
    "validade_mopp": "2025-10-30",
    "bloqueado": "N",
    "nome": "FULANO DE TAL",
    "validade_nr35": "2022-11-09",
    "validade_cnh": "2021-10-17",
    "status": "ok"
}

{
    "data": [
        {
            "tipo": "P",
            "apelido": "B100",
            "aditivado": "N",
            "grupo": "DIESEL",
            "padrao": "B100",
            "nome": "BIODIESEL",
            "simp": "820101001",
            "id_produto": 68
        },
        {
            "tipo": "C",
            "apelido": "GAS C ADT",
            "aditivado": "S",
            "grupo": "GASOLINA",
            "padrao": "GAS C",
            "nome": "GASOLINA C ADITIVADA",
            "simp": "320102002",
            "id_produto": 57
        }
    ],
    "param": {
        "_size": 50,
        "_pages": 1,
        "_page": 1,
        "_count": 2
    },
    "status": "ok"
}

{
    "data": [{
        "tipo": "C",
        "situacao": "O",
        "vistoria": "N",
        "id_motorista": 3587,
        "variacao_remessa": 0,
        "tempo_aguardando": "00:00:21",
        "tempo_operacao": "03:38:53",
        "quantidade_liberada_abastecimento": 0,
        "id_fornecedor": 0,
        "fator_de_correcao": 0,
        "metodo": "L",
        "volume_a_20_remessa": 0,
        "id_ordem": 102632,
        "modal": "R",
        "tempo_vistoria": "00:00:00",
        "transferencia": "N",
        "frascos_necessarios": 1,
        "data_hora_vistoria": "1980-01-01 00:00:00",
        "coletar_amostras": 1,
        "data_hora_operacao": "2022-06-07 12:02:08",
        "id_produto": 0,
        "transportadora": "",
        "cliente": "CLIENTE - SENADOR CANEDO/GO",
        "produto_abastecimento": "",
        "id_veiculo": 6071,
        "volume_a_20": 0,
        "codigo_interno": "",
        "id_operador": 0,
        "complementar_retirar": 0,
        "produtos": "EH",
        "data_movimento": "2022-06-07",
        "volume_ambiente_remessa": 0,
        "data_hora_finalizada": "1980-01-01 00:00:00",
        "densidade_a_20": 0,
        "operador": "",
        "massa": 0,
        "nota_fiscal": "",
        "data_hora_cancelada": "1980-01-01 00:00:00",
        "id_produto_abastecimento": 0,
        "validade_inicial": "1980-01-01 00:00:00",
        "volume_a_20_apurado": 0,
        "quantidade_efetuada_abastecimento": 0,
        "descarte": 0,
        "densidade_amostra": 0,
        "temperatura": 0,
        "grau_inpm": 0,
        "volume_ambiente": 0,
        "data_hora_aguardando": "2022-06-07 12:01:46",
        "veiculo": "AJB0915/10000L/4C",
        "temperatura_amostra": 0,
        "id_cliente": 119,
        "tempo_total": "03:39:15",
        "data_hora_pendente": "2022-06-07 10:30:38",
        "cheio_balanca": 0,
        "validade_final": "2099-12-31 23:59:59",
        "grau_gl": 0,
        "produto": "",
        "id_nota_fiscal": 0,
        "motorista": "FULANO DE TAL (FULANO) - 023.***.***-97",
        "id_transportadora": 0,
        "fornecedor": "",
        "vazio_balanca": 0
    }],
    "param": {
        "_size": 50,
        "_pages": 1,
        "_page": 1,
        "_count": 1
    },
    "status": "ok"
}

{
    "data": [{
        "saldo_ant_dif": 7350,
        "saldo_ant_fiscal": 207318,
        "id_cliente": 141,
        "entrada_fiscal": 0,
        "id_produto": 67,
        "entrada_fisico": 0,
        "entrada_dif": 0,
        "cliente": "CLIENTE - PALMAS/TO",
        "saida_fisico": 0,
        "saldo_fisico": 199968,
        "produto": "GAS A",
        "saldo_dif": 7350,
        "saida_fiscal": 0,
        "saida_dif": 0,
        "dia": "2022-06-04",
        "saldo_ant_fisico": 199968,
        "saldo_fiscal": 207318
    }],
    "param": {
        "_size": 50,
        "_pages": 1,
        "_page": 1,
        "_count": 1
    },
    "status": "ok"
}