Documentação API

Introdução

A API EZCale permite processar pagamentos com divisão automática entre múltiplos destinatários. Nossa infraestrutura lida com validação, split, contabilização e liquidação de forma transparente.

Base URL de produção: https://api.ezcale.com/v1
Base URL de sandbox: https://sandbox-api.ezcale.com/v1

Autenticação

A API EZCale utiliza API keys para autenticar requisições. Todas as chamadas devem incluir sua chave no header Authorization.

curl https://plataforma.ezcale.com/p/api/endpoint.php \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Gerencie suas API keys no painel de controle.

API Keys

API keys são credenciais que permitem integrar sua aplicação com a plataforma EZCale. Existem dois ambientes:

• Test: Para desenvolvimento e testes (sk_test_...)
• Live: Para produção (sk_live_...)

Criar API Key

Cria uma nova API key para autenticação.

{
  "success": true,
  "message": "API Key criada com sucesso",
  "api_key": "sk_production_abc123...",
  "api_secret": "secret_xyz789...",
  "environment": "production"
}

⚠️ Importante: A chave completa é exibida apenas uma vez na criação. Guarde-a em local seguro.

Ativar API Key

Ativa uma API key previamente desativada.

Revogar API Key

Revoga uma API key imediatamente. Todas as requisições com esta key falharão.

Deletar API Key

Remove permanentemente uma API key (soft delete).

Boas Práticas

• Nunca compartilhe suas API keys em repositórios públicos
• Use variáveis de ambiente para armazenar keys
• Crie keys separadas por aplicação/serviço
• Revogue imediatamente keys comprometidas
• Rode keys periodicamente (a cada 90 dias)
• Use keys de test durante desenvolvimento

Gestão de Segurança

A API de gestão de segurança permite gerenciar credenciais biométricas, dispositivos confiáveis e histórico de acessos do usuário.

Listar Credenciais WebAuthn

Lista todas as credenciais biométricas (Touch ID, Face ID, Windows Hello) cadastradas pelo usuário.

{
  "success": true,
  "credentials": [
    {
      "id": "AQIDBAUGBwg...",
      "name": "MacBook Pro Touch ID",
      "created_at": "2025-10-15 09:30:00",
      "last_used": "2025-11-08 10:15:00",
      "device_info": "macOS Safari"
    },
    {
      "id": "CAkKCwwNDg8Q...",
      "name": "iPhone 14 Face ID",
      "created_at": "2025-11-01 14:20:00",
      "last_used": "2025-11-08 08:45:00",
      "device_info": "iOS Safari"
    }
  ]
}

Remover Credencial Biométrica

Renomear Credencial

Listar Dispositivos Confiáveis

Lista dispositivos que foram marcados como confiáveis (skip MFA).

{
  "success": true,
  "devices": [
    {
      "id": 45,
      "name": "MacBook Pro - Chrome",
      "fingerprint": "abc123def456...",
      "last_used": "2025-11-08 10:00:00",
      "ip": "192.168.1.100",
      "location": "São Paulo, BR"
    }
  ]
}

Remover Dispositivo Confiável

Histórico de Login

Retorna o histórico de acessos do usuário (sucessos e falhas).

{
  "success": true,
  "history": [
    {
      "timestamp": "2025-11-08 10:15:30",
      "status": "success",
      "method": "webauthn",
      "device": "MacBook Pro - Safari",
      "ip": "192.168.1.100",
      "location": "São Paulo, BR"
    },
    {
      "timestamp": "2025-11-07 18:30:15",
      "status": "failed",
      "method": "password",
      "device": "iPhone 14 - Safari",
      "ip": "192.168.1.50",
      "location": "São Paulo, BR",
      "reason": "invalid_password"
    }
  ]
}

Códigos de Status

Estabelecimentos - Onboarding

O processo de onboarding permite cadastrar novos estabelecimentos comerciais (Pessoa Física ou Jurídica) na plataforma através de links únicos e temporários.

Gerar Link de Cadastro

Gera um link único e temporário para onboarding de um novo estabelecimento.

{
  "success": true,
  "link": "https://plataforma.ezcale.com/cadastro/ABC123XYZ789",
  "hash": "ABC123XYZ789",
  "expires_at": "2025-11-15 23:59:59",
  "type": "pj"
}

Processar Cadastro

Processa o cadastro completo de um estabelecimento PF ou PJ.

Parâmetros Pessoa Física:

Parâmetros Pessoa Jurídica:

