Referência da API

Todos os endpoints, parâmetros, corpos e respostas, gerados do contrato OpenAPI.

Versão 0.3.0 · endereço base https://api.pki.shieldsign.com.br · baixar o contrato OpenAPI. Toda chamada leva Authorization: Bearer ssk_... (autenticação). Erros: códigos e formato.

API de assinatura digital de PDF (PAdES) com certificados ICP-Brasil e de PKI privada. A chave privada nunca sai do computador do usuário.

Autenticação. Toda chamada leva Authorization: Bearer ssk_... (a chave de API de um cliente) e deve partir do seu servidor, nunca do navegador. Cada cliente tem um limite de requisições por minuto e, opcionalmente, uma cota mensal de assinaturas concluídas. Toda resposta traz o cabeçalho X-Request-Id.

Fluxo de uma assinatura.

POST /v1/pades-signatures (ou .../multipart) envia o PDF e a política e devolve um token de sessão (43 caracteres, válido por 15 minutos).
O certificado do usuário é lido no computador dele. POST .../{token}/prepare valida o certificado e devolve os dados a assinar (toSignData).
O usuário assina localmente. POST .../{token}/complete devolve o PDF assinado, já com o carimbo de tempo.
DELETE .../{token} apaga a sessão e os arquivos do servidor.

A sessão pertence ao cliente que a criou: outro cliente recebe 404 token_not_found.

Prazo e repetição segura. POST .../{token}/extend devolve os 15 minutos, até o teto de 60 minutos desde o início, e GET .../{token} informa a fase e o prazo. Se a resposta do complete se perder, repita a chamada com o mesmo cabeçalho Idempotency-Key: a API devolve a mesma resposta (Idempotent-Replayed: true), sem assinar de novo e sem gastar a cota. Sem a chave, uma conclusão inline é de uso único.

Lotes. POST /v1/pades-signatures/multipart envia um ou vários PDFs em binário. O prepare devolve um item por documento em digests, na mesma ordem, e uma única aprovação assina todos. Com output=link, o complete devolve links para baixar cada PDF ou um .zip. Cada documento concluído é uma transação, para uso, cota e auditoria.

Nomes de certificado. subjectName e issuerName são texto legível, para exibir. subjectDn e issuerDn estão em RFC 4514 (CN=...,OU=...,O=ICP-Brasil,C=BR), o mesmo formato que acceptableIssuers aceita. subjectCn e issuerCn são só o Common Name (o do titular, já sem o :CPF/CNPJ).

Limites (serviço da Shield): 30 MiB por PDF, 256 MiB por envio multipart, 50 documentos por lote e 32 MiB de corpo em chamadas JSON.

Assinatura de PDF (PAdES)

POST/v1/pades-signatures
POST/v1/pades-signatures/multipart
GET/v1/pades-signatures/{token}
DELETE/v1/pades-signatures/{token}
POST/v1/pades-signatures/{token}/extend
GET/v1/pades-signatures/{token}/documents/{index}
GET/v1/pades-signatures/{token}/documents.zip
POST/v1/pades-signatures/{token}/prepare
POST/v1/pades-signatures/{token}/complete

POST/v1/pades-signatures

Inicia a assinatura e devolve o token da sessão

Corpo da requisição (application/json)

Campo	Tipo	Descrição
`pdfToSign` *	texto
`signaturePolicyId` *	texto	`pades-basic` (PAdES-B-B) vem embutida. As políticas ICP-Brasil (AD-RB etc.) dependem de configuração no engine (OID e hash do documento da política); sem ela retornam 422 `policy_not_configured`.
`securityContextId` *	texto	Define as raízes de confiança usadas para validar a cadeia do certificado.
`callbackArgument`	texto	Valor opaco devolvido no `complete`.
`acceptableIssuers`	lista de texto	Restringe quem pode assinar. Cada item é a impressão digital SHA-256 (64 hex) ou o DN (RFC 4514, qualquer ordem, sem diferenciar maiúsculas) de uma AC da cadeia do certificado (intermediária ou raiz; o certificado final não conta). Basta um item casar. A conferência é feita pelo motor DEPOIS de validar a cadeia contra as raízes do contexto, então não dá para burlar com uma AC de mesmo nome. Sem casar: 422 `certificate_issuer_not_allowed`, no `prepare`, antes de o usuário digitar o PIN. Vazio/ausente = sem restrição.

