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

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

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

NF-e (Recebida/Status)

Status das NF-e recebidas

{
    "recebida_status": [{
        "total": 1257,
        "pdf": 1254,
        "xml": 1254,
        "perc_pdf": 99.7,
        "confirmada": 1232,
        "perc_confirmada": 97.9,
        "json": 1254,
        "perc_json": 99.7,
        "perc_xml": 99.7
    }],
    "status": "ok"
}

{
    "data": [
        {
            "situacao": "AUTORIZADA",
            "numero": 128,
            "xml": "S",
            "chave": "52230741999488000124550010000001299901491668",
            "serie": 1,
            "emit_cnpj": "00089488000124",
            "dest_cnpj": "99944957000360",
            "manifesto": "CIÊNCIA",
            "data_emissao": "2023-07-25",
            "modal": "FERROVIÁRIO"
        },
        {
            "situacao": "AUTORIZADA",
            "numero": 130,
            "xml": "S",
            "chave": "52230741999488000124550010000001388801491755",
            "serie": 1,
            "emit_cnpj": "48889488000124",
            "dest_cnpj": "01777282002321",
            "manifesto": "CONFIRMADA",
            "data_emissao": "2023-07-25",
            "modal": "DUTOVIÁRIO"
        }
    ],
    "status": "ok"
}