SDK PHP

O pliic/pliic-php é o SDK oficial em PHP. Ele é para quem quer integrar o Pliic nativamente no backend: em vez de embutir o widget, o seu sistema cria sugestões e tickets em nome dos seus usuários, exibe o mural com estado de voto, responde tickets e consome webhooks, tudo pela API REST.

Se o widget embutido já atende, você não precisa do SDK. Use quando quiser controlar 100% da experiência dentro do seu produto.

Instalação

composer require pliic/pliic-php

Requer PHP 8.2+ com ext-curl e ext-json. Nenhuma outra dependência.

Autenticação

Crie o cliente com a chave secreta do app (sk_live_..., na aba de configurações do app):

use Pliic\PliicClient;

$pliic = new PliicClient('sk_live_...');

Cuidado

A chave secreta dá acesso total à API do seu app. Ela fica só no servidor: nunca no navegador, em app mobile ou em repositório público.

Os endpoints exigem escopos na chave (suggestions:read, suggestions:write, tickets:read, tickets:write, etc.) e o recurso de API disponível no seu plano.

Agindo em nome do seu usuário

Toda escrita aceita um objeto user com a identidade do usuário no seu sistema. O Pliic cria ou reutiliza o usuário correspondente automaticamente (se o e-mail já existir, é a mesma pessoa):

$user = ['id' => 'u_123', 'name' => 'Ana', 'email' => '[email protected]'];

$pliic->suggestions->create([
    'user' => $user,
    'title' => 'Modo escuro',
    'description' => 'Seria mais confortável à noite.',
]);

Você não precisa saber o id interno do Pliic, o id é o do seu próprio banco.

Sugestões

// Mural com estado de voto do usuário atual
$pliic->suggestions->list(['status' => 'planned', 'search' => 'escuro', 'user_id' => 'u_123']);

$pliic->suggestions->get(42, ['user_id' => 'u_123']); // inclui user_has_voted
$pliic->suggestions->vote(42, ['user' => $user]);      // vota; chamar de novo desfaz
$pliic->suggestions->comments(42);
$pliic->suggestions->addComment(42, ['user' => $user, 'body' => 'Ótima ideia!']);

Tickets

$pliic->tickets->list(['user_id' => 'u_123']);  // tickets daquele usuário
$pliic->tickets->create(['user' => $user, 'subject' => 'Erro no checkout', 'body' => '...', 'type' => 'bug']);
$pliic->tickets->get(7);                        // inclui a conversa pública completa
$pliic->tickets->reply(7, ['user' => $user, 'body' => 'Mais detalhes aqui...']);

Só o autor do ticket pode responder por ele, e notas internas da sua equipe nunca aparecem na conversa retornada.

Token do widget (SSO)

Se você também usa o widget embutido, o SDK minta o userToken no servidor:

use Pliic\UserToken;

$token = UserToken::mint($chaveSecreta, [
    'id' => 'u_123',
    'name' => 'Ana',
    'email' => '[email protected]',
]);

Entregue $token ao frontend como userToken do widget.

Webhooks

Verifique a assinatura antes de confiar em qualquer payload:

use Pliic\Webhook;
use Pliic\Exceptions\SignatureVerificationException;

try {
    $event = Webhook::constructEvent(
        $request->getContent(),
        $request->header('X-Pliic-Signature'),
        $segredoDoEndpoint, // whsec_...
    );
} catch (SignatureVerificationException $e) {
    abort(400);
}

match ($event->type) {
    'suggestion.created' => processarSugestao($event->data),
    'ticket.created' => processarTicket($event->data),
    default => null,
};

Detalhes do formato da assinatura e dos eventos disponíveis: Webhooks.

Erros

Falhas da API viram exceções tipadas, todas filhas de Pliic\Exceptions\ApiErrorException:

Status	Exceção
401	AuthenticationException
403	PermissionException (escopo ou recurso do plano faltando)
404	NotFoundException
422	ValidationException ($e->errors() traz os erros por campo)
429	RateLimitException

Falhas de rede viram Pliic\Exceptions\TransportException.

Frontend em JavaScript?

Para construir a interface no navegador (em vez do backend), use o @pliic/sdk, que fala com a API do widget usando a chave pública.