{
  "hash": "ABC123XYZ789",
  "cnpj": "12345678000199",
  "razao_social": "Empresa Exemplo LTDA",
  "nome_fantasia": "Empresa Exemplo",
  "telefone": "11999999999",
  "endereco": {
    "cep": "01310100",
    "logradouro": "Avenida Paulista",
    "numero": "1000",
    "complemento": "Sala 101",
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "estado": "SP"
  },
  "representante_legal": {
    "nome_completo": "João Silva",
    "cpf": "12345678901",
    "data_nascimento": "1985-05-15",
    "telefone": "11988888888"
  }
}

Validações: CPF/CNPJ válidos, maioridade (PF), dados bancários, documentos obrigatórios

Analytics do Link

Retorna métricas de conversão do link de cadastro.

{
  "success": true,
  "analytics": {
    "views": 45,
    "conversions": 1,
    "conversion_rate": 2.22,
    "avg_time_to_complete": "12:34:00",
    "abandonment_rate": 97.78,
    "last_view": "2025-11-08 10:15:00"
  }
}

Revogar Link

Revoga um link de cadastro antes do vencimento.

Estabelecimentos - Gestão de Dados

APIs para atualização de dados cadastrais do estabelecimento após aprovação.

Atualizar Dados do EC (Multi-Seção)

Endpoint unificado para atualização de múltiplas seções do cadastro.

Seções suportadas:

• company_data - Dados da empresa
• address - Endereço
• contacts - Contatos
• bank_data - Dados bancários
• pix_key - Chave PIX
• legal_responsible - Responsável legal

Atualizar Dados da Empresa

Atualizar Endereço

Atualizar Dados Bancários

Atualizar Chave PIX

Estabelecimentos - Documentos

Gerenciamento de upload e validação de documentos obrigatórios para aprovação do estabelecimento.

Upload de Documento

Upload de documentos (multipart/form-data).

{
  "success": true,
  "document": {
    "id": 456,
    "category": "CNH",
    "filename": "cnh_frente.jpg",
    "size": 2048576,
    "status": "pending",
    "uploaded_at": "2025-11-08 10:30:00"
  }
}

Formatos aceitos: PDF, JPG, JPEG, PNG

Tamanho máximo: 10MB por arquivo

Deletar Documento

Remove um documento enviado (antes da aprovação).

Estabelecimentos - Aprovação e KYC

Processo de aprovação e validação de compliance do estabelecimento.

Listar Documentos para Aprovação

Lista todos os documentos enviados pelo estabelecimento.

{
  "success": true,
  "documents": [
    {
      "id": 123,
      "category": "CNH",
      "filename": "cnh_frente.jpg",
      "status": "pending",
      "uploaded_at": "2025-11-08 10:00:00",
      "url": "https://storage.ezcale.com/docs/..."
    },
    {
      "id": 124,
      "category": "Comprovante de Residência",
      "filename": "comprovante.pdf",
      "status": "approved",
      "uploaded_at": "2025-11-08 10:05:00",
      "approved_by": "admin@ezcale.com",
      "approved_at": "2025-11-08 11:00:00"
    }
  ]
}

Aprovar Documento

Ações realizadas:

• Atualiza status para 'approved'
• Registra usuário aprovador
• Cria log de auditoria
• Notifica estabelecimento

Rejeitar Documento

Aprovar Estabelecimento

Valida todos os requisitos e ativa o estabelecimento.

Validações antes de aprovar:

• ✅ Todos documentos obrigatórios aprovados
• ✅ Dados bancários validados
• ✅ Compliance OK
• ✅ KYC completo

Ações realizadas:

• Ativa o estabelecimento
• Cria contas financeiras
• Envia email de boas-vindas
• Registra auditoria completa
• Libera acesso ao painel

Aprovar Compliance

Aprova a análise de compliance do estabelecimento.

Log de Auditoria

Retorna histórico completo de ações realizadas no EC.

{
  "success": true,
  "logs": [
    {
      "timestamp": "2025-11-08 11:30:00",
      "user": "admin@ezcale.com",
      "action": "document_approved",
      "details": "CNH aprovada",
      "ip": "192.168.1.1"
    },
    {
      "timestamp": "2025-11-08 11:25:00",
      "user": "admin@ezcale.com",
      "action": "document_rejected",
      "details": "Comprovante ilegível - motivo: foto desfocada",
      "ip": "192.168.1.1"
    },
    {
      "timestamp": "2025-11-08 10:00:00",
      "user": "ec@exemplo.com",
      "action": "document_uploaded",
      "details": "Upload de CNH",
      "ip": "192.168.1.50"
    }
  ]
}

Estabelecimentos - Terminais

Gestão de terminais de pagamento (POS) associados ao estabelecimento.

Listar Terminais (Admin)

Lista todos os terminais cadastrados (visão administrativa).

Criar Terminal

Associar Terminal a EC

Configurar Terminal