Exemplo

curl -X POST "https://api.pki.shieldsign.com.br/v1/pades-signatures" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfToSign": "<PDF em base64>",
    "signaturePolicyId": "...",
    "securityContextId": "..."
  }'

Respostas

HTTP	Descrição
200	Sessão criada
400	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
503	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`token` *	texto
`documents` *	lista de objeto

POST/v1/pades-signatures/multipart

Inicia a assinatura de um ou vários PDFs enviados em binário

multipart/form-data com os campos de texto signaturePolicyId, securityContextId, callbackArgument e acceptableIssuers (opcionais) e uma ou mais partes file (PDF). A ordem das partes file define o índice dos documentos. Cada arquivo vai direto para o disco, em blocos. Erros: 400 (sem arquivo, não é PDF, lote grande demais, campos ausentes), 403 quota_exceeded (o lote precisa caber na cota restante do mês), 408 upload_timeout (o envio passou do tempo total permitido, 10 min no padrão: a sessão é cancelada), 413 payload_too_large, 507 storage_full.

Corpo da requisição (multipart/form-data)

Campo	Tipo	Descrição
`signaturePolicyId` *	texto
`securityContextId` *	texto
`callbackArgument`	texto
`acceptableIssuers`	texto	Array JSON de textos (`["CN=AC Exemplo","<sha256 de uma AC>"]`) ou um único item; o campo pode repetir. Ver `StartPadesRequest.acceptableIssuers`.
`file` *	lista de texto (binary)

Exemplo

curl -X POST "https://api.pki.shieldsign.com.br/v1/pades-signatures/multipart" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY"
  -F signaturePolicyId=... \
  -F securityContextId=... \
  -F file=@contrato.pdf

Respostas

HTTP	Descrição
200	Sessão criada
400	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
403	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
413	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
507	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`token` *	texto
`documents` *	lista de objeto

GET/v1/pades-signatures/{token}

Estado da sessão (fase, prazo e, se concluída, o resultado sem o PDF)

Use depois de um tempo-limite para saber se a conclusão chegou a acontecer. Não revela o PDF (baixe com documents/{index}). Em sessões inline sem Idempotency-Key nada fica retido: após o complete o token é 404.

Parâmetros

Nome	Em	Descrição
`token`	path

Exemplo

curl -X GET "https://api.pki.shieldsign.com.br/v1/pades-signatures/${TOKEN}" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY"

Respostas

HTTP	Descrição
200	Estado da sessão
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`token` *	texto
`phase` *	`started` \| `prepared` \| `completed`
`expiresInSeconds` *	inteiro
`extendableForSeconds` *	inteiro	Por quanto tempo ainda dá para renovar (teto de 60 minutos desde o `start`).
`documents` *	lista de objeto
`callbackArgument`	texto
`result`	objeto	Só em `completed`: o mesmo resultado do `complete`, sem `signedPdf`.

DELETE/v1/pades-signatures/{token}

Descarta a sessão e apaga os arquivos do servidor na hora

Parâmetros

Nome	Em	Descrição
`token`	path

Exemplo

curl -X DELETE "https://api.pki.shieldsign.com.br/v1/pades-signatures/${TOKEN}" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY"

Respostas

HTTP	Descrição
204	Descartada
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

POST/v1/pades-signatures/{token}/extend

Renova o prazo da sessão (15 minutos a partir de agora, até 60 minutos desde o início)

