Novidades

O que mudou em cada versão.

As versões do contrato público da API (openapi.yaml) e dos pacotes. Mudanças que quebram compatibilidade são avisadas aqui antes de entrar.

Outubro de 2026: API 0.3.0, SDK JavaScript 0.3.1 e cliente PHP 0.3.1#

Erros sempre no formato padrão. Corpo grande demais, JSON inválido ou sem campo obrigatório, Content-Type errado, método não permitido e endereço inexistente agora respondem {"error":{"code","message"}}, com códigos estáveis (payload_too_large, invalid_request, unsupported_media_type, method_not_allowed e not_found) e sem nomes internos. Antes, esses casos saíam em texto puro.
Pré-voo OPTIONS: responde 405 method_not_allowed com Allow, em vez de 401. A API não atende navegadores.
Documentação: reescrita, com guias de integração, referência com exemplos e busca.
SDK JavaScript 0.3.1: ExtensionSigner.installUrl já vem com o endereço da página de instalação, e client.installUrl aponta para ela.

verify: uma assinatura visível acrescentada depois, que cubra mais de 10% da página, reprova a anterior (modified_after_signing, aviso later_visible_covers_content). Selos pequenos mantêm a anterior válida, com o aviso later_visible_signature.
PDFs com formulário cíclico ou gigante são recusados (invalid_pdf).
complete: novo 409 complete_in_progress (esperar e repetir com a mesma chave). A repetição de uma resposta inline grande pode receber 429 com Retry-After. O SDK JavaScript e o cliente PHP repetem esses casos e não descartam a sessão quando o resultado é incerto.
Cliente PHP: a Idempotency-Key é validada (1 a 64 caracteres entre letras, dígitos, - e _).
Extensão: o nome do provedor de chaves do Windows não vai mais aos sites.
Sessões: cada cliente tem um teto de sessões abertas; sessões concluídas contam até o DELETE.

Tudo é aditivo: nada do que existia mudou de nome nem de formato.

API

prepare devolve certificate (a identidade já validada, antes do PIN) e signatureFieldNames.
Nomes de certificado em RFC 4514 (subjectDn, issuerDn) e só o CN (subjectCn, issuerCn) em prepare, complete e verify. pkiBrazil.companyName traz a razão social do e-CNPJ.
error.reason: motivo estável das recusas de certificado.
signatureFieldName e signatureFieldNames no prepare, e vários signatários em sequência.
Assinatura visível: imagePlacement, fontColor, textAlign, textVerticalAlign, includeSigningTime, autoFontSize e o marcador {{company}}.
Sessão: GET /v1/pades-signatures/{token}, POST .../extend (até 60 minutos desde o início) e o cabeçalho Idempotency-Key no complete, com Idempotent-Replayed: true na repetição.
verify: messages em português por assinatura e laterSignatures.
Carimbo de tempo em toda assinatura PAdES.

Correções

A verificação marcava as assinaturas anteriores como modified_after_signing quando outra pessoa assinava depois. Agora continuam valid.
O carimbo da assinatura visível saía ilegível em corpo pequeno no Chrome e no Edge.

SDK JavaScript e cliente PHP

SDK: ExtensionSigner.diagnose(), installUrl e redirectToInstallPage, EXTENSION_ERROR_CODES, os campos subjectDn, issuerDn, subjectCn, issuerCn, keyStorage, icpBrasil e isTest, os filtros icpBrasilChain() e notTest(), beforeSign, signatureFieldName, getSession, extendSession e complete com Idempotency-Key e repetição automática.
PHP: complete(..., $idempotencyKey), completeSafely(), getSession(), extendSession(), prepare(..., signatureFieldName), imagem em memória na assinatura visível e ApiException::$reason.

Extensão e agente

A lista de certificados não traz mais raízes e intermediárias, só o certificado do titular, e informa onde a chave está (token, file ou cloud).
A assinatura espera até 3 minutos (certificado em nuvem com aprovação no celular).
PIN errado: o token informa "poucas tentativas" ou "a próxima errada bloqueia", quando sabe.
A extensão está disponível na Chrome Web Store e no Edge Add-ons.

Novo

Login por certificado (/v1/certificate-authentications): e-CPF e e-CNPJ, desafio de uso único, e a mensagem inclui a origem do seu site. A revogação é conferida por padrão.
acceptableIssuers: restrição da AC emissora no início da assinatura e do login.
PKI privada: contextos private:<identificador> por cliente, com raízes, intermediárias e LCRs enviadas por você, e a política pades-basic-lt.
Assinatura visível com posição, página e texto.
Lote: vários PDFs numa só sessão, com um PIN.
Painel: PKI privada, edição de planos, exclusão de usuário (LGPD), papel de administrador do cliente e atividade.
O login por certificado é assinado com SHA-384 (use o digestAlgorithm devolvido).
O envio multipart tem tempo-limite total (408 upload_timeout).

Segurança

Extensão: permissão por site e proteção contra repasse do login a outro site.
Teto de disco por cliente (429 tenant_storage_limit) e trava de conclusão por sessão: uma assinatura concluída nunca é cobrada duas vezes.
A auditoria é imutável.

Mudanças de comportamento

O login por certificado passou a exigir origin.
Em contexto privado, a verificação usa só as LCRs enviadas por você e falha fechada sem elas.
Páginas com /Rotate (90, 180, 270): o carimbo sai de pé, e o retângulo continua no espaço do PDF sem rotação. Um /Rotate que não é múltiplo de 90 é recusado.

CAdES e XAdES, OCSP para PKI privada, e o instalador do agente para macOS e Linux.

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