Ir para o conteúdo

API de documentos

O seu sistema pede a assinatura. A pessoa assina no uShield.

Um pedido por PDF, até 10 pessoas por pedido, em paralelo ou em ordem. O mesmo token DPoP da API de cliente, um webhook assinado e uma especificação OpenAPI que você baixa.

Visão geral

Do token ao PDF assinado, em quatro passos.

A organização precisa estar registrada no uShield, com a razão social e o CNPJ, e ter um pacote contratado; para receber os eventos, também o endereço do webhook no registro. Antes de oferecer o meio, GET /api/rp/consumo diz em disponivel se a organização envia agora e, quando não, em motivo, por quê (arquivo-fora-do-ar, organizacao-so-leitura, organizacao-incompleta ou organizacao-sem-pacote). O resto é o seu sistema falando HTTP.

  1. Peça o token

    client_credentials com private_key_jwt, amarrado por DPoP, com o resource da API de cliente e os escopos rp:envelopes e rp:webhooks. Vale 10 minutos.

  2. Crie o pedido

    POST /api/rp/envelopes com o PDF em base64 (até 10 MB), o SHA-256 dele, o título, os e-mails de quem assina, o regime, o nível mínimo e a sua referência. Cada pessoa recebe o convite por e-mail e assina na carteira do uShield.

  3. Acompanhe

    Os eventos envelope.assinado, recusado, concluido, cancelado e vencido chegam ao seu webhook, assinados. O que se perdeu, a reconciliação devolve.

  4. Baixe e confira

    O PDF final, com a folha de assinaturas e as provas anexadas, e o pacote de cada assinatura. Qualquer pessoa confere a prova com as chaves públicas do uShield.

Os contratos

O que vai no fio.

Os trechos resumem a especificação OpenAPI, que tem cada campo, cada resposta e cada código de recusa.

O token

O mesmo cliente do registro dinâmico, autenticado pela sua chave. Bearer é recusado; cada pedido leva uma prova DPoP nova, e prova repetida também é recusada.

POST https://ushield.app/oidc/token
DPoP: <prova assinada com a chave do cliente>

grant_type=client_credentials
&scope=rp:envelopes rp:webhooks
&resource=https://ushield.app/api/rp
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<JWT assinado com a sua chave>

200 { "access_token": "...", "token_type": "DPoP", "expires_in": 600 }

Criar o pedido

O PDF fica no arquivo da sua organização no uShield, cifrado, enquanto durar o contrato e por mais 30 dias, ou até a organização apagá-lo. A referência é idempotente: repetir a mesma com o mesmo pedido devolve o que já nasceu (200), e com outro é referencia-divergente. Com sequencial, só a pessoa da vez recebe o convite. O prazo vai de 1 a 30 dias. Na qualificada, quem assina usa o certificado digital ICP-Brasil, e o nível mínimo é sempre n3. Na simples, quem assina confirma com um código enviado ao e-mail do convite, sem passkey; ela e o nível n0 valem quando o consumo os lista em aceita.

POST https://ushield.app/api/rp/envelopes
Authorization: DPoP <access_token>
DPoP: <prova nova, com htm, htu, iat, jti e ath>

{
  "titulo": "Contrato de prestação de serviços",
  "referencia": "pedido-123",
  "documentoBase64": "<o PDF em base64>",
  "hashDoDocumento": "<SHA-256 do PDF, em hex>",
  "algoritmo": "sha256",
  "tamanhoBytes": 48213,
  "regime": "avancada",
  "nivelMinimo": "n2",
  "participantes": [{ "email": "pessoa-1@exemplo.com.br" }, { "email": "pessoa-2@exemplo.com.br" }],
  "sequencial": true,
  "diasParaAssinar": 7
}

201 { "id": "...", "expiraEm": "...", "participantes": [{ "id": "...", "email": "pessoa-1@exemplo.com.br" }, ...],
      "pdfEmAnexo": false, "sequencial": true }

Webhook

