📋 Documentação da API

Velloz Net v3.0.0

📖 Índice

🔧 Informações Gerais

URL Base https://api.velloz.net
Versão 3.0.0
Autenticação Bearer Token (JWT)
Content-Type application/json

🔐 Autenticação

Todos os endpoints requerem autenticação via Bearer Token no cabeçalho:

Header de Autenticação
Authorization: Bearer <seu-token-jwt>

1. 🎯 Endpoint: GET TOKEN

Descrição: Obtém um token disponível do tipo especificado usando sistema de fila FIFO. Aguarda até 30 segundos por um token disponível caso não haja nenhum imediatamente disponível.

📊 Informações do Endpoint

Método POST
URL /get-token
Timeout 30 segundos
Rate Limit Conforme limite do plano do usuário (padrão: 10 req/min)

📝 Parâmetros de Entrada

Body (JSON)

Campo Tipo Obrigatório Descrição
user_id string ✅ Identificador do usuário (1-100 caracteres)
tipo string ✅ Tipo de token desejado (NFE ou CTE)

🔧 Exemplo de Requisição

cURL
curl -X POST "https://api.velloz.net/get-token" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "cliente123",
    "tipo": "NFE"
  }'

✅ Resposta de Sucesso (200 OK)

JSON Response
{
  "id": 12345,
  "guid": "550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tipo": "NFE",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
  "dataCriacao": "2024-01-15T10:30:00Z",
  "dataExpiracao": "2024-01-15T10:31:30Z",
  "usuarioSolicitante": "cliente123",
  "criadoPor": "usuario_criador"
}

📋 Campos da Resposta

Campo Tipo Descrição
id integer ID único do token no banco de dados
guid string Identificador único global (UUID)
token string O token propriamente dito
tipo string Tipo do token (sempre em MAIÚSCULA)
userAgent string User agent do cliente que criou o token
dataCriacao string Data/hora de criação (formato ISO 8601)
dataExpiracao string Data/hora de expiração (formato ISO 8601)
usuarioSolicitante string ID do usuário que solicitou o token
criadoPor string ID do usuário que criou o token

❌ Códigos de Erro

Código Descrição Exemplo de Resposta
401 Token de autenticação inválido {"detail": "Token inválido ou expirado"}
402 Créditos insuficientes {"detail": "Créditos insuficientes. Necessário: 1, Disponível: 0"}
404 Nenhum token disponível no timeout {"detail": "Timeout: Nenhum token do tipo 'NFE' ficou disponível em 30 segundos"}
429 Rate limit excedido {"detail": "Limite de 10 requisições por minuto excedido"}
500 Erro interno do servidor {"detail": "Erro ao aguardar token"}
  • Fila FIFO: Se não houver token disponível imediatamente, o usuário é colocado em uma fila
  • Timeout: Aguarda até 30 segundos por um token disponível

2. 💰 Endpoint: CONSULTAR SALDO

Descrição: Consulta o saldo atual de créditos do usuário autenticado, incluindo informações detalhadas sobre o plano, gastos e status do saldo.

📊 Informações do Endpoint

Método GET
URL /creditos/saldo
Autenticação Bearer Token
Rate Limit Conforme limite do plano do usuário

📝 Parâmetros de Entrada

Nenhum parâmetro necessário - utiliza informações do usuário autenticado.

🔧 Exemplo de Requisição

cURL
curl -X GET "https://api.velloz.net/creditos/saldo" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json"

✅ Resposta de Sucesso (200 OK)

JSON Response
{
  "user_id": "cliente123",
  "nome": "João Silva",
  "saldo_atual": 850,
  "creditos_iniciais": 1000,
  "creditos_gastos": 150,
  "custo_por_token": 1.0,
  "plano": "PRO",
  "data_renovacao": "2024-02-15T00:00:00Z",
  "status_saldo": "ok",
  "tokens_que_pode_consumir": 850,
  "porcentagem_gasta": 15.0
}

📋 Campos da Resposta