Para certificado em nuvem com aprovação no celular que demora mais que o prazo normal. Também renova o prazo dos arquivos no servidor. Passou de 60 minutos desde o start: 409 invalid_session_state.

Parâmetros

Nome	Em	Descrição
`token`	path

Exemplo

curl -X POST "https://api.pki.shieldsign.com.br/v1/pades-signatures/${TOKEN}/extend" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY"

Respostas

HTTP	Descrição
200	Prazo renovado
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
409	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`expiresInSeconds` *	inteiro
`extendableForSeconds` *	inteiro	Quanto do teto de 60 minutos ainda estava disponível antes desta renovação.

GET/v1/pades-signatures/{token}/documents/{index}

Baixa um PDF assinado (sessão concluída com output=link)

Parâmetros

Nome	Em	Descrição
`token`	path
`index`	path

Exemplo

curl -X GET "https://api.pki.shieldsign.com.br/v1/pades-signatures/${TOKEN}/documents/${INDEX}" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY"

Respostas

HTTP	Descrição
200	PDF assinado
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
409	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

GET/v1/pades-signatures/{token}/documents.zip

Baixa todos os PDFs assinados num .zip (sessão concluída com output=link)

Parâmetros

Nome	Em	Descrição
`token`	path

Exemplo

curl -X GET "https://api.pki.shieldsign.com.br/v1/pades-signatures/${TOKEN}/documents.zip" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY"

Respostas

HTTP	Descrição
200	Arquivo .zip (nomes `001-<nome>-assinado.pdf`, ...)
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
409	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

POST/v1/pades-signatures/{token}/prepare

Recebe o certificado e devolve os dados a assinar

Parâmetros

Nome	Em	Descrição
`token`	path

Corpo da requisição (application/json)

Campo	Tipo	Descrição
`certificate` *	texto
`certificateChain`	lista de texto
`visualRepresentation`	objeto	Assinatura visível em TODOS os documentos da sessão. Sem este campo (nem `visualRepresentations`) a assinatura é invisível.
`visualRepresentations`	lista de objeto ou nulo	Lote: um item por documento, na ordem do envio (`null` = esse documento fica sem assinatura visível). O tamanho precisa ser igual ao número de documentos. Não combine com `visualRepresentation`.
`signatureFieldName`	texto	Nome do campo de assinatura em TODOS os documentos. Padrão: `ShieldSignature1` ou, se o PDF já tem assinaturas (vários signatários em sequência), o primeiro `ShieldSignatureN` livre (a 2ª assinatura vira `ShieldSignature2`, a 3ª `ShieldSignature3`...). Nome já usado no PDF: 409 `signature_field_exists`; nome fora do padrão: 400.
`signatureFieldNames`	lista de texto	Lote: um nome por documento (`null` = nome padrão). Não combine com `signatureFieldName`.

Exemplo

curl -X POST "https://api.pki.shieldsign.com.br/v1/pades-signatures/${TOKEN}/prepare" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate": "<certificado DER em base64>"
  }'

Respostas

HTTP	Descrição
200	Dados para assinatura
400	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
409	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
422	Recusa do format-engine. Códigos: `invalid_certificate`, `certificate_not_trusted`, `certificate_issuer_not_allowed`, `policy_not_configured`, `security_context_not_configured`, `invalid_pdf`, `invalid_visual_representation`. `certificate_not_trusted`, `invalid_certificate` e `certificate_issuer_not_allowed` trazem `error.reason` (subcódigo estável, sem dados pessoais): `expired`, `not_yet_valid`, `chain`, `key_usage`, `revoked`, `revocation_unavailable`, `algorithm`, `malformed`, `issuer_not_allowed`. `409 signature_field_exists` (o PDF já tem um campo com o `signatureFieldName` pedido).
502	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`toSignData` *	texto	DER dos atributos assinados CMS; é este o dado que a chave privada assina.
`toSignHash` *	texto	Hash de `toSignData` com `digestAlgorithm`, para assinadores que só aceitam o hash.
`digestAlgorithm` *	texto
`digestAlgorithmOid` *	texto
`signatureAlgorithm` *	texto
`digests` *	lista de objeto + objeto
`certificate`	objeto	Identidade do certificado que vai assinar, JÁ validado (cadeia, validade, uso de chave, emissor aceito): o mesmo bloco do `complete`. Compare `pkiBrazil.cpf`/`cnpj` com o esperado e recuse ANTES do PIN, sem gastar a transação.
`signatureFieldNames`	lista de texto	Nome do campo de assinatura criado em cada documento (na ordem de `digests`).
`warnings`	lista de texto