HMAC-SHA256 sobre "<t>.<corpo>" com o segredo do registro, e recuse t fora de 5 minutos. O id da entrega se repete nas tentativas: descarte o repetido por ele. O evento não traz nome nem e-mail; releia o pedido pela API. Sem resposta 2xx, o uShield tenta de novo por 24 horas e então desiste da entrega. Os eventos saem só dos pedidos criados pela API.

POST https://exemplo.com.br/api/webhooks/ushield
X-Ushield-Signature: t=1793577600,v1=<HMAC-SHA256 de "<t>.<corpo>" com o segredo>
X-Ushield-Delivery: <id da entrega>

{ "id": "<id da entrega>", "client_id": "rp_...", "evento": "envelope.assinado",
  "em": "2026-11-02T14:03:27.512Z", "envelopeId": "...", "referencia": "pedido-123", "participanteId": "..." }

Reconciliação

Comece no último atualizadoEm recebido MENOS 5 minutos, com o instante codificado para a URL, e trate cada item como idempotente: uma transação longa grava um instante anterior ao de outra já lida. A janela alcança 30 dias, o vencimento de um pedido aparece em até 5 minutos, e os pedidos criados no console também aparecem, com a referência nula. O que mudou antes de a reconciliação entrar no ar se lê pedido a pedido. Uma entrega desistida de um evento de documento volta à fila, com o mesmo id, por POST /api/rp/webhooks/entregas/{id}/reenviar, até 3 vezes.

GET https://ushield.app/api/rp/envelopes?atualizadosDesde=2026-11-02T13%3A58%3A27.512Z&limite=100

200 { "itens": [{ "id": "...", "referencia": "pedido-123", "situacao": "PENDENTE", "daVez": "...",
                  "participantes": [...], "pdf": { "pronto": false, ... }, "atualizadoEm": "..." }],
      "proximo": "<cursor da página seguinte, ou null>" }

O resultado e a conferência

O PDF final é montado depois que o pedido conclui, em geral em poucos minutos, e o evento envelope.concluido avisa quando ele (ou as provas à parte) está pronto. Quem diz o nome e o nível de quem assinou é o pacote, um JWS EdDSA que se confere só com as chaves públicas: confira também que o instante do ato cai entre o desde e o ate da chave do kid. Na qualificada, o pacote leva o certificado ICP-Brasil inteiro de quem assinou. A conferência pela API não grava o documento.

GET  https://ushield.app/api/rp/envelopes/{id}/assinado   (o PDF final, application/octet-stream)
GET  https://ushield.app/api/rp/envelopes/{id}/pacotes    (o pacote assinado de cada assinatura)
POST https://ushield.app/api/rp/conferencias              (um PDF assinado, cru, em application/pdf)

GET  https://ushield.app/api/integracao/chaves-do-pacote.json   (as chaves públicas, sem token)

Pedido do titular

A busca devolve os pedidos que a sua organização mandou a um e-mail; o e-mail vai no corpo, para não ir à URL. O apagamento tira o arquivo de um pedido encerrado, sem lê-lo, e as provas continuam valendo.

POST https://ushield.app/api/rp/envelopes/busca
{ "email": "pessoa-1@exemplo.com.br" }

DELETE https://ushield.app/api/rp/envelopes/{id}/arquivo
{ "motivo": "titular" }

As regras

O que vale para toda chamada.

