Logigate SDK para PHP

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

Evento	Descrição
processo.iniciado	Processo de exportação iniciado
processo.concluido	Processo concluído com sucesso
processo.erro	Processo falhou
factura.emitida	Nova factura emitida
factura.anulada	Factura anulada
cliente.criado	Novo cliente criado
cliente.actualizado	Cliente actualizado
cliente.eliminado	Cliente eliminado
*	Todos os eventos

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