Referência

Esta seção contém informações técnicas de referência, incluindo códigos de status HTTP, formatos de dados, observações importantes e detalhes de implementação.

Códigos de Status HTTP

A API retorna os seguintes códigos de status HTTP:

Código	Descrição	Quando Ocorre
200	OK	Requisição bem-sucedida
401	Unauthorized	Token inválido, expirado ou ausente
404	Not Found	Recurso não encontrado (endpoint ou ID inválido)
422	Unprocessable Entity	Erro de validação (dados inválidos no body)
500	Internal Server Error	Erro interno do servidor

Tratamento de Erros

Exemplo de tratamento de erros:

try {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    switch (response.status) {
      case 401:
        // Token inválido - fazer login novamente
        await reauthenticate();
        break;
      case 404:
        // Recurso não encontrado
        console.error('Recurso não encontrado');
        break;
      case 422:
        // Erro de validação
        const errors = await response.json();
        console.error('Erros de validação:', errors);
        break;
      case 500:
        // Erro do servidor
        console.error('Erro interno do servidor');
        break;
    }
    throw new Error(`HTTP ${response.status}`);
  }
  
  return await response.json();
} catch (error) {
  console.error('Erro na requisição:', error);
  throw error;
}

Formato de Datas

A API retorna datas em diferentes formatos dependendo do contexto:

ISO 8601

Formato padrão para timestamps com timezone:

2025-11-20T20:46:06.906Z

Formato MySQL

Formato usado em alguns campos:

2025-11-20 20:36:06

Conversão em JavaScript

// ISO 8601
const date1 = new Date('2025-11-20T20:46:06.906Z');

// Formato MySQL (precisa ajustar)
const mysqlDate = '2025-11-20 20:36:06';
const date2 = new Date(mysqlDate.replace(' ', 'T') + 'Z');

Valores Monetários

Os valores monetários são retornados como strings com alta precisão decimal para evitar problemas de arredondamento.

Exemplo:

{
  "amount": "0.250000000000000000"
}

Conversão e Cálculos

// Converter string para número
const amount = parseFloat("0.250000000000000000"); // 0.25

// Para cálculos precisos, use bibliotecas como decimal.js
const Decimal = require('decimal.js');
const amount1 = new Decimal("0.250000000000000000");
const amount2 = new Decimal("0.10");
const total = amount1.plus(amount2); // 0.35

Tipos de Chave PIX

A API suporta os seguintes tipos de chave PIX:

Tipo	Código	Formato	Exemplo
CPF	cpf	Apenas números	70059235373
CNPJ	cnpj	Apenas números	12345678000190
E-mail	email	E-mail válido	[email protected]
Telefone	phone	Formato internacional	+5521999999999
Chave Aleatória	evp	UUID	123e4567-e89b-12d3-a456-426614174000

Validação de Chaves

Exemplo de validação:

function validatePixKey(key, type) {
  switch (type) {
    case 'cpf':
      return /^\d{11}$/.test(key);
    case 'cnpj':
      return /^\d{14}$/.test(key);
    case 'email':
      return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(key);
    case 'phone':
      return /^\+\d{10,15}$/.test(key);
    case 'evp':
      return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(key);
    default:
      return false;
  }
}

Status de Cobranças

Status	Descrição	Ação Recomendada
pending	Pendente de pagamento	Continuar monitorando
paid	Paga	Processar confirmação
expired	Expirada	Criar nova cobrança se necessário
cancelled	Cancelada	Não será processada

Status de Transferências

Status	Descrição	Ação Recomendada
pending	Pendente	Continuar monitorando
paid	Concluída	Processo finalizado
failed	Falhou	Verificar motivo e tentar novamente
cancelled	Cancelada	Não será processada

Expiração de Cobranças

• Tempo padrão: 3600 segundos (1 hora)
• Campo: metadata.expires_in (em segundos)
• Data de expiração: metadata.expires_at (ISO 8601)

Verificação de Expiração