Limites, versões e o que a sua organização recebe, para não ter surpresa em produção.

  • Limites por rotaCriar: 120 por minuto. Reconciliar: 60. Conferir: 6. As demais: 30. Passou, 429 com o código limite e Retry-After em segundos.
  • Cotas de 24 horasAcima do ritmo, o volume é o do pacote contratado, nas últimas 24 horas corridas (teto-do-dia), e cada e-mail recebe até 20 pedidos da sua organização no mesmo período (convites-demais). Os dois são 429 sem Retry-After: repetir logo não adianta.
  • Recusa com código estávelO corpo é sempre { codigo, mensagem }, mais campos em dados-invalidos. O código não muda; a frase pode mudar.
  • VersõesCampo, rota, evento e código novos saem sem aviso, e quem integra ignora o que não conhece. O que quebra vai a uma rota nova, /api/rp/v2/..., com as duas no ar por 6 meses.
  • O que a sua organização recebeO PDF assinado, com a folha de assinaturas, e as provas, com o nome e o nível de quem assinou, o instante e, quando registrado, o endereço IP de onde a pessoa assinou; na avançada, a chave pública da passkey que assinou, e na qualificada, o certificado inteiro. A leitura do pedido não traz nome nem e-mail de ninguém, e nunca diz se um e-mail tem conta.
  • PDF em anexopdfEmAnexo: true pede que o e-mail de conclusão leve o PDF assinado a quem assinou, até 10 MB. Só vale com a opção ligada nas configurações da sua organização e fora da qualificada, e nunca deve ir em documento de solicitação de titular: quem declara responde.
  • A API antigaPOST /api/rp/assinaturas segue no ar para quem já a usa, na assinatura dentro de uma sessão aberta pelo login, e responde com o cabeçalho Deprecation. Pedido novo de documento usa os envelopes.

Os códigos de recusa

Cada código, o status e onde aparece.

