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.
URL de produção (url_base)
https://zp1.txfuel.com.br/api
https://zp2.txfuel.com.br/apiURL de testes (sandbox)
https://teste.txfuel.com.br/API_ZP/api| TIPO | FORMATO | EXEMPLO |
|---|---|---|
| text | ZP | |
| int | 1975 | |
| numeric | 2972.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 |
| boolean | S=TRUE, N=FALSE | S ou N |
| object | {"campo": valor} | {"nome": "JOAO"} |
* caso você envie um parâmetro com valor e/ou formato inválido o mesmo será processado com seu valor padrão
Nossas APIs suportam os seguintes métodos de requisição HTTP:
POST
Utilizado para adicionar um recurso específico.
GET
Solicita a representação de um recurso específico.
PUT
Utilizado para atualizar um recurso específico.
DELETE
Utilizado para deletar um recurso específico.
200
Sucesso! Deu tudo certo com a requisição.
400
Requisição errada! Um ou mais parâmetros da sua requisição não estão de acordo com o esperado. Verifique se os parâmetros foram enviados com valor e formato correto.
401
Não autorizado! Verifique se foi informado corretamente o CNPJ do estabelecimento, a SENHA do dia e o A (id do aplicativo). Verifique também se o IDENTIFICADOR utilizado para gerar a senha do dia ainda é válido (consulte o usuário master do estabelecimento).
404
Não encontrado! Verifique o endereço requisitado.
405
Não suportado! Verifique o método utilizado.
429
Limite de requisições ultrapassado! Você fez mais requisições do que o permitido. Aguarde alguns minutos e tente novamente.
500
Erro interno! Algo não está funcionando como deveria. Solicite ajuda ao nosso suporte através do e-mail suporte@txfuel.com.br ou pelo WhatsApp (41) 9 9701-1807.
503
Serviço indisponível! Por algum motivo as APIs estão indisponíveis neste momento. Aguarde alguns minutos, se o problema persistir, solicite ajuda ao nosso suporte através do e-mail suporte@txfuel.com.br ou pelo WhatsApp (41) 9 9701-1807.
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}
Endpoint
/v1/terceiro/status
Método
GET
Parâmetros
| CNPJ (obrigatório) | CNPJ do estabelecimento | text |
| SENHA (obrigatório) | SENHA do dia | text |
| A (obrigatório) | id do aplicativo | int |
Respostas
| status | 'ok' ou 'error' | text |
* você também pode utilizar este endpoint para validar suas credenciais (CNPJ + SENHA do dia)
URL de produção (url_base)
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=1URL de teste (sandbox)
https://teste.txfuel.com.br/API_ZP/api/v1/terceiro/status?CNPJ=25337354000157&SENHA=08642b70c3f06d8650c32ae8279db86b&A=1Você deve solicitar o CNPJ ao usuário master do estabelecimento.
Você deve solicitar o IDENTIFICADOR ao usuário master do estabelecimento.
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.
Java
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);
}Dart
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);
}Node.JS
function getSenhaDia(identificador, cnpj) {
return require('crypto').createHash('md5').update(identificador + new Date().toISOString().slice(0, 10) + cnpj).digest("hex");
}Python
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())PHP
function getSenhaDia($identificador, $cnpj) {
return md5($identificador . date("Y-m-d") . $cnpj);
}PostgreSQL
select md5(
'd563eef2d7354e1e8d080854d34574bf' || current_date || '25337354000157'
) as senha_diaMySQL
select md5(
concat('d563eef2d7354e1e8d080854d34574bf', curdate(), '25337354000157')
) as senha_diaVocê deve solicitar o A (id do aplicativo) ao usuário master do estabelecimento.
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.
Exemplo de retorno (json)
"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.