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

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

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.

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.

5. Postman: Exemplos de chamadas aos Endpoints

Projeto Postman com as chamadas aos endpoints.

Open