Visão Geral da Plataforma

O ACG-Faka é um sistema de distribuição digital construído sobre PHP 8, focado na automação de vendas de licenças e cartões pré-pagos. Esta documentação técnica detalha os endpoints disponíveis para integração com plataformas de terceiros, permitindo o gerenciamento programático de catálogos, processamento de transações e controle de acesso.

Padrões de Comunicação

Todas as chamadas devem ser enviadas via método POST com dados codificados como application/x-www-form-urlencoded. O servidor responde estritamente em formato JSON.

A estrutura padrão de retorno é definida da seguinte forma:

{
  "code": 200,
  "msg": "Operação concluída",
  "data": {}
}

Campo	Tipo	Descrição
code	integer	Código de resposta (200 indica sucesso)
msg	string	Descrição textual do resultado
data	object/array	Conteúdo retornado pela operação

Códigos de Erro Comuns:

• 200: Sucesso
• 400: Parâmetros inválidos ou ausentes
• 401: Falha na autenticação
• 403: Acesso negado
• 404: Recurso não encontrado
• 500: Erro interno do servidor

Autenticação

Acesso aos recursos protegidos exige obtenção de sessão válida.

URL: /api/auth/login

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
account_id	string	Sim	Identificador de acesso (usuário, e-mail ou celular)
secret_key	string	Sim	Credencial de acesso
verify_code	integer	Não	Challenge CAPTCHA (quando habilitado)

Exemplo de Requisição:

curl -X POST "https://seudominio.com/api/auth/login" \
  -d "account_id=operador01&secret_key=SenhaSegura#99"

Gestão de Catálogo

Os endpoints de produtos permitem listar itens disponíveis e verificar estoques em tempo real.

URL: /api/commodity/data

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
page_size	integer	Sim	Quantidade de itens por página
offset	integer	Sim	Índice da página atual
vendor_id	integer	Não	Filtrar por ID do fornecedor

Resposta de Exemplo:

{
  "code": 200,
  "msg": null,
  "data": [
    {
      "item_id": 101,
      "title": "Cartão Pré-Pago Premium",
      "list_price": 75.50,
      "discounted_price": 65.00,
      "group_ref": 5,
      "stock_total": 200,
      "stock_sold": 45,
      "public_link": "https://loja.com/link?pid=101&vid=5"
    }
  ],
  "count": 24
}

Campos de Estoque:

• stock_total: Quantidade total de códigos gerados
• stock_sold: Quantidade já comercializada
• public_link: URL pública para compartilhamento do item

Fluxo de Pedidos

A criação e consulta de transações são realizadas através de endpoints dedicados.

Criação de Transação
URL: /api/order/trade

Nome	Tipo	Obrigatório	Descrição
product_ref	integer	Sim	ID do produto selecionado
units_qty	integer	Sim	Quantidade desejada
contact_info	string	Sim	E-mail ou telefone do comprador
challenge	integer	Não	Validação anti-bot

Resposta:

{
  "code": 200,
  "msg": "Transação inicializada",
  "data": {
    "order_code": "ORD-2025-04-12-X9Y",
    "total_value": 150.00,
    "checkout_link": "https://gateway.com/checkout/ORD-2025-04-12-X9Y"
  }
}

Consulta de Situação
URL: /api/order/state

Nome	Tipo	Obrigatório	Descrição
transaction_id	string	Sim	Código único do pedido

Mapeamento de Status:

Valor	Significado
0	Aguardando pagamento
1	Pago
2	Entregue
3	Finalizado
4	Cancelado

Webhooks de Pagamento

O sistema notifica terceiros sobre atualizações financeiras através de callbacks assíncronos.

URL Base: /api/order/callback/{gateway_id}

Lógica de Processamento (Exemplo em PHP):

public function processIncomingNotification(string $gateway, array $requestData): array
{
    // Limpar metadados injetados pelo roteador
    unset($requestData['_route'], $requestData['_controller']);
    
    // Delegar ao serviço de transações para validação
    return $this->transactionService->handleNotification($gateway, $requestData);
}

Cadastro de Usuários

URL: /api/auth/register

O sistema suporta diferentes métodos de cadastro configurados no painel administrativo:

Configuração	Valor	Modo
registration_mode	0	Baseado em nome de usuário
registration_mode	1	Baseado em celular
registration_mode	2	Baseado em e-mail

Corpo da Requisição (E-mail):

{
  "handle": "cliente_novo",
  "mailbox": "user@dominio.com.br",
  "access_password": "MinhaSenhaForte!2025",
  "mailbox_token": "987654",
  "captcha_token": "4321"
}

Mecanismos de Segurança

A aplicação implementa uma camada de proteção que filtra solicitações maliciosas antes do roteamento principal. Os módulos ativos incluem:

• Filtragem de vetores SQL Injection
• Sanitização de entradas contra XSS
• Validação de tokens CSRF em formulários
• Rate limiting por endereço IP

Validação de Dados (Exemplo):

// Verificar conformidade do identificador
AccountValidator::checkIdentifier($handle, 3);

// Confirmar formato de correio eletrônico
AccountValidator::confirmEmail($mailbox);

// Validar número telefônico
AccountValidator::confirmPhone($mobileNumber);

// Testar complexidade da senha
AccountValidator::assessPasswordStrength($accessPassword);

Diretrizes de Implementação

Tratamento de Exceções

try {
    $result = $httpClient->sendRequest('/api/order/trade', $payload);
    if ($result['code'] !== 200) {
        throw new IntegrationException($result['msg']);
    }
    return $result['data'];
} catch (IntegrationException $e) {
    $logger->warning('Falha na integração', ['erro' => $e->getMessage()]);
    throw $e;
}

Estratégia de Retentativas

function executarComTentativas(callable $operacao, int $maxTentativas = 3): mixed
{
    $contador = 0;
    do {
        try {
            return $operacao();
        } catch (Throwable $e) {
            $contador++;
            if ($contador === $maxTentativas) {
                throw $e;
            }
            usleep(1000000 * $contador); // Backoff linear
        }
    } while (true);
}

Gerenciamento de Cache

$chaveCache = "prod_{$identificador}";
$dadosCache = $armazenamento->recuperar($chaveCache);

if ($dadosCache !== false) {
    return $dadosCache;
}

$informacoesProduto = $gatewayCliente->buscarProduto($identificador);
$armazenamento->salvar($chaveCache, $informacoesProduto, 300); // TTL 300s

return $informacoesProduto;

Limites de Taxa de Requisição

Categoria	Limite Sguerido	Observação
Consulta de Catálogo	1 req/s	Implementar cache local para reduzir carga
Iniciação de Pedido	1 req/5s	Evitar duplicação de transações
Verificação de Status	1 req/2s	Alta frequência permitida para tracking em tempo real

Para operações em massa, priorize paginação, processamento em background e sincronização incremental.

Diagnóstico de Falhas

Sintoma	Causa Provável	Ação Recomendada
401 Unauthorized	Credenciais inválidas ou expiradas	Renovar sessão ou verificar chaves
403 Forbidden	Restrição de nível de acesso	Validar permissões do perfil
404 Not Found	Rota incoreta ou depreciada	Conferir documentação oficial
500 Internal Error	Exceção não tratada no backend	Registrar incidente e contactar suporte

Registro de Eventos:

$registro->info('Comunicação externa', [
    'rota' => $caminho,
    'entrada' => $dadosEnvio,
    'saida' => $retornoServidor,
    'marcar_tempo' => time()
]);