Sign API

Visão geral

A Sign API do Redtrust é uma API REST que permite integrar a assinatura de documentos com certificados digitais gerenciados de forma centralizada no Redtrust. Ela foi desenvolvida para aplicações externas que precisam autenticar usuários, recuperar seus certificados, executar operações de assinatura e gerenciar o perfil de assinatura do usuário.

URL base

https://SEU_IP_REDTRUST:PORTA/signapi

A porta padrão é 8083. Por exemplo: https://localhost:8083/signapi/v1/certificate/list.

Autenticação

Token de acesso

Todos os endpoints da Sign API exigem um token de acesso no cabeçalho Authorization:

Authorization: Bearer SEU_ACCESS_TOKEN

Há duas formas de obter esse token, dependendo do tipo de integração:

Fluxo de login do Sign Service

Este é o fluxo descrito em detalhes em Integração com o Sign Service. Em resumo:

1. Sua aplicação redireciona o usuário para GET /authclient/auth/loginrequest com os parâmetros do parceiro (incluindo a assinatura HMAC).
2. O usuário se autentica no Redtrust (ou em seu provedor de identidade externo).
3. O Redtrust redireciona o usuário para sua URL de retorno com um token temporário (tkn).
4. Sua aplicação troca esse token temporário por um token de acesso chamando POST /authapi/v1/login_by_temp_token.

Fluxo de código de autorização OAuth2

Este é o fluxo OAuth2 padrão. Segue o mesmo padrão de redirecionamento, mas usa os endpoints padrão:

1. Sua aplicação redireciona o usuário para GET /authclient/authorize com client_id, redirect_uri, response_type=code, state e os parâmetros PKCE (code_challenge e code_challenge_method).
2. O usuário se autentica.
3. O Redtrust redireciona o usuário para sua URL de retorno com um código de autorização (code).
4. Sua aplicação troca esse código por um token de acesso chamando POST /authclient/token.

Em ambos os casos, o resultado é um token de acesso que deve ser incluído no cabeçalho Authorization de todas as chamadas à Sign API.

tip

O fluxo OAuth2 é recomendado para novas integrações, pois segue um padrão amplamente adotado e permite renovar a sessão com um token de atualização.

aviso

Pré-requisito: o fluxo OAuth2 só funciona se o administrador do Redtrust tiver registrado previamente sua URI de redirecionamento. Consulte Configurar as URIs de redirecionamento.

Parâmetros do fluxo OAuth2

Este fluxo implementa PKCE (Proof Key for Code Exchange) para prevenir ataques de interceptação de código de autorização.

Solicitação de autorização

GET /authclient/authorize

Parâmetro	Obrigatório	Descrição
response_type	Sim	Deve ser code.
client_id	Sim	Identificador da sua aplicação. O Redtrust atribui esse valor ao registrar sua aplicação.
redirect_uri	Sim	URL para a qual o Redtrust redireciona o usuário após a autenticação. Deve corresponder exatamente a uma das URIs de redirecionamento registradas para o serviço no console de administração.
code_challenge	Sim	Challenge PKCE derivado do code_verifier. Entre 43 e 128 caracteres em formato base64url.
code_challenge_method	Sim	Método de transformação do challenge. O único valor aceito é S256.
state	Sim	Valor aleatório gerado pela sua aplicação para prevenir ataques CSRF. Entre 16 e 512 caracteres. O Redtrust o retorna sem modificações no redirecionamento.
domain	Não	Domínio do usuário. Se omitido, o usuário pode selecioná-lo durante a autenticação.

Troca do código pelo token

POST /authclient/token com corpo application/x-www-form-urlencoded:

Parâmetro	Obrigatório	Descrição
grant_type	Sim	Deve ser authorization_code.
client_id	Sim	O mesmo client_id da solicitação de autorização.
redirect_uri	Sim	A mesma URL de redirecionamento da solicitação de autorização.
code	Sim	O código de autorização recebido no redirecionamento.
code_verifier	Sim	O valor original do code_verifier PKCE gerado pela sua aplicação antes de calcular o code_challenge.

O servidor responde com:

{
  "access_token": "...",
  "token_type": "Bearer",
  "refresh_token": "..."
}

Renovação do token

Quando o token de acesso expira, você pode renová-lo sem que o usuário precise se autenticar novamente. Chame POST /authclient/token com:

Parâmetro	Obrigatório	Descrição
grant_type	Sim	Deve ser refresh_token.
client_id	Sim	Identificador da sua aplicação.
refresh_token	Sim	O token de atualização recebido na resposta anterior.

Cabeçalhos HMAC

Além do token de acesso, cada instalação do Redtrust pode exigir cabeçalhos HMAC para validar a identidade do parceiro em cada chamada à API. Se estiverem habilitados, inclua-os em todas as requisições:

Cabeçalho	Descrição
x-partner-name	Nome da aplicação cliente em maiúsculas. Usado para identificar e autorizar o parceiro que realiza a chamada.
x-request-timestamp	Timestamp UNIX que indica quando a requisição é feita. Ajuda a prevenir ataques de repetição.
x-hmac-signature	Assinatura HMAC-SHA256 gerada assinando a mensagem NOME_PARCEIRO:TIMESTAMP_UNIX com a chave compartilhada entre o parceiro e o Redtrust.

A validação HMAC pode ser desabilitada nas configurações da instalação. Consulte o administrador do Redtrust para saber se sua integração requer essa validação.

Formato de resposta

Todos os endpoints retornam a seguinte estrutura JSON:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "string",
  "data": {}
}

Campo	Descrição
message	Mensagem descritiva sobre o resultado.
messageType	SUCCESS se a operação foi concluída com sucesso; ERROR se ocorreu algum problema.
errorCode	Código identificador do erro, ou OK quando a operação é bem-sucedida.
data	Conteúdo da resposta. O tipo varia por endpoint — pode ser um objeto, uma lista ou estar vazio.