URIs base do Valid PSC

Produção: https://certificado.vidaas.com.br
Homologação: https://hml-certificado.vidaas.com.br
Demonstração: https://demo-certificado.vidaas.com.br

 

Passo 1 - Cadastro de Aplicação sem Certificado

Para utilizar os serviços de autorização e assinatura é obrigatório cadastrar sua aplicação junto ao Valid PSC, este serviço para cadastro é realizado uma única vez. Abaixo a descrição do serviço para cadastro de aplicação.

Solicitação de cadastro:

• Path : <URI-base>/v0/oauth/application
• Método HTTPS: POST
• Cabeçalho:
  
  • Content-type: application/json ;
  • Accept: application/json ;
• Parâmetros: formato "application/json;charset=UTF-8":
  
  • name: obrigatório, nome/descrição da aplicação;
  • comments: obrigatório, observações gerais de uso da aplicação;
  • redirect_uris: obrigatório, URI’s autorizadas para redirecionamento (para serviços de código de autorização).
  • email: obrigatório, e-mail para suporte em caso de indisponibilidade, mudança de versão, entre outros.

 

Exemplo Request:

{
  "name": "App Demo",
  "comments": "App Demo",
  "redirect_uris": [https://valid.com.br/],
  "email": ""
}

 

Exemplo Response:

{
  "status": "success",
  "message": "New Client Application registered with Sucess",
  "client_id": "4c9fb552-0387-4e5f-8727-6676fa88dce1",
  "client_secret": "Ny2n3hq67gQEFvH7"
}

 

Observação:
Os parâmetros de retorno “client_id” e “client_secret” devem ser armazenadas na sua aplicação que serão parâmetros nas chamadas de outros serviços para autorização e assinatura.
Não incluir no cadastro de “redirect_uris“ o “push://” pois é gerado automaticamente.

 

Passo 2 - Serviço para encontrar um titular mediante informação de CPF ou CNPJ

Antes de chamar a aplicação para autenticação, você pode verificar se um CPF ou CNPJ existe no Valid PSC e listar os certificados disponíveis
para ele.

Solicitação do serviço:

• Path: <URI-base>/v0/oauth/user-discovery;
• Método HTTPS: POST;
• Parâmetros da requisição: formato "application/json;charset=UTF-8":
  
  • client_id: obrigatório, deve conter a identificação da aplicação;
  • client_secret: obrigatório, deve conter o segredo associado à aplicação;
  • user_cpf_cnpj: obrigatório, deve conter “CPF” para pessoa física ou “CNPJ” pessoa jurídica;
  • val_cpf_cnpj: obrigatório, deve conter o valor do cpf ou cnpj ;

 

Exemplo Request:

{
  "client_id": "4c9fb552-0387-4e5f-8727-6676fa88dce1",
  "client_secret": "Ny2n3hq67gQEFvH7",
  "user_cpf_cnpj": "CPF",
  "val_cpf_cnpj": "12345678901"
}

 

 Exemplo Response:

2.1 - Status S

{
  "status": "S",
  "slots": [
    {
      "slot_alias": "a4c2b5bc-ee20-492a-9908-
45d892f2e808",
      "label": "e-CPF A3 em nuvem gold"
    },
    {
      "slot_alias": "8e8353d5-e786-4822-9666-
603bd966ee58",
      "label": "e-CPF A3 em nuvem gold"
    }
  ]
}

 

 2.2 - Status N

{
  "status": "N"
}

 

Observação:
Status de retorno indicando “S” para resultado positivo ou “N” caso contrário;

 

Passo 3 - Autorização e Autenticação

Serviço para obter do titular autorização de uso da sua chave privada, com solicitação de fatores de autenticação.

AUTHORIZATION

Solicitação de Autorização:

• Path : <URI-base>/v0/oauth/authorize;
• Método HTTPS: GET;
• Parâmetros da requisição: formato "application/x-www-form-urlencoded"
  
  • client_id: obrigatório, deve conter a identificação da aplicação;
  • code_challenge: obrigatório, ver RFC 7636;
  • code_challenge_method: obrigatório, valor “S256” (ver RFC 7636);
  • response_type: obrigatório, valor "code";
  • scope: opcional, se não informado, será considerado "single_signature". Possíveis valores para o parâmetro:
    
    • single_signature: token que permite a assinatura de apenas um conteúdo (hash), sendo invalidado após a sua utilização;
    • multi_signature: token que permite a assinatura de multiplos hashes em uma única requisição, sendo invalidado após a sua utilização;
    • signature_session: token de sessão OAuth que permite várias assinaturas em várias chamadas a API, desde que o token esteja dentro do prazo de validade ou que não tenha sido revogado pela aplicação ou pelo usuário.
  • login_hint: opcional, valor de CPF ou CNPJ a ser informado como filtro para seleção do certificado a ser utilizado.
  • lifetime: opcional, indica o tempo de vida desejado para o token a ser gerado. Inteiro, em segundos;
  • redirect_uri: opcional, deve ser igual ou conter uma url informado no Serviço Cadastro de Aplicação. Para solicitar uma notificação deve-se informar apenas o valor “push://” no parâmetro.

 

Exemplo Request:

PATH_BASE/oauth/authorize?client_id=4c9fb552-0387-4e5f-8727-6676fa88dce1&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstwcM&code_challenge_method=S256&response_type=code&scope=signature_session&login_hint=12345678901&lifetime=900&redirect_uri=http://valid.com.br

 

Exemplo Request com PUSH:

PATH_BASE/oauth/authorize?client_id=4c9fb552-0387-4e5f-8727-6676fa88dce1&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstwcM&code_challenge_method=S256&response_type=code&scope=signature_session&login_hint=12345678901&lifetime=900&redirect_uri=push://

 

Exemplo Response:

<REDIRECT_URI>?code=2b15b0e1-bbf2-4e55-99b8-93cf824576b1&state=NONE

 

Exemplo Response com PUSH:
code=d402d71c-0918-43ca-a07d-62597f559497

 

Observação: 
Para o modo "PUSH NOTIFICATION" deverá realizar o Passo AUTHENTICATIONS antes do Passo 4 - Token.

Para autorização via QRCODE
Após solicitação de autorização, redireciona para o titular autorizar o uso

Página de Autorização para o titular da chave privada
O Valid PSC irá retornar com HTTP 302, solicitando redirecionamento para a página de autenticação OAuth para que o titular da chave privada
possa fazer autenticação via QRCODE. A página com o QRCODE ficará aguardando por 2 minutos o titular da chave privada autenticar com o
aplicativo ViDaas.

Autenticação pelo titular da chave privada
O titular da chave privada com uso do aplicativo ViDaas efetua a leitura do QRCODE autorizando a aplicação cliente na versão WEB o uso do
certificado digital.

Caso o titular possua mais de um certificado, será apresentado os certificados para que o titular faça a escolha do certificado que será
autorizado o uso.

Resposta da Requisição de Código de Autorização (Receive Code)
Ao autorizar o uso pelo titular, o Valid PSC emite um código de autorização com tempo de validade curto e retorna para aplicação cliente com
uma URI de redirecionamento contendo parâmetros no componente http query, usando o formato "application/x-www- form-urlencoded":

• code: obrigatório, código de autorização gerado pelo Valid PSC, a ser usado na solicitação do token de acesso;
• state: obrigatório caso tenha sido informado na requisição, deverá conter o mesmo valor.

Caso o titular não autorize o uso, o Valid PSC aguardará o tempo de expiração do QRCODE e irá exibir a mensagem conforme imagem abaixo:

 

 

AUTHENTICATIONS

Solicitação de Autenticação:
Path : <URI-base>/valid/api/v1/trusted-services/authentications
Método HTTPS: GET
Parâmetros da requisição: formato "application/x-www-form-urlencoded"
  code: obrigatório, deve conter código retornado do Serviço de Solicitação de Autorização (Authorization);

 

Exemplo de Solicitação de Autenticação

<URI-base>/valid/api/v1/trusted-services/authentications?code=d402d71c-0918-43ca-a07d-62597f559497

 

Exemplo de Resposta

{
"authorizationToken":
"eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..
nYWhIcwNUH_22Upe1BSUTQ.
oXT7UF2Mvtm5C6CjpdEGxcL_9XM86oNh4w0iGgUkQVGBla0CNnNW0_QbGx73Ldnu81kydOuz
tSj3wfWUQf3t7IftvVMuyfdigW4_
lz1LcC2q3p9N32iSEGb5VPzzSKqiZGa3asfMgEPjr3xYo7Lo3biTtbVPrChPLHslMi--
b7DXXOIZ23N2R5bCT2_h6pj6PyBnXsEWl5uaF9v5PSXsQ.ZuLdlRZkfGBoqrxbj5tgTg",
"redirectUrl": "push://<URI gerada no cadastro de aplicação>?
code=8b1bde77-3647-4d76-1289-a2ec97c75a4d&state=NONE"
}

 

Passo 4 - Token

• Path : <URI-base>/v0/oauth/token;
• Método HTTPS: POST;
• Parâmetros da requisição: formato "application/x-www-form-urlencoded"
  
  • grant_type: obrigatório, valor "authorization_code";
  • client_id: obrigatório, deve conter a identificação da aplicação;
  • client_secret: obrigatório, deve conter o segredo associado à aplicação;
  • code: obrigatório, deve conter código de autorização retornado do Serviço Código de Autorização;
  • redirect_uri: opcional, deve ser igual ao informado no Serviço Código de Autorização;
  • code_verifier: obrigatório, correspondendo a code_challenge enviado na Requisição de Código de Autorização (ver RFC 7636).

Observação: 
Para o método Authorize QRCODE (sem o push://) deve-se alterar o campo "code" pelo "code" retornado na URL.
Para o método Authorize PUSH deve-se alterar o campo "code" pelo "authorizationToken" retornado no Authentications.

 

Exemplo Request:

{
  "grant_type": "authorization_code",
  "client_id": "4c9fb552-0387-4e5f-8727-6676fa88dce1",
  "client_secret": Ny2n3hq67gQEFvH7,
  "code": "<authorization code>",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

 

Exemplo Response:

{
  "access_token": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..2tk9rh8yisesxBm1tNNcUg.z6VZu-HZJka9EDBSAgDrtZWgYn5je__nCc6uOOrl3wsCrzWT5G0SMUHpuX3McdBk0uIJ85cMOe3MFn75Pe5mfhlmdLtRUtnX_tJmg8rW6dU7mg4nR4XlyMmWYy-Yep_2dIM2xni0sWUplPxUCLg9dl7_aeVTB_U9TmsXOYCJNMYSJfjPErsthUNHWJHzUIOg-2Otj9gkq_EBLr0jYVWCw.IPOs5b_o6yKmz2Q24zYYvA",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "signature_session",
  "authorized_identification": "12345678901",
  "authorized_identification_type": "CPF"
}

 

Passo 5 - Signature

• Path: <URI-base>/v0/oauth/signature
• Método HTTPS: POST
• Cabeçalho: Re: Nova Versão da IN PSC
  
  • Content-type: application/json;
  • Accept : application/json;
  • Authorization: Bearer access_token;
    
    • Parâmetros: formato "application/json;charset=UTF-8" :
      
      • certificate_alias: opcional, identificador do certificado correspondente à chave utilizada na assinatura;
      • hashes: conjunto com valores a serem assinados. Cada elemento do conjunto conterá:
        
        • id: identificador do conteúdo a ser assinado;
        • alias: forma legível do identificador do conteúdo;
        • hash: conteúdo a ser assinado;
        • hash_algorithm: Object Identifier (OID) do algoritimo de hash. Por exemplo, para SHA256 utilize o OID 2.16.840.1.101.3.4.2.1;
        • signature_format: obrigatório:
          
          • RAW: resultado direto (em base64) da operação RSA sobre o hash informado na requisição.
          • CMS detached (PKCS#7), contendo os seguintes atributos assinados:
            - contentType
            - signingTime (hora do PSC)
            - messageDigest (hash informado pela aplicação na requisição)
            - signingCertificateV2 (certificado do assinante);
        • padding_method: opcional,
        • pdf_signature_page: opcional, página acrescentada no PDF mostrando a assinatura digital, podendo ter o valor "true" ou "alse", por padrão é definido o valor "false"
        • base64_content: opcional, conteúdo em base64 a ser assinado. Por exemplo Texto ou PDF a ser
          assinado em base64

Observação:
A aplicação suporta os seguintes signature_format:
RAW, CMS, CAdES_AD_RT, CAdES_AD_RB, PAdES_AD_RT, PAdES_AD_RB, RAW_DIGESTED_DATA.

e padding_method:
NONE, PKCS1V1_5, PSS.

Exemplo Request:

{
  "hashes": [
    {
      "id": "dummy assinatura",
      "alias": "dummy.pdf",
      "hash": "FqulOTrXLABB9WAK08LFLsQ3ovDH/Aj638PA/pZB16M=",
      "hash_algorithm": "2.16.840.1.101.3.4.2.1",
      "signature_format": "RAW"
    }
  ]
}

Exemplo Response:

{
  "signatures": [
    {
      "id": "dummy assinatura",
      "raw_signature": "my signature base64"
    }
  ],
  "certificate_alias": "CERTIFICADO TESTE"
}

 

Downloads

• Manual Integração com VIDaaS - Certificado em Nuvem (Produção).pdf
• ExemploRepresentacaoGraficaAssinaturaPDF.java
• PSC.postman_collection_ordenado.json