README

SDK oficial para integrar com a API do Logigate ERP da plataforma Honga Yetu.

Funciona em qualquer projecto PHP 8.1+ e tem integração nativa com Laravel.

Documentação

Consulte a documentação completa da API em: https://logigate.hongayetu.com/desenvolvedores/docs

Instalação

composer require hongayetu/logigate-sdk

Configuração

PHP Puro

use HongaYetu\LogigateSDK\LogigateClient;

$logigate = new LogigateClient(
    token: 'seu_token_api',
    baseUrl: 'https://api.honga.com/logigate/v1'
);

Laravel

Publique o ficheiro de configuração:

php artisan vendor:publish --tag=logigate-sdk-config

Adicione ao .env:

LOGIGATE_API_TOKEN=seu_token_api
LOGIGATE_API_URL=https://api.honga.com/logigate/v1

Use via Facade ou helper:

use HongaYetu\LogigateSDK\Facades\Logigate;

// Facade
$clientes = Logigate::clientes()->listar();

// Helper
$clientes = logigate()->clientes()->listar();

Utilização

Autenticação

// Verificar se o token é válido
$auth = $logigate->auth()->verificar();
echo $auth['data']['empresa']['nome']; // Nome da empresa

Clientes

// Listar clientes (paginado)
$clientes = $logigate->clientes()->listar(['por_pagina' => 20]);

// Ver cliente
$cliente = $logigate->clientes()->ver(1);

// Criar cliente
$novo = $logigate->clientes()->criar([
    'nome' => 'João Silva',
    'tipo' => 0, // 0 = Pessoa Singular, 1 = Empresa
    'nif' => '001234567LA041',
    'telefone' => 923456789,
    'email' => 'joao@email.com',
]);

// Actualizar cliente
$logigate->clientes()->actualizar(1, ['nome' => 'João Silva Actualizado']);

// Eliminar cliente
$logigate->clientes()->eliminar(1);

Produtos

$produtos = $logigate->produtos()->listar();
$produto = $logigate->produtos()->ver(1);
$novo = $logigate->produtos()->criar([
    'nome' => 'Produto Novo',
    'preco' => 5000.00,
    'taxa' => 14,
]);

Serviços

$servicos = $logigate->servicos()->listar();
$servico = $logigate->servicos()->criar([
    'nome' => 'Consultoria',
    'preco' => 25000.00,
]);

Facturas

// Listar facturas
$facturas = $logigate->facturas()->listar([
    'start' => '2026-01-01',
    'end' => '2026-12-31',
    'por_pagina' => 20,
]);

// Ver factura
$factura = $logigate->facturas()->ver(50);

// Emitir factura
$resultado = $logigate->facturas()->emitir([
    'tipo' => 0,              // 0=FR, 1=FT, 3=FP
    'tipo_pagamento' => 0,    // 0=Dinheiro, 1=TPA, 2=Transf. Bancária
    'cliente_id' => 535,
    'estabelecimento_id' => 21,
    'artigos' => [
        ['artigo_id' => 1, 'quantidade' => 2, 'preco' => 5000],
        ['artigo_id' => 3, 'quantidade' => 1],
    ],
]);

echo $resultado['data']['texto']; // "Factura FR EMP012026/01 emitida com sucesso"

// Obter PDF (base64)
$pdf = $logigate->facturas()->pdf(50);
file_put_contents('factura.pdf', base64_decode($pdf['data']['pdf_base64']));

// URL directa do PDF (para abrir no browser)
$url = $logigate->facturas()->pdfUrl(50);

Estabelecimentos

$estabelecimentos = $logigate->estabelecimentos()->listar();

Logística

// Fornecedores
$fornecedores = $logigate->fornecedores()->listar();
$logigate->fornecedores()->criar([
    'nome' => 'Fornecedor ABC',
    'tipo' => 1,
    'endereco' => 'Rua Principal, 100',
    'is_estrangeiro' => false,
]);

// Estoques
$estoques = $logigate->estoques()->listar(['estabelecimento_id' => 1]);
$logigate->estoques()->criar([
    'tipo_estoque' => 0,        // 0=Produto, 1=Matéria-Prima
    'produto_id' => 1,
    'quantidade' => 100,
    'preco_compra' => 5000.00,
    'data_entrada' => '2026-03-01',
    'estabelecimento_id' => 1,
]);

// Matérias-Primas
$materias = $logigate->materiasPrimas()->listar();

// Movimentações (apenas leitura)
$movimentacoes = $logigate->movimentacoes()->listar([
    'data_inicio' => '2026-01-01',
    'data_fim' => '2026-03-31',
]);

Relatórios

Os relatórios podem ser gerados imediatamente ou em segundo plano (quando o volume excede o threshold).