function isChargeExpired(charge) {
  const expiresAt = new Date(charge.metadata.expires_at);
  const now = new Date();
  return now > expiresAt;
}

// Verificar tempo restante
function getTimeRemaining(charge) {
  const expiresAt = new Date(charge.metadata.expires_at);
  const now = new Date();
  const remaining = expiresAt - now;
  return Math.max(0, Math.floor(remaining / 1000)); // segundos
}

Observações Importantes

1. Token de Autenticação

• O token retornado no login deve ser incluído em todas as requisições subsequentes
• Use o header: Authorization: Bearer {token}
• Se receber 401 Unauthorized, faça login novamente
• Nunca exponha tokens em código público ou repositórios

2. IDs de Conta

• Todos os endpoints requerem o account_id na URL
• Certifique-se de usar o ID correto da conta
• O account_id pode ser obtido nas informações do usuário após login

3. Referências

• Tanto cobranças quanto transferências retornam um campo reference
• Armazene a referência para consultas de status posteriores
• A referência é única e não pode ser alterada

4. Valores Monetários

• Os valores são retornados como strings com alta precisão
• Em operações matemáticas, converta para número decimal
• Para cálculos precisos, use bibliotecas de precisão decimal

5. Tipos de Chave PIX

• Sempre use o formato correto para cada tipo de chave
• CPF e CNPJ devem conter apenas números (sem pontos, traços ou barras)
• Telefone deve estar no formato internacional com código do país

6. Formato de Datas

• As datas podem estar em diferentes formatos (ISO 8601 ou MySQL)
• Sempre converta para o formato adequado na sua aplicação
• Considere timezone ao trabalhar com datas

7. Rate Limiting

Nota

A API pode ter limites de taxa (rate limiting). Se receber muitos erros 429 Too Many Requests, implemente um sistema de retry com backoff exponencial.

Exemplo de Implementação Completa

class FinexisAPI {
  constructor(accountId) {
    this.accountId = accountId;
    this.baseUrl = 'https://app.finexis.com.br/api/v1/gateway';
    this.token = null;
  }
  
  async login(username, apiKey) {
    const payload = Buffer.from(`${username}:${apiKey}`).toString('hex');
    
    const response = await fetch(`${this.baseUrl}/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ payload })
    });
    
    if (!response.ok) throw new Error(`Login failed: ${response.status}`);
    
    const data = await response.json();
    this.token = data.data.token;
    return data;
  }
  
  async request(endpoint, options = {}) {
    if (!this.token) throw new Error('Not authenticated');
    
    const url = `${this.baseUrl}${endpoint}`;
    const headers = {
      'Authorization': `Bearer ${this.token}`,
      'Content-Type': 'application/json',
      ...options.headers
    };
    
    const response = await fetch(url, { ...options, headers });
    
    if (response.status === 401) {
      throw new Error('Token expired - please login again');
    }
    
    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new Error(`API Error: ${response.status} - ${error.message || 'Unknown error'}`);
    }
    
    return await response.json();
  }
  
  async getAccountInfo() {
    return this.request(`/account/${this.accountId}/info`);
  }
  
  async createCharge(amount, description) {
    return this.request(`/account/${this.accountId}/charge/pix/create`, {
      method: 'POST',
      body: JSON.stringify({ amount, description, currency: 'BRL' })
    });
  }
  
  async checkChargeStatus(reference) {
    return this.request(`/account/${this.accountId}/charge/pix/status?reference=${reference}`);
  }
  
  async createTransfer(pixKey, pixType, amount) {
    return this.request(`/account/${this.accountId}/transfer/pix/create`, {
      method: 'POST',
      body: JSON.stringify({ pix_key: pixKey, pix_type: pixType, amount })
    });
  }
  
  async checkTransferStatus(reference) {
    return this.request(`/account/${this.accountId}/transfer/pix/status?reference=${reference}`);
  }
}

Suporte

Para mais informações ou suporte técnico, entre em contato com a equipe Finexis.

---

Última atualização: Novembro 2025