Campo Tipo Descrição
user_id string Identificador único do usuário
nome string Nome do usuário
saldo_atual integer Créditos disponíveis atualmente
creditos_iniciais integer Créditos iniciais do período atual
creditos_gastos integer Total de créditos já gastos
custo_por_token float Custo em créditos por token
plano string Nome do plano atual
data_renovacao string Data de renovação do plano (ISO 8601)
status_saldo string Status do saldo: ok, warning, critical
tokens_que_pode_consumir integer Quantidade de tokens que pode consumir
porcentagem_gasta float Percentual de créditos já gastos

📊 Status do Saldo

Status Descrição Condição
ok Saldo adequado Mais de 50 créditos
warning Saldo baixo Entre 11-50 créditos
critical Saldo crítico 10 créditos ou menos

3. 📊 Endpoint: CONSULTAR SALDO SIMPLES

Descrição: Versão simplificada da consulta de saldo, retornando apenas informações essenciais.

📊 Informações do Endpoint

Método GET
URL /creditos/saldo-simples

🔧 Exemplo de Requisição

cURL
curl -X GET "https://api.velloz.net/creditos/saldo-simples" \
  -H "Authorization: Bearer SEU_TOKEN_JWT"

✅ Resposta de Sucesso (200 OK)

JSON Response
{
  "user_id": "cliente123",
  "nome": "João Silva",
  "saldo_atual": 850,
  "status_saldo": "ok",
  "tokens_que_pode_consumir": 850
}

🔧 Exemplos de Integração

🐍 Python (requests)

Python
import requests

# Configuração
BASE_URL = "https://api.velloz.net"
TOKEN = "SEU_TOKEN_JWT"
headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Consultar saldo
response = requests.get(f"{BASE_URL}/creditos/saldo", headers=headers)
saldo = response.json()
print(f"Saldo atual: {saldo['saldo_atual']} créditos")

# Obter token
payload = {
    "user_id": "cliente123",
    "tipo": "NFE"
}
response = requests.post(f"{BASE_URL}/get-token", json=payload, headers=headers)
token_data = response.json()
print(f"Token obtido: {token_data['token']}")

🟨 JavaScript (fetch)

JavaScript
const BASE_URL = 'https://api.velloz.net';
const TOKEN = 'SEU_TOKEN_JWT';

const headers = {
  'Authorization': `Bearer ${TOKEN}`,
  'Content-Type': 'application/json'
};

// Consultar saldo
fetch(`${BASE_URL}/creditos/saldo`, { headers })
  .then(response => response.json())
  .then(data => console.log('Saldo:', data.saldo_atual));

// Obter token
fetch(`${BASE_URL}/get-token`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    user_id: 'cliente123',
    tipo: 'NFE'
  })
})
.then(response => response.json())
.then(data => console.log('Token:', data.token));

🐘 PHP (cURL)

PHP
<?php
$baseUrl = 'https://api.velloz.net';
$token = 'SEU_TOKEN_JWT';

$headers = [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
];

// Consultar saldo
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/creditos/saldo');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$saldo = json_decode($response, true);
echo "Saldo atual: " . $saldo['saldo_atual'] . " créditos\n";

// Obter token
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/get-token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'user_id' => 'cliente123',
    'tipo' => 'NFE'
]));
$response = curl_exec($ch);
$tokenData = json_decode($response, true);
echo "Token: " . $tokenData['token'] . "\n";
curl_close($ch);
?>

⚠️ Considerações Importantes

🚦 Rate Limiting

  • Cada plano tem um limite de requisições por minuto
  • Limite padrão: 10 requisições/minuto
  • Exceder o limite resulta em erro 429

💳 Gestão de Créditos

  • Cada token consumido debita créditos do usuário
  • Consulte sempre o saldo antes de fazer muitas requisições
  • Monitore o status_saldo para evitar interrupções

⏱️ Timeouts

  • Endpoint get-token: 30 segundos de timeout
  • Recomenda-se implementar retry logic para casos de timeout

📋 Fila FIFO

  • Se não houver tokens disponíveis, o usuário entra em fila
  • A posição na fila é baseada na ordem de chegada
  • Tokens ficam disponíveis conforme outros usuários os criam