Configura parâmetros operacionais do terminal.

Listar Terminais do EC

Lista terminais associados ao EC (visão do estabelecimento).

{
  "success": true,
  "terminals": [
    {
      "id": 789,
      "serial_number": "ABC123XYZ",
      "model": "D195",
      "status": "active",
      "associated_at": "2025-10-01 10:00:00",
      "last_transaction": "2025-11-08 09:45:00"
    }
  ]
}

Outras Actions Disponíveis

• dissociate - Desassociar terminal do EC
• delete - Deletar terminal
• quick_update - Atualização rápida de dados
• pairing - Parear dispositivo
• list_shadows - Listar terminais alternativos
• add_shadow - Adicionar terminal alternativo
• remove_shadow - Remover terminal alternativo

Conexões

O sistema de conexões da EZCale permite integrar estabelecimentos com diversos provedores de pagamento (adquirentes, gateways, bancos) através de um marketplace de conectores.

Conceitos principais:

• Conectores (SRConnectors): Templates disponíveis no marketplace (Stone, Cielo, Adyen, etc.) - gerenciados apenas por GOAT
• Conexões (SRConnections): Instâncias de conectores vinculadas a um estabelecimento específico, contendo credenciais e configurações

💡 Fluxo: GOAT cadastra conectores → ECs criam conexões baseadas nos conectores → Conexões são usadas no checkout para processar pagamentos

Conectores (Marketplace)

Conectores são templates de integração com provedores de pagamento. Apenas usuários GOAT podem criar, editar ou remover conectores do marketplace.

Listar Conectores Disponíveis

Lista todos os conectores disponíveis no marketplace (status: available ou beta).

{
  "success": true,
  "connectors": [
    {
      "id": 1,
      "name": "Stone",
      "type": "acquirer",
      "status": "available",
      "logo_url": "/assets/connectors/stone.svg",
      "description": "Gateway de pagamento Stone",
      "required_fields": ["api_key", "merchant_id"],
      "supports_pix": true,
      "supports_card": true
    },
    {
      "id": 2,
      "name": "Adyen",
      "type": "gateway",
      "status": "beta",
      "logo_url": "/assets/connectors/adyen.svg",
      "required_fields": ["api_key", "merchant_account"]
    }
  ]
}

Buscar Conector (GOAT Only)

Retorna detalhes completos de um conector específico.

Criar Conector (GOAT Only)

Cadastra novo conector no marketplace.

Atualizar Conector (GOAT Only)

Atualiza configurações de um conector existente.

Deletar Conector (GOAT Only)

Remove conector do marketplace (soft delete: vflag = 1).

⚠️ Importante: Deletar um conector não remove as conexões existentes dos ECs. Elas continuam funcionando normalmente.

Gestão de Conexões

Conexões são instâncias de conectores vinculadas a um estabelecimento. Cada EC pode ter múltiplas conexões ativas.

Criar Conexão

Cria nova conexão para o estabelecimento autenticado.

// Request
{
  "connector_id": 1,
  "name": "Stone - Loja Principal",
  "credentials": {
    "api_key": "sk_live_abc123...",
    "merchant_id": "12345678"
  },
  "is_production": true
}

// Response
{
  "success": true,
  "message": "Conexão criada com sucesso",
  "connection": {
    "id": 42,
    "connector_id": 1,
    "name": "Stone - Loja Principal",
    "status": "active",
    "is_production": true,
    "created_at": "2025-11-08 11:00:00"
  }
}

🔐 Segurança: Credenciais são criptografadas usando encryptData() antes de serem armazenadas no banco.

Atualizar Conexão

Atualiza dados de uma conexão existente.

Deletar Conexão

Remove conexão do estabelecimento (soft delete).

⚠️ Atenção: Conexões usadas em checkouts ativos não podem ser deletadas. Primeiro desative o checkout ou migre para outra conexão.

Testes e Métricas

APIs para validar conectividade com provedores e monitorar performance das conexões.

Testar Conexão

Valida se a conexão está funcional fazendo ping no provedor.

// Sucesso
{
  "success": true,
  "message": "Conexão válida",
  "test_result": {
    "status": "online",
    "response_time_ms": 145,
    "provider_status": "operational",
    "tested_at": "2025-11-08 11:30:00"
  }
}

// Falha
{
  "success": false,
  "message": "Falha na conexão",
  "test_result": {
    "status": "offline",
    "error": "Authentication failed: Invalid API key",
    "error_code": "AUTH_001",
    "tested_at": "2025-11-08 11:30:00"
  }
}

💡 Dica: Execute este teste após criar/atualizar conexões para validar credenciais antes de ativar no checkout.

Métricas de Conexão

Retorna estatísticas de performance da conexão.

