Sessões

Quanto tempo a sessão vale, como renová-la e o que fazer quando a resposta se perde.

A vida de uma sessão#

A sessão de assinatura vale 15 minutos a partir do início (o POST que devolve o token), com teto de 60 minutos se for renovada. Durante esse tempo, os PDFs ficam em disco no servidor da API. Ao terminar, você os apaga com DELETE; se esquecer, somem ao expirar.

GET /v1/pades-signatures/{token} devolve a phase, o expiresInSeconds e o extendableForSeconds. Se a sessão já expirou, o complete responde 404 token_not_found e nenhuma assinatura foi feita: reinicie (o usuário assina de novo, e nada foi gasto).

Quando o PIN ou a aprovação demora#

Com certificado em nuvem, o usuário aprova no aplicativo do celular, e isso pode passar de alguns minutos. Renove a sessão:

curl -s -X POST "$SHIELDSIGN_URL/v1/pades-signatures/$TOKEN/extend" -H "Authorization: Bearer $SHIELDSIGN_KEY"

$api->extendSession($token);   // volta a 15 minutos, até 60 desde o início

A renovação também estende o prazo dos arquivos no servidor. Se a sua tela sabe que o certificado é em nuvem (keyStorage === "cloud"), renove ao abrir a janela de aprovação. O agente espera até 3 minutos pela aprovação; negar no aplicativo vira user_cancelled, e passar do prazo vira timeout, com nada assinado.

Quando a resposta do complete se perde#

Uma conclusão bem-sucedida em inline é de uso único. Se a rede cair depois de a assinatura ser feita, repetir o complete devolveria 404, e você não saberia se assinou. A solução é o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave devolve a mesma resposta, sem assinar de novo e sem gastar a cota.

$chave = bin2hex(random_bytes(16));   // UMA por tentativa de assinar (não por tentativa de rede); guarde-a junto da assinatura em andamento

try {
    $c = $api->complete($token, $assinaturas, null, $chave);
} catch (ApiException $e) {
    if ($e->httpStatus === 0 || $e->httpStatus >= 502) {          // rede ou gateway: pode ter concluído
        $c = $api->complete($token, $assinaturas, null, $chave);  // MESMA chave e MESMO token
    } else {
        throw $e;
    }
}
$api->discard($token);   // com a chave, a API retém a sessão e o PDF: libere quando já guardou o resultado

completeSafely($token, $assinaturas, $output) faz tudo isso sozinho: gera a chave e repete em falha de rede, 408, 429, 502, 503, 504 e 409 complete_in_progress, com espera crescente. No modo inline, ele também apaga a sessão ao receber o PDF; no modo link, a sessão continua, para você baixar os arquivos, e você deve chamar discard depois. O SDK JavaScript também usa chave e repetição por padrão.

Regras da Idempotency-Key:

• 1 a 64 caracteres: letras, dígitos, - e _.
• A chave só vale para uma conclusão que deu certo. Um erro de negócio, como invalid_signature, não a consome.
• Chave diferente (ou ausente) numa sessão já concluída: 409 invalid_session_state.
• A repetição devolve o cabeçalho Idempotent-Replayed: true.
• A repetição não conta a cota de novo.
• Sem a chave, nada fica retido no servidor, e o inline é de uso único.

409 complete_in_progress e 429 na repetição#

• 409 complete_in_progress: a primeira chamada ainda está sendo concluída (por exemplo, o carimbo de tempo está lento). Espere e repita com a mesma chave. Não descarte a sessão.
• 429 com Retry-After na repetição de uma resposta inline grande, quando a API está entregando outras ao mesmo tempo: a conclusão não foi executada de novo; tente mais tarde.

Apague a sessão ao terminar#

Uma sessão concluída continua ocupando uma vaga do seu cliente até o DELETE ou o fim do prazo (15 minutos). Há um teto de sessões abertas por cliente e um teto de bytes: ao passar, a API responde 429 tenant_storage_limit. Quem não apaga as sessões fica limitado a cerca de 100 assinaturas a cada 15 minutos.

$api->discard($token);   // assim que guardar o PDF, inclusive nos caminhos de erro

O SDK JavaScript apaga a sessão sozinho depois de receber o PDF. No cliente PHP, completeSafely faz isso no modo inline; no modo link, chame discard depois de baixar. Se você chama a API direto, faça o DELETE você mesmo. Veja Limites e cotas.

O que o servidor guarda e por quanto tempo#

• O PDF original e o assinado ficam em disco só durante a sessão.
• Em inline sem chave, somem na hora do complete.
• Em link, ou com Idempotency-Key, ficam até o DELETE ou o fim do prazo (no mínimo 5 minutos com a chave).
• A auditoria registra a operação (quem, quando, transactionId), nunca o conteúdo do documento.