POST/v1/pades-signatures/{token}/complete

Recebe a assinatura produzida pelo agente e devolve o PDF assinado

Com Idempotency-Key, uma conclusão que deu certo pode ser repetida (mesmo token, mesma chave) e devolve a MESMA resposta com o cabeçalho Idempotent-Replayed: true, sem assinar de novo nem contar a cota. Chave diferente, ou sem chave, numa sessão já concluída: 409 invalid_session_state. 409 complete_in_progress: a 1ª chamada ainda está sendo concluída (ex.: carimbo de tempo lento): espere e repita com a MESMA chave. 429 rate_limited (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 de novo. Falha de negócio (4xx) não consome a chave: a sessão continua e a mesma chave serve na próxima tentativa que der certo.

Parâmetros

Nome	Em	Descrição
`token`	path
`Idempotency-Key`	header	1 a 64 caracteres [A-Za-z0-9_-]. Gere um valor novo por tentativa de ASSINAR (não por tentativa de rede).

Corpo da requisição (application/json)

Campo	Tipo	Descrição
`signature`	texto	Valor bruto da assinatura sobre `toSignData`. RSA PKCS#1 v1.5; ECDSA aceito em DER ou r\|\|s (PKCS#11).
`signatures`	lista de texto
`output`	`inline` \| `link`	`inline` (padrão com 1 documento): `signedPdf` em base64 na resposta (até 32 MiB) e a sessão é apagada. `link` (padrão em lote): links de download válidos até o fim da sessão. Se um documento do lote for recusado (`invalid_signature`) nada é gerado e a sessão é preservada para nova tentativa; a mensagem diz `documento N: ...`.

Exemplo

curl -X POST "https://api.pki.shieldsign.com.br/v1/pades-signatures/${TOKEN}/complete" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Respostas

HTTP	Descrição
200	PDF assinado
400	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
409	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
410	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
422	`invalid_signature` (não confere com o certificado/digest). A sessão é preservada e o cliente pode reenviar `complete`.
502	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`signedPdf`	texto	Só em `output=inline`.
`documents` *	lista de objeto + objeto
`zipUrl`	texto	Só em `output=link`.
`certificate` *	objeto
`callbackArgument`	texto
`warnings`	lista de texto	Avisos do servidor. `tsa_not_configured`: a política (AD-RC/AD-RA) pede carimbo de tempo, mas este servidor está em modo de desenvolvimento sem TSA; o DSS foi embutido com o relógio local e a assinatura NÃO vale como AD-RC/AD-RA no ITI.
`ltv`	objeto	AD-RC/AD-RA — o que foi embutido no PDF.

Verificação de assinaturas

POST/v1/signature-verifications

POST/v1/signature-verifications

Verifica as assinaturas de um PDF

Confere CADA assinatura do PDF: integridade, assinatura criptográfica, cadeia do certificado até as raízes do securityContextId, alterações feitas depois de assinar, carimbo de tempo e política ICP-Brasil declarada (conferida contra a LPA oficial). Cobrada como transação pades_verification (preço próprio no plano; não consome a cota de assinaturas). Sem raízes configuradas para o contexto a resposta é erro (nunca "confiável" por omissão). status de cada assinatura: valid, invalid, untrusted, revoked, modified_after_signing. Atenção: signingTime é o que o próprio signatário declarou; sem carimbo de tempo confiável ele não prova quando assinou.

Corpo da requisição (application/json)

Campo	Tipo	Descrição
`pdfToVerify` *	texto
`securityContextId` *	texto

Exemplo

curl -X POST "https://api.pki.shieldsign.com.br/v1/signature-verifications" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfToVerify": "...",
    "securityContextId": "..."
  }'

