v1.6

Open

1. Introdução

Informações de contato e URIs.

1.1. Contato

Em caso de dúvidas ou dificuldades na integração você pode entrar em contato conosco abrindo um chamado em: https://valid-sa.atlassian.net/servicedesk/customer/portal/4/group/115/create/51 ou pelo email produtos.certificadora@valid.com.

Inclua em seu email os dados abaixo:

1.1. URIs base do Valid PSC

Produção: https://certificado.vidaas.com.br

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

2. Cadastro de Aplicação

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. Para obtenção 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

• Verbo HTTP: POST

• Cabeçalho:

  • Content-type: application/json

  • Accept: application/json

• Corpo da requisição no 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 de requisição:

Exemplo de resposta:

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.

O parâmetro “redirect_uris“ é utilizado para armazenar todas as URIs que poderão ser utilizadas posteriormente pela aplicação no redirecionamento do usuário após a assinatura ser realizada.

3. Uso da API

Os próximos tópicos descrevem como utilizar a API para realizar autenticações e assinaturas digitais.

Open

Imagem 1: Sugestão de implementação com os dois métodos de autenticação

Open

Imagem 2: Tela com o QR Code que deverá ser lido utilizando o aplicativo VidaaS

Open

Imagem 3: Jornada do usuário para realizar uma autenticação via QR Code

Open

Imagem 4: Resposta da aplicação web

c) Endpoint

Abaixo os parâmetros necessários para utilização deste método:

Path : <URI-base>/v0/oauth/authorize

• Verbo HTTP: GET

• Parâmetros da requisição no formato "Query Params"

  • client_id: obrigatório, deve conter a identificação da aplicação;

  • code_challenge: obrigatório, ver RFC 7636. Utilizado para assegurar integridade com a solicitação da autorização e com a geração do access_token que será visto adiante. Utiliza OAuth com PKCE para geração do par code challenge e code verifier. Caso precise, fazendo uma busca na internet, pode-se encontrar geradores online dessas chaves;

  • 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" (preferencialmente deve ser informado o tipo do escopo desejado porque o valor padrão pode mudar). 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.

    • authentication_session: token de sessão oAuth apenas para autenticação e que não permite uso da chave privada do usuário.

  • login_hint: deixar em branco.

  • lifetime: opcional, indica o tempo de vida desejado para o token a ser gerado. Inteiro, em segundos. O valor máximo varia com o tipo de certificado:

    • Pessoa Física: até 7 dias;

    • Pessoa Jurídica: até 30 dias;

      • Nota: Neste caso é importante conhecer a rotina do seu usuário. Alguns parceiros utilizam esse parâmetro de forma em que o usuário final escolhe por quanto tempo poderá ficar sem precisar inserir a senha novamente.

      • Sugestão: A duração da sessão pode ser implementada de acordo com a rotina do usuário, por exemplo, um médico que realiza um plantão de doze horas deveria ter uma sessão de 43200 s.

  • redirect_uri: obrigatório, deve conter uma uri informada anteriormente na criação da aplicação.

  • state: opcional.

3.1.2. Solicitação por notificação no celular (Push)

Nesse método, o signatário receberá uma notificação em seu celular, solicitando a assinatura pelo aplicativo VIDaaS:

a) Jornada do usuário: Usuário fornecendo a autorização através da notificação

Open

Imagem 5: Jornada do usuário ao autenticar via Push

b) Endpoint

• Path : <URI-base>/v0/oauth/authorize

• Verbo HTTP: GET

• Parâmetros da requisição no formato "Query Params"

  • client_id: obrigatório, deve conter a identificação da aplicação;

  • code_challenge: obrigatório, ver RFC 7636. Utilizado para assegurar integridade com a solicitação da autorização e com a geração do access_token que será visto adiante. Utiliza OAuth com PKCE para geração do par code challenge e code verifier. Caso precise, fazendo uma busca na internet, pode-se encontrar geradores online dessas chaves;

  • 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" (preferencialmente deve ser informado o tipo do escopo desejado porque o valor padrão pode mudar). 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;

    • authentication_session: token de sessão oAuth apenas para autenticação e que não permite uso da chave privada do usuário.

  • login_hint: obrigatório, informar CPF ou CNPJ do titular a que se destina a requisição.

  • lifetime: opcional, indica o tempo de vida desejado para o token a ser gerado. Inteiro, em segundos;

  • redirect_uri: informar apenas o valor “push://” no parâmetro.

c) Importante! Realizando uma autenticação através do “authentications” ao solicitar autorização por push

Esse método deve ser utilizado somente para casos de solicitação por notificação (Push) e permite saber se o titular realizou a “assinatura” que lhe foi solicitada.

Por se tratar de uma operação assíncrona, esse método deve ser chamado recorrentemente até que retorne o conteúdo com o “autorizationToken”.

Importante informar que a “recorrência“ deve ocorrer “com intervalo de tempo de no mínimo 1 segundo“. Chamadas menores do que esse intervalo estarão sujeitas ao bloqueio da aplicação.

• Path : <URI-base>/valid/api/v1/trusted-services/authentications