{
  "success": true,
  "metrics": {
    "connection_id": 42,
    "period": "7d",
    "transactions": {
      "total": 1543,
      "successful": 1489,
      "failed": 54,
      "success_rate": 96.5
    },
    "volume": {
      "total_brl": 487320.50,
      "avg_ticket_brl": 315.80
    },
    "performance": {
      "avg_response_time_ms": 234,
      "p95_response_time_ms": 450,
      "uptime_percentage": 99.8
    },
    "errors": [
      {
        "code": "TIMEOUT",
        "count": 28,
        "percentage": 51.9
      },
      {
        "code": "AUTH_FAILED",
        "count": 18,
        "percentage": 33.3
      }
    ]
  }
}

Console de Testes de API

Cada conexão possui um console interativo para testar endpoints do provedor em tempo real, facilitando debug e validação de integração.

Acessar Console

Acesse o console através da página de detalhes da conexão (conexao_view.php?id={connection_id}) e clique em "API Console" no cabeçalho.

📍 URL: conexao_settings.php?id={connection_id}

Funcionalidades do Console

• Cards colapsáveis por endpoint: Organize endpoints por categoria (Onboarding, Payments, POS, etc.)
• Formulários dinâmicos: Parâmetros e body pré-preenchidos com exemplos
• Execução em tempo real: Chamadas diretas via proxy com timeout de 30s
• Timer visual: Contador de tempo decorrido com alerta aos 25s
• Copy cURL: Copie comando cURL completo para testar externamente
• Response formatado: JSON colorizado com status HTTP e metadata

Endpoints Cappta Disponíveis

API Proxy Backend

Endpoint interno usado pelo console para executar chamadas ao provedor. Garante autenticação, headers corretos e timeout.

// Request
{
  "connection_id": 42,
  "endpoint_id": "pos_list",
  "params": {},
  "body": null
}

// Response - Sucesso
{
  "success": true,
  "status": "200 OK",
  "response": {
    "data": [
      {
        "deviceId": "POS001",
        "serialNumber": "123456789",
        "model": "D195",
        "status": "active"
      }
    ]
  },
  "metadata": {
    "endpoint": "pos_list",
    "method": "GET",
    "url": "https://apiportal.posportal.com.br/api/hub/pos/device",
    "content_type": "application/json",
    "timestamp": "2025-11-21 14:30:00"
  }
}

// Response - Erro (403 Forbidden)
{
  "success": false,
  "status": "403 Forbidden",
  "response": {
    "_error": "Acesso negado pelo firewall/WAF da API",
    "_http_code": 403,
    "_raw_preview": "Access Denied - Reference: 18.4ce1dd17.173...",
    "_troubleshooting": "O IP do servidor pode não estar whitelisted, ou o token pode estar expirado/inválido."
  },
  "metadata": {
    "endpoint": "onboarding_list",
    "method": "GET",
    "url": "https://apiportal.posportal.com.br/api/hub/onboarding/...",
    "timestamp": "2025-11-21 14:31:00"
  }
}

🔒 Segurança: O proxy descriptografa credenciais automaticamente e injeta no header Authorization. Headers simulam Postman para evitar bloqueio por WAF.

Gerenciar Credenciais

Credenciais são editadas através de interface dedicada, acessível via botão "Edit" no card de credenciais.

📍 URL: conexao_edit_credentials.php?id={connection_id}

Atualizar Credenciais (API)

// Request
{
  "connection_id": 42,
  "credentials": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "merchant_key": "ABC123XYZ",
    "cnpj": "12345678000100"
  }
}

// Response
{
  "success": true,
  "message": "Credenciais atualizadas com sucesso"
}

💡 Dica: Use o console logo após atualizar credenciais para validar que estão corretas antes de integrar no checkout.

Connection Service Layer - Uso Programático

Camada de abstração para consumir endpoints de conectores a partir de qualquer módulo do sistema (ec_manager.php, checkout.php, webhooks, etc). Todas chamadas são automaticamente registradas em SRAPIMetrics via _guard.php.

Arquitetura

Business Logic (ec_manager.php, checkout.php)
    ↓
Connection Service Layer (functions/connections.php)
    ↓ executeConnectionEndpoint()
    ↓ getConnectionHealth()
    ↓ getActiveConnectionByType()
    ↓
API Proxy (api/conexao_api_proxy.php)
    ↓
External API (Cappta, Stone, Adyen)
    ↓
SRAPIMetrics (registro automático)

Função: executeConnectionEndpoint()

Executa endpoint de uma conexão com tratamento completo: descriptografia de credenciais, injeção de autenticação, timeout, retry e métricas.

Assinatura