Respostas

HTTP	Descrição
200	Relatório (PDF sem assinaturas devolve `signatureCount: 0` e `allValid: false`)
400	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
422	`invalid_pdf` (ilegível, criptografado), `security_context_not_configured`, `too_many_signatures`
502	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`transactionId` *	texto
`signatureCount` *	inteiro
`allValid` *	booleano	Verdadeiro só se há ao menos uma assinatura e todas estão `valid`.
`documentTimestampCount`	inteiro	Carimbos de tempo do documento (AD-RA); `signatureCount` conta só assinaturas de pessoas.
`ltv`	objeto	Validação de longo prazo embutida (DSS).
`signatures` *	lista de objeto

POST/v1/certificate-authentications
POST/v1/certificate-authentications/{token}/complete

POST/v1/certificate-authentications

Inicia a autenticação por certificado (login com e-CPF/e-CNPJ)

Cria um desafio de uso único (nonce de 256 bits, validade de 5 minutos). O usuário assina dataToSign com o certificado (A1, A3 por extensão + agente; no SDK JS: signer.sign(dataToSign, "SHA-256")) e o seu servidor conclui em POST /v1/certificate-authentications/{token}/complete. A mensagem tem separação de domínio (ShieldSign-Auth-v1) e leva o cliente e o contexto: nunca é um PDF nem um hash de PDF. Transação certificate_authentication (uso/fatura próprios; não consome a cota de assinaturas).

Corpo da requisição (application/json)

Campo	Tipo	Descrição
`securityContextId` *	texto
`acceptableIssuers`	lista de texto	Mesma restrição de emissor da assinatura (ver `StartPadesRequest.acceptableIssuers`).
`checkRevocation`	booleano	Exige a situação de revogação (ICP-Brasil: LCR/OCSP; PKI privada: as LCRs enviadas). PADRÃO true: certificado revogado ou sem como consultar NÃO autentica (`certificate_revoked` / `revocation_unavailable`). false só em ambiente sem fonte de revogação.
`callbackArgument`	texto

Exemplo

curl -X POST "https://api.pki.shieldsign.com.br/v1/certificate-authentications" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "securityContextId": "..."
  }'

Respostas

HTTP	Descrição
200	Desafio criado
400	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`token` *	texto
`transactionId` *	texto
`dataToSign` *	texto
`digestAlgorithm` *	texto	Algoritmo com que `dataToSign` deve ser assinado. É SHA-384 de propósito (a assinatura de PDF usa SHA-256): uma assinatura SHA-256, como a que a extensão produz para `hash`/`hashes`, não vale como login (separação de domínio contra relé). Use sempre o valor devolvido.
`expiresIn` *	inteiro	Segundos de validade do desafio (300).

POST/v1/certificate-authentications/{token}/complete

Conclui a autenticação por certificado

Valida a cadeia do certificado contra as raízes do securityContextId (e acceptableIssuers, e a revogação se checkRevocation) e a assinatura sobre o desafio. A mensagem é montada pela API a partir do desafio guardado. O desafio é consumido atomicamente: qualquer tentativa (certa ou errada) o queima; para tentar de novo, inicie outro. Token de outro cliente, vencido, já usado ou de assinatura PAdES: 404 token_not_found. Erros do motor: certificate_not_trusted, certificate_issuer_not_allowed, invalid_signature, invalid_certificate, certificate_revoked... authenticated: true prova a posse da chave; quem é o usuário (CPF/CNPJ de certificate.pkiBrazil) o seu servidor decide.