• Verbo HTTP: GET

• Parâmetros da requisição no formato "Query Params"
  ◦  code: obrigatório, deve conter código retornado pelo método authorize

3.1.3 Obter a chave para autenticação de documentos com o “token”

Retorna o “access_token”.

• Path : <URI-base>/v0/oauth/token

• Verbo HTTP: POST

• Parâmetros da requisição no 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_verifier: obrigatório, informar a chave que corresponde ao code_challenge enviado na Requisição de Código de Autorização (ver RFC 7636).

  • code: obrigatório, deve conter código de autorização retornado do Serviço Código de Autorização;

Observações:

1. Para o método Authorize QR Code deve-se alterar o campo "code" pelo "code" retornado.

2. Para o método Authorize PUSH deve-se alterar o campo "code" pelo "authorizationToken" retornado no Authentications.

Exemplo de requisição:

Exemplo de resposta:

3.2. Assinaturas digitais em documentos com o “Signature”

Utilizado para realizar assinaturas digitais em documentos de no máximo 7 MB.

• Path: <URI-base>/v0/oauth/signature

• Verbo HTTP: POST

• Parâmetros da requisição no formato "raw"

  • Content-type: application/json;

  • Accept : application/json;

  • Authorization: Bearer access_token (obtido anteriormente);

    • Parâmetros: formato "application/json;charset=UTF-8" :

      • certificate_alias: opcional, identificador do certificado correspondente à chave utilizada na assinatura.

      • hashes: conjunto com valores referentes a documentos 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, deve ser convertido inicialmente em SHA256 e posteriormente em base64;

        • 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: formato da assinatura, por exemplo:

          • RAW: resultado direto (em base64) da operação RSA sobre o hash informado na requisição.

          • CMS: PKCS#7 detached 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, acrescenta página no PDF mostrando a assinatura digital, podendo ter o valor "true" ou "false", 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ções:

1. A aplicação suporta os seguintes “signature_format”: RAW_DATA, CMS, CAdES_AD_RT, CAdES_AD_RB, PAdES_AD_RT, PAdES_AD_RB, RAW_DIGESTED_DATA.

2. A aplicação suporta os seguintes “padding_method”: NONE, PKCS1V1_5, PSS. Método usado para complementar o tamanho de 256 bytes do dado a ser assinado. O mais utilizado é o PKCS1V1_5.

Exemplo de requisição:

Exemplo de resposta:

3.3 Serviço para encontrar um titular mediante informação de CPF ou CNPJ (“user-discovery”).

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

• Verbo HTTP: POST

• Corpo da requisição no 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 de requisição:

Exemplos de respostas:

2.1 - Status S

2.2 - Status N

3.4 Extração da chave pública com o “Public Certificate”

Utilizado para extração da chave pública em base64 do signatário de um documento.

Para utilização dessa função deve-se utilizar o “certificate_alias” gerado no Sinature e do “access_token” gerado no endpoit Token.

• Path : <URI-base>/v0/oauth/certificate-discovery

• Verbo HTTP: GET

• Parâmetros da requisição no formato "Query Params"

Exemplo de resposta:

4. Observações sobre o modelo de negócios

a) O que é a licença comercial ou “Direito de uso”?

Quando um certificado A3 em nuvem é emitido, ele é criado com validade normativa de 5 anos. No entanto, comercialmente o usuário terá adquirido um período menor, de 1 ano em geral. Quando este prazo de licença comercial, ou, “Direito de uso” tiver acabado, ele poderá adquirir licenças adicionais, ampliando o direito de utilização, sem que precise realizar o processo e validação.

Open

Imagem 6: Como funciona o direito de uso no modelo de negócios do VidaaS

b) Todos os usuários podem ser bloqueados?

Não! Não são todos os usuários que podem ser bloqueados. Existe possibilidade de implementação de solução corporativa para que a renovação seja transparente ao usuário final.

c) Como o usuário saberá que não possui direito de uso ao certificado.?

Desde que seja um usuário proveniente do varejo. O usuário terá alterações visuais na interface do aplicativo, receberá notificações e email para comunicar a proximidade do vencimento do direito de uso.

Open

Carteira com o certificado expirado

Open

Tela para realizar a liberação do uso

 

Open

Tela que demonstra os preços do produto no varejo

 

5.Diretrizes de uso da Aplicação

Para o uso aberto da API existem limitações na forma de realizar chamadas aos endpoints e também na quantidade de requisições por segundo:

• /v0/oauth/authorize: Cada aplicação pode fazer no máximo 100 requisições ao authorize por segundo;

• Requisições chamando o /signatures: Cada aplicação pode fazer chamadas incluindo no máximo 20 documentos no lote por requisição;

• CPFs únicos chamando o /signatures por minuto: Cada CPF/ CNPJ pode fazer no máximo 100 requisições ao signatures por minuto;

• Cada aplicação pode solicitar no máximo 5k assinaturas por minuto;

6. Postman: Exemplos de chamadas aos Endpoints

Projeto Postman com as chamadas aos endpoints.

Open