executeConnectionEndpoint(
    int $connectionId,     // ID da conexão (SRConnections.id)
    string $operation,     // Nome da operação (ex: 'verify_merchant', 'pos_list')
    array $params,         // Parâmetros URL (substituem {placeholders})
    array|null $body       // Body JSON para POST/PUT (opcional)
) : array

Retorno

Exemplo 1: Verificar merchant antes de criar EC

<?php
// ec_manager.php - Validar CNPJ antes de criar estabelecimento
require_once(__DIR__ . '/functions/connections.php');

$cnpj = $_POST['cnpj'];

// Buscar conexão Cappta ativa
$conn = getActiveConnectionByType('Cappta');

if (!$conn) {
    throw new Exception('Conexão Cappta não encontrada');
}

// Verificar merchant na Cappta
$result = executeConnectionEndpoint(
    $conn['id'],
    'verify_merchant',
    array('cnpj' => $cnpj, 'resellerCnpj' => '44556706000100')
);

if (!$result['success']) {
    throw new Exception('Erro ao verificar merchant: ' . $result['error']);
}

if ($result['data']['status'] !== 'active') {
    throw new Exception('CNPJ não habilitado. Complete o onboarding.');
}

// Prosseguir com criação do EC...
echo "Merchant verificado com sucesso!";
?>

Exemplo 2: Processar pagamento PIX

<?php
// checkout.php - Processar pagamento
$conn = getActiveConnectionByType('Cappta');

$result = executeConnectionEndpoint(
    $conn['id'],
    'payment_pix',
    array(),  // Sem parâmetros URL
    array(    // Body JSON
        'merchantKey' => '{merchant_key}',  // Substituído automaticamente
        'amount' => 10000,
        'orderId' => 'ORDER-' . time()
    )
);

if ($result['success']) {
    $qrCode = $result['data']['qrCode'];
    $txnId = $result['data']['transactionId'];
    echo "QR Code PIX: " . $qrCode;
} else {
    echo "Erro: " . $result['error'];
}
?>

Função: getConnectionHealth()

Obtém métricas de saúde de uma conexão baseado em dados reais do SRAPIMetrics.

Assinatura

getConnectionHealth(
    int $connectionId,     // ID da conexão
    string $period         // Período: '24h', '7d', '30d' (padrão: '24h')
) : array

Retorno

Exemplo: Dashboard de status

<?php
$conn = getActiveConnectionByType('Cappta');
$health = getConnectionHealth($conn['id'], '7d');

echo "Status: " . $health['status'] . "\n";
echo "Success Rate: " . $health['success_rate'] . "%\n";
echo "Avg Latency: " . $health['avg_latency_ms'] . "ms\n";
echo "Total Calls (7d): " . $health['total_calls'] . "\n";

if ($health['status'] === 'offline') {
    echo "⚠️ ALERTA: Conexão offline!\n";
}
?>

Função: getActiveConnectionByType()

Busca conexão ativa por nome do conector. Útil quando você não sabe o ID da conexão.

Assinatura

getActiveConnectionByType(
    string $connectorName,     // Nome do conector (ex: 'Cappta', 'Stone')
    int|null $customerId       // ID do customer (usa sessão se null)
) : array|null

Retorno

array(
    'id' => 42,
    'name' => 'Cappta - Loja Principal',
    'idSRConnector' => 2,
    'connector_name' => 'Cappta POS',
    'status' => 'active'
)
// ou null se não encontrada

APIs REST

POST /api/connections/execute.php

API REST para executar endpoints de conexões via HTTP (útil para integrações externas).

// Request
{
  "connection_id": 42,
  "operation": "pos_list",
  "params": {},
  "body": null
}

// Response
{
  "success": true,
  "status": "200 OK",
  "data": [
    {
      "deviceId": "POS001",
      "serialNumber": "123456789",
      "model": "D195",
      "status": "active"
    }
  ],
  "error": null,
  "metadata": {
    "operation": "pos_list",
    "method": "GET",
    "url": "https://apiportal.posportal.com.br/api/hub/pos/device",
    "duration_ms": 234,
    "timestamp": "2025-11-21 14:30:00"
  }
}

GET /api/connections/health.php

API REST para obter métricas de saúde de uma conexão.

GET /api/connections/health.php?connection_id=42&period=7d

// Response
{
  "success": true,
  "connection_id": 42,
  "period": "7d",
  "health": {
    "total_calls": 1543,
    "success_rate": 96.5,
    "uptime": 96.5,
    "avg_latency_ms": 234,
    "min_latency_ms": 120,
    "max_latency_ms": 450,
    "error_count": 54,
    "last_call_at": "2025-11-21 14:30:00",
    "status": "online",
    "recent_errors": [...]
  }
}