Parâmetros

Nome	Em	Descrição
`token`	path

Corpo da requisição (application/json)

Campo	Tipo	Descrição
`certificate` *	texto
`certificateChain`	lista de texto
`signature` *	texto

Exemplo

curl -X POST "https://api.pki.shieldsign.com.br/v1/certificate-authentications/${TOKEN}/complete" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate": "<certificado DER em base64>",
    "signature": "<assinatura em base64>"
  }'

Respostas

HTTP	Descrição
200	Autenticado
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.
422	Recusado pelo motor (código estável em `error.code`)
502	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`authenticated` *	booleano
`transactionId` *	texto
`certificate` *	objeto
`callbackArgument`	texto

PKI privada (contextos de segurança)

GET/v1/private-security-contexts
PUT/v1/private-security-contexts/{slug}
DELETE/v1/private-security-contexts/{slug}
PUT/v1/private-security-contexts/{slug}/crls

GET/v1/private-security-contexts

Lista os contextos de segurança privados do cliente

Exemplo

curl -X GET "https://api.pki.shieldsign.com.br/v1/private-security-contexts" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY"

Respostas

HTTP	Descrição
200	Contextos (sem o PEM; só emissor, validade e thumbprint)
401	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`contexts`	lista de objeto

PUT/v1/private-security-contexts/{slug}

Cria ou substitui uma PKI privada (corporativa) do cliente

Cadastra as raízes (e, opcionalmente, intermediárias) da PKI da empresa (ex.: Microsoft AD CS) e passa a valer como securityContextId: "private:<slug>". Separação estrita: o motor, nesse contexto, confia SOMENTE nestas âncoras (nunca nas raízes globais ICP-Brasil), e nenhuma âncora própria entra em contexto global. Cada cliente só vê e usa os seus. Só pades-basic e pades-basic-lt são aceitas (as políticas ICP-Brasil exigem o contexto icp-brasil). pades-basic-lt = PAdES-B-LT: revogação obrigatória com as LCRs enviadas em crls (o motor não busca nada na rede para PKI privada) e DSS embutido; sem LCR válida não assina (revocation_unavailable), certificado revogado = certificate_revoked, sempre antes do PIN. Validação: só CERTIFICATE (chave privada colada = 400 e nada é gravado); raiz = autoassinada, CA, não vencida; intermediária = CA, não autoassinada; até 50 certificados e 512 KB; até 20 contextos por cliente. Substituir troca TODAS as âncoras; sessões já preparadas terminam com as âncoras do prepare. Quem tem a chave de API pode alterar a confiança do cliente: guarde-a como segredo (as alterações vão para a auditoria).

Parâmetros

Nome	Em	Descrição
`slug`	path

Corpo da requisição (application/json)

Campo	Tipo	Descrição
`description`	texto
`roots` *	lista de texto
`intermediates`	lista de texto
`crls`	lista de texto	LCRs das ACs acima. Cada uma precisa ser emitida e assinada por uma AC do contexto, já válida e com nextUpdate no futuro. Total até 512 KB.

Exemplo

curl -X PUT "https://api.pki.shieldsign.com.br/v1/private-security-contexts/${SLUG}" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "roots": [
      "..."
    ]
  }'

Respostas

HTTP	Descrição
201	Criado
200	Substituído
400	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`id`	texto
`slug`	texto
`description`	texto
`roots`	lista de objeto
`intermediates`	lista de objeto
`crls`	lista de objeto
`createdAt`	texto
`updatedAt`	texto

DELETE/v1/private-security-contexts/{slug}

Exclui o contexto (nunca cai para as raízes globais)

Parâmetros

Nome	Em	Descrição
`slug`	path

Exemplo

curl -X DELETE "https://api.pki.shieldsign.com.br/v1/private-security-contexts/${SLUG}" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY"