A tabela sai da mesma especificação que as rotas usam e diz o que cada código quer dizer. A mensagem da resposta é outra frase, que pode mudar; o código, não.

  • dados-invalidos

    400, 413, 415 · POST /api/rp/envelopes, GET /api/rp/envelopes, POST /api/rp/envelopes/{id}/cancelar, POST /api/rp/envelopes/{id}/lembrar, DELETE /api/rp/envelopes/{id}/arquivo, POST /api/rp/envelopes/busca, GET /api/rp/consumo, POST /api/rp/conferencias, GET /api/rp/webhooks/entregas, POST /api/rp/webhooks/entregas/{id}/reenviar

    O corpo, a consulta ou o caminho não passou na validação (em `campos`, quais); 413 quando o corpo passa do teto, e 415 na conferência sem `application/pdf`.

  • nao-encontrado

    404 · POST /api/rp/envelopes, GET /api/rp/envelopes/{id}, GET /api/rp/envelopes/{id}/assinado, GET /api/rp/envelopes/{id}/pacotes, POST /api/rp/envelopes/{id}/cancelar, POST /api/rp/envelopes/{id}/lembrar, DELETE /api/rp/envelopes/{id}/arquivo, POST /api/rp/webhooks/entregas/{id}/reenviar

    Não existe, ou é de outra organização: a resposta é a mesma para os dois. Na criação, a organização do token não foi achada; no reenvio, a entrega.

  • arquivo-fora-do-ar

    409 · POST /api/rp/envelopes

    O arquivo de documentos não está ligado neste ambiente: nenhum pedido nasce pela API.

  • documento-divergente

    400 · POST /api/rp/envelopes

    O `documentoBase64` não tem o `hashDoDocumento` ou o `tamanhoBytes` declarados.

  • documento-nao-e-pdf

    400 · POST /api/rp/envelopes

    O documento não começa com `%PDF-`.

  • organizacao-incompleta

    409 · POST /api/rp/envelopes

    O uShield ainda não registrou a razão social e o CNPJ da organização: fale com o atendimento.

  • organizacao-so-leitura

    409 · POST /api/rp/envelopes

    A organização está suspensa ou encerrada: lê, mas não cria nem altera.

  • organizacao-sem-pacote

    409 · POST /api/rp/envelopes

    A organização não tem pacote contratado: nenhum pedido nasce.

  • teto-do-dia

    429 · POST /api/rp/envelopes

    A organização passou dos convites (ou dos pedidos) das últimas 24 horas corridas que o pacote dela permite. É cota, não ritmo: repetir logo não adianta.

  • convites-demais

    429 · POST /api/rp/envelopes

    Algum dos e-mails já recebeu 20 pedidos desta organização nas últimas 24 horas corridas.

  • regime-fora-do-ar

    409 · POST /api/rp/envelopes

    O pedido é `simples` ou `n0`, e o `aceita` do consumo ainda não os lista: nada foi criado.

  • referencia-divergente

    409 · POST /api/rp/envelopes

    A `referencia` já nasceu com outro pedido (outro documento, título, regime ou pessoas). A mesma referência com o mesmo pedido devolve o que já nasceu, em 200.

  • deposito-indisponivel

    503 · POST /api/rp/envelopes, GET /api/rp/envelopes/{id}/assinado

    O depósito dos documentos não respondeu, ao guardar ou ao ler: nada foi criado. Tente de novo em alguns minutos.

  • janela-antiga

    400 · GET /api/rp/envelopes

    Sem cursor, o `atualizadosDesde` passa da janela de 30 dias; com cursor, o cursor é velho demais para o registro de mudanças. Recomece por um `atualizadosDesde` recente e leia o resto pedido a pedido.

  • assinado-ainda-nao

    409 · GET /api/rp/envelopes/{id}/assinado, DELETE /api/rp/envelopes/{id}/arquivo

    O PDF final ainda não existe: o pedido está aberto, foi encerrado sem concluir, ou concluiu e está sendo montado.

  • provas-a-parte

    409 · GET /api/rp/envelopes/{id}/assinado

    O pedido concluiu, mas o PDF não recebeu a folha (já assinado, protegido, grande demais ou a montagem falhou): as provas valem soltas, em `/pacotes`.

  • arquivo-indisponivel

    409 · GET /api/rp/envelopes/{id}/assinado

    O arquivo deste pedido foi apagado (pela organização ou pelo atendimento). As provas continuam em `/pacotes`.

  • envelope-fechado

    409 · POST /api/rp/envelopes/{id}/cancelar, POST /api/rp/envelopes/{id}/lembrar

    O pedido já não está aberto (concluído, recusado, cancelado ou vencido): não se cancela nem se lembra.

  • pedido-aberto

    409 · DELETE /api/rp/envelopes/{id}/arquivo

    O pedido ainda está aberto: cancele antes de apagar o arquivo.

  • limite

    429 · todas

    Pedidos demais desta organização nesta rota, ou deste endereço: espere os segundos de `Retry-After`, que só este código traz.

  • evento-sem-reenvio

    409 · POST /api/rp/webhooks/entregas/{id}/reenviar

    Só os eventos de documento voltam à fila. Para os avisos sobre uma pessoa, releia o nível pela consulta.

  • entrega-nao-desistida

    409 · POST /api/rp/webhooks/entregas/{id}/reenviar

    Só uma entrega desistida volta à fila.

  • reenvios-esgotados

    409 · POST /api/rp/webhooks/entregas/{id}/reenviar

    Esta entrega já foi reenviada três vezes.

  • sem-endereco

    409 · POST /api/rp/webhooks/entregas/{id}/reenviar

    A organização não tem endereço e segredo de webhook registrados, ou não está ativa.

  • invalid_token

    401 · todas

    Token ausente, inválido, vencido, sem amarração DPoP ou emitido para outro recurso.

  • invalid_dpop_proof

    401 · todas

    A prova DPoP não confere com o pedido, ou já foi usada.

  • insufficient_scope

    403 · todas

    O token não tem o escopo da rota.

  • invalid_client

    403 · todas

    A organização não está ativa no uShield.

  • erro-interno

    500 · todas

    Defeito do uShield, já registrado. Repita mais tarde: a criação é idempotente pela `referencia`.

A especificação

Baixe a OpenAPI e as chaves.

A especificação OpenAPI 3.1 está em https://ushield.app/api/integracao/openapi.json, e as chaves públicas do pacote em https://ushield.app/api/integracao/chaves-do-pacote.json, sem token.

Quer integrar a sua organização?

Peça uma demonstração: saímos dela com a sua organização pré-registrada e o pacote combinado.