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.
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.
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.
Acompanhe
Os eventos envelope.assinado, recusado, concluido, cancelado e vencido chegam ao seu webhook, assinados. O que se perdeu, a reconciliação devolve.
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.