// Gerar relatório de facturas em PDF
$relatorio = $logigate->relatorios()->facturas([
    'tipo' => 'pdf',
    'formato' => 'base64',      // ou 'link'
    'start' => '2026-01-01',
    'end' => '2026-03-31',
]);

if ($relatorio['tipo_resposta'] === 'imediato') {
    // Relatório gerado imediatamente
    file_put_contents('relatorio.pdf', base64_decode($relatorio['data']['ficheiro_base64']));
} else {
    // Relatório em background — monitorar via processos
    $processoId = $relatorio['data']['processo_id'];
    echo "A gerar em background. Processo: {$processoId}";
}

// Outros relatórios disponíveis:
$logigate->relatorios()->clientes(['tipo' => 'excel']);
$logigate->relatorios()->produtos(['tipo' => 'pdf']);
$logigate->relatorios()->servicos(['tipo' => 'excel']);
$logigate->relatorios()->documentosEmitidos(['tipo' => 'pdf']);
$logigate->relatorios()->detalhado(['tipo' => 'pdf']);
$logigate->relatorios()->produtosMovimentos(['tipo' => 'pdf']);

Processos

Monitorizar tarefas em segundo plano (relatórios, exportações).

// Listar processos
$processos = $logigate->processos()->listar();

// Ver estado de um processo
$processo = $logigate->processos()->ver(123);
echo $processo['data']['status_texto']; // "Concluído"

// Download do ficheiro
$ficheiro = $logigate->processos()->download(123, 'base64');
file_put_contents('export.pdf', base64_decode($ficheiro['data']['ficheiro_base64']));

// Ou obter link temporário (válido 30 min)
$link = $logigate->processos()->download(123, 'link');
echo $link['data']['download_url'];

Webhooks

Receba notificações em tempo real quando ocorrem eventos.

// Criar webhook
$webhook = $logigate->webhooks()->criar([
    'url' => 'https://meusite.com/webhook',
    'eventos' => ['factura.emitida', 'cliente.criado'],
    'descricao' => 'Webhook principal',
]);

// Guardar o secret (retornado apenas na criação)
$secret = $webhook['data']['secret']; // whsec_...

// Listar webhooks
$webhooks = $logigate->webhooks()->listar();

// Testar webhook
$logigate->webhooks()->testar(1);

// Ver entregas
$entregas = $logigate->webhooks()->entregas(1);

// Actualizar
$logigate->webhooks()->actualizar(1, ['eventos' => ['*']]);

// Eliminar
$logigate->webhooks()->eliminar(1);

Validar webhooks recebidos

Quando receber um webhook, valide a assinatura HMAC-SHA256:

use HongaYetu\LogigateSDK\Support\WebhookValidator;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_LOGIGATE_SIGNATURE'] ?? '';
$secret = 'whsec_seu_secret_aqui';

if (WebhookValidator::validar($payload, $signature, $secret)) {
    $evento = json_decode($payload, true);
    // Processar evento...
} else {
    http_response_code(401);
    echo 'Assinatura inválida';
}

Eventos disponíveis

Tratamento de erros

O SDK converte erros HTTP em excepções específicas:

use HongaYetu\LogigateSDK\Exceptions\AuthenticationException;
use HongaYetu\LogigateSDK\Exceptions\ValidationException;
use HongaYetu\LogigateSDK\Exceptions\RateLimitException;
use HongaYetu\LogigateSDK\Exceptions\LogigateException;

try {
    $logigate->clientes()->criar(['nome' => '']);
} catch (AuthenticationException $e) {
    // 401 — Token inválido ou expirado
    echo $e->getCodigoErro(); // TOKEN_INVALIDO, TOKEN_EXPIRADO, TOKEN_AUSENTE
} catch (ValidationException $e) {
    // 422 — Dados inválidos
    echo $e->getMessage();
    print_r($e->errors()); // ['nome' => ['O nome é obrigatório']]
} catch (RateLimitException $e) {
    // 429 — Limite de requisições excedido
    echo "Tentar novamente em {$e->retryAfter()} segundos";
} catch (LogigateException $e) {
    // Outros erros
    echo $e->getMessage();
    echo $e->getCodigoErro();
}

Respostas paginadas

use HongaYetu\LogigateSDK\Support\PaginatedResponse;

$resposta = $logigate->clientes()->listar(['por_pagina' => 10]);
$paginacao = new PaginatedResponse($resposta);

echo "Página {$paginacao->paginaActual} de {$paginacao->ultimaPagina}";
echo "Total: {$paginacao->total}";

foreach ($paginacao as $cliente) {
    echo $cliente['nome'];
}

if ($paginacao->temProximaPagina()) {
    // Carregar próxima página
    $proxima = $logigate->clientes()->listar(['por_pagina' => 10, 'p' => $paginacao->paginaActual + 1]);
}

Requisitos

• PHP 8.1+
• Guzzle 7.0+
• Laravel 10/11/12 (opcional, para integração Laravel)

Licença

MIT