Dashboard Health Integrado

O console de testes (conexao_settings.php) inclui seção de healthcheck no topo da página com:

• Status visual: 🟢 Online / 🟡 Degraded / 🔴 Offline
• Success Rate: Percentual de chamadas bem-sucedidas
• Uptime: Disponibilidade no período
• Avg Latency: Latência média em milissegundos
• Total Calls: Volume de requisições
• Errors: Total de erros com lista detalhada
• Filtros: 24h / 7d / 30d para análise de tendências

📊 Métricas em Tempo Real: Todas chamadas feitas via executeConnectionEndpoint() são registradas em SRAPIMetrics automaticamente pelo _guard.php. Use o API Monitor (/api_monitor.php) para análises avançadas.

Operações Disponíveis (Cappta)

📚 Documentação Completa: Consulte functions/CONNECTIONS_README.md para guia detalhado com mais exemplos e casos de uso.

KYC via Conexões

Alguns conectores oferecem processo de KYC (Know Your Customer) integrado. Estabelecimentos precisam completar o KYC do provedor antes de processar pagamentos.

Obter URL de KYC

Gera URL para o estabelecimento completar KYC no site do provedor.

{
  "success": true,
  "kyc_url": "https://provider.com/kyc/complete?token=abc123...",
  "expires_at": "2025-11-09 11:00:00",
  "status": "pending"
}

Aprovar KYC

Marca KYC como aprovado após validação no provedor (webhook ou consulta manual).

{
  "success": true,
  "message": "KYC aprovado com sucesso",
  "connection": {
    "id": 42,
    "kyc_status": "approved",
    "kyc_approved_at": "2025-11-08 12:00:00",
    "can_process_payments": true
  }
}

📌 Status de KYC:
• pending - Aguardando envio de documentos
• in_review - Em análise pelo provedor
• approved - Aprovado, pode processar pagamentos
• rejected - Rejeitado, documentação insuficiente
• not_required - Provedor não exige KYC

Checkout

O sistema de checkout da EZCale permite que estabelecimentos configurem múltiplas formas de pagamento, regras de split (divisão de valores) e gerenciem pontos de venda integrados.

Conceitos principais:

• Checkout: Configuração de ponto de venda (loja física, e-commerce, terminal)
• Métodos de Pagamento: Conexões ativas para cada método (PIX, cartão de crédito/débito)
• Split Rules: Regras de divisão automática de valores entre múltiplos recebedores
• Checkout Padrão: Configuração principal usada quando não especificado

💡 Fluxo: EC cria checkout → Configura métodos de pagamento (via conexões) → Define regras de split (opcional) → Ativa checkout → Processa transações

Métodos de Pagamento

Cada checkout pode ter diferentes métodos de pagamento habilitados, cada um usando uma conexão específica com provedor.

Configurar Métodos de Pagamento

Define quais métodos de pagamento estão disponíveis no checkout e qual conexão usar para cada um.

// Request
{
  "checkout_id": 42,
  "config": {
    "credit_card": {
      "idConnection": 10,
      "enabled": true
    },
    "debit_card": {
      "idConnection": 10,
      "enabled": true
    },
    "pix": {
      "idConnection": 15,
      "enabled": true
    },
    "boleto": {
      "idConnection": 15,
      "enabled": false
    }
  }
}

// Response
{
  "success": true,
  "message": "Métodos de pagamento configurados com sucesso",
  "config": {
    "credit_card": { "idConnection": 10, "enabled": true },
    "debit_card": { "idConnection": 10, "enabled": true },
    "pix": { "idConnection": 15, "enabled": true }
  }
}

Métodos Suportados

⚠️ Validação: A conexão especificada deve estar ativa, pertencer ao EC e suportar o método de pagamento escolhido.

Regras de Split

Split permite dividir automaticamente o valor de cada transação entre múltiplos recebedores (marketplace, afiliados, taxas de plataforma, etc.).

Configurar Split

Define regras de divisão de valores para o checkout.

Estrutura de uma Rule

// Request - Exemplo: Marketplace com taxa de 15% + taxa fixa de R$ 2,00
{
  "checkout_id": 42,
  "rules": [
    {
      "type": "fixed",
      "idSRCustomer": 1,  // Plataforma
      "amount_cents": 200,  // R$ 2,00
      "description": "Taxa de transação fixa",
      "priority": 1
    },
    {
      "type": "percentage",
      "idSRCustomer": 1,  // Plataforma
      "percentage": 15.0,
      "description": "Comissão marketplace",
      "priority": 2
    }
    // Restante vai para o EC dono do checkout (85% - R$ 2,00)
  ]
}