Respostas

HTTP	Descrição
204	Excluído
404	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

PUT/v1/private-security-contexts/{slug}/crls

Troca só as LCRs do contexto privado

Para a rotina do cliente que repete isto a cada publicação de LCR da AD CS (elas vencem em dias). As âncoras (raízes/intermediárias) ficam como estão; as LCRs anteriores são TODAS substituídas ([] remove todas). LCR vencida, ainda não válida, de AC que não é do contexto ou com a assinatura errada = 400 e nada muda. A PKI de duas camadas precisa da LCR da raiz (cobre a intermediária) e da LCR da intermediária (cobre o usuário).

Parâmetros

Nome	Em	Descrição
`slug`	path

Corpo da requisição (application/json)

Campo	Tipo	Descrição
`crls` *	lista de texto

Exemplo

curl -X PUT "https://api.pki.shieldsign.com.br/v1/private-security-contexts/${SLUG}/crls" \
  -H "Authorization: Bearer $SHIELDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "crls": [
      "..."
    ]
  }'

Respostas

HTTP	Descrição
200	Contexto atualizado
400	Erro. Além dos códigos de cada operação, qualquer rota pode responder: 401 `unauthorized` (chave ausente, inválida ou revogada; cabeçalho `WWW-Authenticate: Bearer`), 403 `tenant_suspended` (cliente suspenso) ou `quota_exceeded` (cota mensal esgotada, só no `start`), 429 `rate_limited` (cabeçalho `Retry-After` em segundos) e 503 `store_unavailable`.

Resposta de sucesso

Campo	Tipo	Descrição
`id`	texto
`slug`	texto
`description`	texto
`roots`	lista de objeto
`intermediates`	lista de objeto
`crls`	lista de objeto
`createdAt`	texto
`updatedAt`	texto

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

Referência da API

Assinatura de PDF (PAdES)

POST/v1/pades-signatures

Corpo da requisição (application/json)

Exemplo

Respostas

Resposta de sucesso

POST/v1/pades-signatures/multipart

Corpo da requisição (multipart/form-data)

Exemplo

Respostas

Resposta de sucesso

GET/v1/pades-signatures/{token}

Parâmetros

Exemplo

Respostas

Resposta de sucesso

DELETE/v1/pades-signatures/{token}

Parâmetros

Exemplo

Respostas

POST/v1/pades-signatures/{token}/extend

Parâmetros

Exemplo

Respostas

Resposta de sucesso

GET/v1/pades-signatures/{token}/documents/{index}

Parâmetros

Exemplo

Respostas

GET/v1/pades-signatures/{token}/documents.zip

Parâmetros

Exemplo

Respostas

POST/v1/pades-signatures/{token}/prepare

Parâmetros

Corpo da requisição (application/json)

Exemplo

Respostas

Resposta de sucesso

POST/v1/pades-signatures/{token}/complete

Parâmetros

Corpo da requisição (application/json)

Exemplo

Respostas

Resposta de sucesso

Verificação de assinaturas

POST/v1/signature-verifications

Corpo da requisição (application/json)

Exemplo

Respostas

Resposta de sucesso

Login por certificado

POST/v1/certificate-authentications

Corpo da requisição (application/json)

Exemplo

Respostas

Resposta de sucesso

POST/v1/certificate-authentications/{token}/complete

Parâmetros

Corpo da requisição (application/json)

Exemplo

Respostas

Resposta de sucesso

PKI privada (contextos de segurança)

GET/v1/private-security-contexts

Exemplo

Respostas

Resposta de sucesso

PUT/v1/private-security-contexts/{slug}

Parâmetros

Corpo da requisição (application/json)

Exemplo

Respostas

Resposta de sucesso

DELETE/v1/private-security-contexts/{slug}

Parâmetros

Exemplo

Respostas

PUT/v1/private-security-contexts/{slug}/crls