Cliente PHP

Instalação e uso do cliente PHP, sem dependências além do cURL.

O cliente PHP (ShieldSign\Client) é um arquivo só, sem dependências além da extensão curl do PHP. Os PDFs vão do disco para a API em blocos (sem base64 e sem carregar o arquivo na memória), e os erros da API viram ApiException.

Instalação#

Baixe o cliente na página de Downloads (shieldsign-php-<versão>.zip). Há três jeitos de usar:

Copiar a classeComposer (artifact)Composer (path)

O mais simples, sem Composer. Descompacte o .zip, copie src/ShieldSignClient.php para o seu projeto e carregue:

require __DIR__ . '/ShieldSignClient.php';

Coloque o .zip numa pasta do projeto (por exemplo, vendor-packages/) e, no composer.json:

{
  "repositories": [ { "type": "artifact", "url": "vendor-packages/" } ],
  "require": { "shieldcertificadora/shieldsign-php": "*" }
}

Depois: composer update shieldcertificadora/shieldsign-php.

Para desenvolvimento, apontando para a pasta descompactada:

{
  "repositories": [ { "type": "path", "url": "../shieldsign-php" } ],
  "require": { "shieldcertificadora/shieldsign-php": "*@dev" }
}

Configuração#

use ShieldSign\Client;

$api = new Client(
    'https://api.pki.shieldsign.com.br',
    getenv('SHIELDSIGN_KEY'),      // ssk_...: variável de ambiente ou cofre, nunca no repositório
    timeoutSeconds: 300            // PDFs grandes e lotes: deixe folgado
);

Métodos#

Método	O que faz
`startMultipart($arquivos, $politica, $contexto, $callbackArgument, $acceptableIssuers)`	Inicia a assinatura de um ou vários PDFs enviados em binário.
`startJson($pdfBytes, $politica, $contexto, ...)`	Inicia com um PDF pequeno (até cerca de 24 MiB), em base64.
`prepare($token, $certificadoDerBase64, visual: …, visualPerDocument: …, signatureFieldName: …, signatureFieldNames: …)`	Envia o certificado e recebe os dados a assinar.
`complete($token, $assinaturas, $output, $idempotencyKey)`	Envia as assinaturas. `$output`: `'inline'` ou `'link'`.
`completeSafely($token, $assinaturas, $output)`	`complete` com chave de idempotência e repetição em falha de rede. No modo `inline`, apaga a sessão ao receber o PDF; no modo `link`, chame `discard` depois de baixar.
`getSession($token)`	Fase e prazo da sessão.
`extendSession($token)`	Renova o prazo (até 60 minutos desde o início).
`downloadDocument($token, $indice, $destino)`	Baixa um PDF assinado para o disco.
`downloadZip($token, $destino)`	Baixa todos os PDFs assinados num `.zip`.
`discard($token)`	Apaga a sessão e os arquivos do servidor da API.
`verify($pdfBytes, $contexto)`	Verifica as assinaturas de um PDF.
`startCertificateAuthentication($contexto, $origem, ...)` e `completeCertificateAuthentication(...)`	Login por certificado.
`putPrivateContext`, `putPrivateContextCrls`, `listPrivateContexts`, `deletePrivateContext`	PKI privada.
`Client::visualRepresentation(...)`	Monta o pedido de assinatura visível.

Erros: `ApiException`#

Todo erro da API vira ShieldSign\ApiException, com campos estáveis:

try {
    $api->prepare($token, $certificado);
} catch (ShieldSign\ApiException $e) {
    $e->httpStatus;    // 0 se a rede falhou
    $e->errorCode;     // código estável: 'certificate_not_trusted', 'quota_exceeded', ...
    $e->requestId;     // X-Request-Id: registre e informe ao suporte
    $e->retryAfter;    // segundos sugeridos, em 429
    $e->reason;        // motivo da recusa de um certificado ('expired', 'chain', ...)
}

A lista dos códigos está em Erros.

Um exemplo completo#

$api = new ShieldSign\Client(getenv('SHIELDSIGN_URL'), getenv('SHIELDSIGN_KEY'));

$r = $api->startMultipart([['path' => $pdf, 'name' => 'contrato.pdf']], 'pades-icpbrasil-ad-rb', 'icp-brasil');
$p = $api->prepare($r['token'], $certificadoBase64);               // o certificado veio do navegador
$c = $api->completeSafely($r['token'], $assinaturasBase64, 'link'); // as assinaturas vieram do navegador
$api->downloadDocument($r['token'], 0, '/storage/assinado.pdf');
$api->discard($r['token']);                                         // no modo 'link', apague a sessão depois de baixar

Os três endpoints que ligam o navegador a este código estão em Assinar PDFs no seu sistema.

ShieldSign PKI · Shield Certificadora · contato@shieldcertificadora.com.br · Privacidade