// Response
{
  "success": true,
  "message": "Regras de split configuradas com sucesso",
  "rules": [
    {
      "id": 123,
      "type": "fixed",
      "idSRCustomer": 1,
      "amount_cents": 200,
      "description": "Taxa de transação fixa",
      "priority": 1
    },
    {
      "id": 124,
      "type": "percentage",
      "idSRCustomer": 1,
      "percentage": 15.0,
      "description": "Comissão marketplace",
      "priority": 2
    }
  ],
  "validation": {
    "total_percentage": 15.0,
    "fixed_amount_cents": 200,
    "remaining_to_owner": "85% - R$ 2,00"
  }
}

Exemplo de Cálculo

Transação de R$ 100,00 com as regras acima:

1. Taxa fixa: R$ 2,00 → Plataforma recebe R$ 2,00
2. Base para %: R$ 100,00 - R$ 2,00 = R$ 98,00
3. 15% de R$ 98,00 = R$ 14,70 → Plataforma recebe R$ 14,70
4. Restante: R$ 98,00 - R$ 14,70 = R$ 83,30 → EC recebe R$ 83,30

⚠️ Validação:
• Soma dos percentuais não pode exceder 100%
• Taxas fixas são aplicadas antes dos percentuais
• Recebedores devem ser ECs válidos e ativos
• Priority define ordem de aplicação (menor = primeiro)

Gestão de Checkout

APIs para ativar/desativar checkouts e definir configuração padrão.

Ativar/Desativar Checkout

Alterna o status de um checkout entre ativo e inativo.

// Request
{
  "checkout_id": 42,
  "is_active": true
}

// Response
{
  "success": true,
  "message": "Checkout ativado com sucesso",
  "checkout": {
    "id": 42,
    "is_active": true,
    "updated_at": "2025-11-08 12:00:00"
  }
}

⚠️ Validação: Para ativar um checkout, é necessário ter ao menos um método de pagamento configurado e uma conexão válida.

Definir Checkout Padrão

Define qual checkout será usado como padrão quando não especificado na transação.

// Request
{
  "checkout_id": 42
}

// Response
{
  "success": true,
  "message": "Checkout definido como padrão",
  "default_checkout_id": 42
}

Deletar Checkout

Remove um checkout (soft delete).

⚠️ Atenção: Não é possível deletar um checkout que:
• É o checkout padrão (defina outro antes)
• Tem transações pendentes
• Está associado a um terminal ativo

Casos de Uso

Usuários e Perfis

Sistema de gestão de usuários, perfis de acesso (roles) e permissões granulares para controle de funcionalidades dentro do estabelecimento.

Conceitos principais:

• Usuário (SRUser): Pessoa com acesso à plataforma, vinculada a um estabelecimento
• Perfil (SRProfile): Template de permissões (Ex: Admin, Operador, Financeiro)
• Role: Nível hierárquico (Super Adm, Diretor, Gerente, Operador)
• Permissões: Controle granular de acesso por módulo e ação (view, create, edit, delete)

Gestão de Usuários

APIs para criar, editar, listar e gerenciar usuários de um estabelecimento.

Listar Usuários

Lista todos os usuários de um estabelecimento.

{
  "success": true,
  "users": [
    {
      "id": 123,
      "name": "João Silva",
      "email": "joao@loja.com",
      "phone": "+55 11 98765-4321",
      "idSRProfile": 5,
      "profile_name": "Gerente",
      "status": "active",
      "last_login": "2025-11-08 09:30:00",
      "created_at": "2025-01-15 10:00:00"
    },
    {
      "id": 124,
      "name": "Maria Santos",
      "email": "maria@loja.com",
      "phone": "+55 11 91234-5678",
      "idSRProfile": 8,
      "profile_name": "Operador",
      "status": "active",
      "last_login": "2025-11-08 10:15:00",
      "created_at": "2025-03-20 14:30:00"
    }
  ]
}

Criar/Editar Usuário

Cria novo usuário ou edita existente.

// Criar novo usuário
{
  "h": "ABC123",
  "name": "Pedro Costa",
  "email": "pedro@loja.com",
  "phone": "+55 11 99999-8888",
  "idSRProfile": 5
}

// Response
{
  "success": true,
  "message": "Usuário criado com sucesso",
  "user": {
    "id": 125,
    "email": "pedro@loja.com",
    "welcome_email_sent": true
  }
}

📧 Email de Boas-Vindas: Ao criar usuário, um email com link para definir senha é enviado automaticamente.

Alterar Status

Ativa ou desativa um usuário.

Resetar Senha

Envia email com link para redefinir senha.

Reenviar Email de Boas-Vindas

Reenvia email de boas-vindas para usuário que ainda não ativou conta.

Deletar Usuário

Remove usuário (soft delete).

⚠️ Restrições: Não é possível deletar o usuário principal (owner) do estabelecimento.

Perfis e Permissões

Perfis são templates de permissões que definem o que cada usuário pode acessar e fazer na plataforma.

Listar Perfis

Lista todos os perfis disponíveis para o estabelecimento.

{
  "success": true,
  "profiles": [
    {
      "id": 1,
      "name": "Administrador",
      "description": "Acesso total ao sistema",
      "isDefault": true,
      "users_count": 3
    },
    {
      "id": 5,
      "name": "Gerente",
      "description": "Gestão operacional e relatórios",
      "isDefault": false,
      "users_count": 5
    },
    {
      "id": 8,
      "name": "Operador",
      "description": "Apenas operação de vendas",
      "isDefault": false,
      "users_count": 12
    }
  ]
}

Criar Perfil

Cria novo perfil de acesso.

Atualizar Perfil

Atualiza dados de um perfil existente.

Salvar Permissões

Define permissões detalhadas para um perfil. Requer role Super Adm/Diretor.

// Request
{
  "idSRProfile": 8,
  "permissions": {
    "dashboard": {
      "view": true
    },
    "transactions": {
      "view": true,
      "create": true,
      "refund": false,
      "export": false
    },
    "customers": {
      "view": true,
      "create": false,
      "edit": false,
      "delete": false
    },
    "financial": {
      "view": false,
      "transfers": false,
      "anticipation": false
    },
    "settings": {
      "view": false,
      "edit": false
    }
  }
}

// Response
{
  "success": true,
  "message": "Permissões salvas com sucesso",
  "profile": {
    "id": 8,
    "name": "Operador",
    "permissions_updated_at": "2025-11-08 11:00:00"
  }
}

Módulos Principais

Deletar Perfil

Remove perfil (soft delete). Não pode deletar se houver usuários vinculados.

Preferências do Usuário

Cada usuário pode personalizar sua experiência na plataforma.

Atualizar Preferências Gerais

Atualiza preferências de interface e regionalização.

Atualizar Notificações

Configura quais notificações o usuário deseja receber.

Atualizar Acessibilidade

Configura opções de acessibilidade.

Atualizar Perfil

Atualiza dados pessoais do usuário (nome, telefone, foto).

Financeiro

Gestão financeira completa: consulta de saldos, extratos, transferências e agenda de recebíveis.

Contas e Saldos

Consultar Saldos

Retorna saldos disponíveis, bloqueados e a receber.

{
  "success": true,
  "balances": {
    "available": 15320.50,
    "blocked": 2450.00,
    "to_receive": 48900.75,
    "currency": "BRL"
  }
}

Consultar Extrato

Retorna movimentações financeiras do período.

Transferir

Realiza transferência para conta bancária cadastrada.

Recebíveis

Agenda de Recebíveis

Agenda de valores a receber (próximos 90 dias).

{
  "success": true,
  "receivables": [
    {
      "date": "2025-11-09",
      "amount": 3420.50,
      "transactions_count": 15
    },
    {
      "date": "2025-11-10",
      "amount": 5120.80,
      "transactions_count": 22
    }
  ],
  "total": 48900.75
}

Histórico de Recebíveis

Histórico completo de recebimentos.

Status de Antecipação

Verifica elegibilidade e valores disponíveis para antecipação.

Webhooks

Receba notificações em tempo real sobre eventos na plataforma.

Eventos Disponíveis

• transaction.approved - Transação aprovada
• transaction.refused - Transação recusada
• transaction.refunded - Estorno realizado
• transfer.completed - Transferência concluída
• receivable.paid - Recebível pago

Testar Webhook

Envia evento de teste para validar endpoint.

Retentar Envio

Retenta envio de webhook que falhou.

Dashboard e Métricas

Dashboard API

Retorna KPIs e métricas consolidadas.

{
  "success": true,
  "period": "last_30_days",
  "metrics": {
    "transactions": {
      "total": 1543,
      "approved": 1489,
      "refused": 54,
      "total_value": 487320.50
    },
    "revenue": {
      "gross": 487320.50,
      "net": 478450.30,
      "fees": 8870.20
    },
    "conversion_rate": 96.5,
    "avg_ticket": 315.80,
    "top_payment_methods": [
      {"method": "pix", "count": 890, "percentage": 57.7},
      {"method": "credit_card", "count": 653, "percentage": 42.3}
    ]
  }
}

APIs Públicas

Lista completa de APIs públicas disponíveis (gerada automaticamente via ./sync-api-docs).

Autenticação

Outros

V0 (Legacy)

V1 (API Key)

V2 (REST)

Webhooks