Iniciando a Integração

Procedimentos para a Integração

A aplicação que irá consumir os serviços da API da Prova de vida deve estar obrigatoriamente integrada ao sistema do Login Único site externo. Além disso, há necessidade de liberar o ambiente de homologação para aplicação cliente possa utilizar. Essa liberação ocorre por meio do envio das informações listadas abaixo:

  • Credenciais de acesso aos serviços de Homologação

    • CPF de um representante do orgão ou entidade dona do serviço a ser integrado

    • E-mail do representante do orgão ou entidade

    • CPNJ do orgão ou entidade


  • Para pessoas que realizarão testes no Aplicativo (Validação Facial), e não constam na base do TSE, deve-se enviar as informações abaixo para cadastro da biometria facial

    • Nome

    • CPF

    • Foto no formato 3X4


  • Para liberação de acesso ao APP de Homologação, deve-ser enviar a informação:

    • Email do Google ou e-mail AppleID

Essas informações deverão ser encaminhadas para o e-mail: int-provavida-govbr@economia.gov.br, por um representante do órgão ou entidade. O representante ficará responsável pelas credenciais de acesso gerada por integrantes da Secretaria de Governança Digital (SGD) do Ministério da Economia (ME).

Métodos e interfaces de integração

Autenticação

Para que a autenticação aconteça, é preciso chamar serviço com intuito de adquirir um ticket de acesso (token) para os serviços protegidos da Prova de vida. O serviço de autenticação segue o padrão OAuth 2.0 site externo.

A requisição é feita através de um POST para o endereço: https://h.meugov.estaleiro.serpro.gov.br/auth/oauth/token?grant_type=client_credentials

Parâmetros do Header para a requisição: https://h.meugov.estaleiro.serpro.gov.br/auth/oauth/token?grant_type=client_credentials

Variável

Descrição

Content-Type

Tipo do conteúdo da requisição que está sendo enviada. Nesse caso estamos enviando como um application/json

Authorization

Informação codificada em Base64, no seguinte formato: CLIENT_ID:CLIENT_SECRET (senha de acesso do serviço consumidor)(utilizar codificador para Base64 site externo para gerar codificação).

Exemplo de header:

Content-Type: application/json
Authorization: ZWM0MzE4ZDYtZjc5Ny00ZDY1LWI0ZjctMzlhMzNiZjRkNTQ0OkFJSDRoaXBfTUJYcVJkWEVQSVJkWkdBX2dRdjdWRWZqYlRFT2NWMHlFQll4aE1iYUJzS0xwSzRzdUVkSU5FcS1kNzlyYWpaZ3I0SGJuVUM2WlRXV1lJOA==

O serviço retornará, em caso de sucesso, no formato JSON, as informações conforme exemplo:

Response: 200

{
        "access_token": "(Token de acesso a serviços protegidos da Prova de vida.)",
        "token_type": "(O tipo do token gerado. Padrão: Bearer)",
        "expires_in": "(Tempo de vida do token em segundos.)",
        "scope": "(Escopos autorizados pelo provedor de autenticação. Padrão: '*')",
        "cnpj": "(CNPJ da organização solicitante da Prova de vida.)",
        "jti": "(Identificador único do token, reconhecido internamente pelo provedor de autenticação.)"
}

Transação simplificada da Prova de vida

A Transação é sem suporte a resposta automática utilizando selo biométrico GovBr. Ou seja, não apresenta na resposta informações sobre validação facial feita pelo usuário em um momento anterior à solicitação. Portanto, a solicitação de Prova de vida não pode ser autorizada automaticamente.

A Transação cria um pedido de Prova de vida para o cidadão (CPF). O Cidadão é informado via push notification no aplicativo “Meu Gov.Br”. Tem como retorno apenas o UUID da transação.

A autorização do usuário pode ser dada por confirmação ou por biometria facial no app “Meu Gov.Br”.

Parâmetros do Header para POST https://h.meugov.estaleiro.serpro.gov.br/api/vbeta1/transacoes

Variável

Descrição

Content-Type

Tipo do conteúdo da requisição que está sendo enviada. Nesse caso estamos enviando como um application/json

Authorization

Palavra Bearer e o access_token da requisição POST do https://h.meugov.estaleiro.serpro.gov.br/auth/oauth/token?grant_type=client_credentials

Parâmetros do Body para POST https://h.meugov.estaleiro.serpro.gov.br/api/vbeta1/transacoes

{
"solicitante": {
  "cnpj": "(CNPJ do Solicitante.)",
  "nome": "(Orgão Solicitante.)",
  "servico": "(Nome do Serviço cliente.)"
 },
"cpf": "(CPF do usuário que realizará a Prova de Vida.)",
"motivo": "(Motivo da Prova de Vida. Exemplo: Obter benefício previdenciário)",
"tipo": "(Tipo da solicitação. Padrão: 'B')",
"expiracao_em": "(Tempo de vida da transação em minutos)",
"mensagem_falha": "(Mensagem apresentada ao usuário no caso de falha na Prova de vida)",
"mensagem_sucesso": "(Mensagem apresentada ao usuário no caso de sucesso na Prova de vida)"
}

Exemplo de body:

{
"solicitante": {
  "cnpj": "33.683.111/0001-07",
  "nome": "Secretaria de Governo Digital",
  "servico": "AppGovBr"
 },
"cpf": "01534562567",
"motivo": "prova de vida para obtenção de selo",
"tipo": "B",
"expiracao_em": "120",
"mensagem_falha": "Não foi possível confirmar a prova de vida, volte ao sistema XYZ para obter mais informações",
"mensagem_sucesso": "Sua prova de vida foi realizada com sucesso, volte ao sistema XYZ para continuar o processo de autorização"
}

Ao chamar o serviço, o pedido de autorização de transação é criado e enviado para o usuário autorizar usando o App “Meu GovBr”. O serviço retornará, em caso de sucesso, o código que identifica unicamente a transação (UUID), conforme exemplo:

Response: 201

Body

0a4f7059-78b3-1b16-8179-56713d547f8a

Transação com verificação do selo de Biometria Facial

A Transação é com suporte a resposta automática utilizando selo biométrico GovBr. A resposta da requisição contém informações sobre validação facial feita pelo usuário em um momento anterior à solicitação. Portanto, a solicitação de Prova de vida pode ser autorizada automaticamente.

Diferente da transação simplicada, a requisição com verificação do selo possui o parâmetro “selogovbr_reuso_em” no body. O valor desse parâmetro é o intervalo de tempo em minutos anterior a data da transação. A Prova de vida será autorizada automaticamente caso o usuário tiver feito a validação facial dentro desse intervalo.

A Transação cria um pedido de Prova de vida para o cidadão (CPF). O Cidadão é informado via push notification no aplicativo “Meu Gov.Br”.

Caso a Prova de vida não seja autorizada automaticamente, o usuário (cidadão) pode autorizar por confirmação ou por biometria facial no app “Meu Gov.Br”.

Parâmetros do Header para POST https://h.meugov.estaleiro.serpro.gov.br/api/vbeta2/transacoes

Variável

Descrição

Content-Type

Tipo do conteúdo da requisição que está sendo enviada. Nesse caso estamos enviando como um application/json

Authorization

Palavra Bearer e o access_token da requisição POST do https://h.meugov.estaleiro.serpro.gov.br/auth/oauth/token?grant_type=client_credentials

Parâmetros do Body para POST https://h.meugov.estaleiro.serpro.gov.br/api/vbeta2/transacoes

{
"solicitante": {
        "cnpj": "(CNPJ do Solicitante.)",
        "nome": "(Orgão Solicitante.)",
        "servico": "(Nome do Serviço cliente.)"
       },
      "cpf": "(CPF do usuário que realizará a Prova de Vida.)",
      "motivo": "(Motivo da Prova de Vida. Exemplo: Obter benefício previdenciário)",
      "tipo": "(Tipo da solicitação. Padrão: 'B')",
      "selogovbr_reuso_em": "(Intervalo de tempo em minutos anterior a data da transação)",
      "expiracao_em": "(Tempo de vida da transação em minutos)",
      "mensagem_falha": "(Mensagem apresentada ao usuário no caso de falha na Prova de vida)",
      "mensagem_sucesso": "(Mensagem apresentada ao usuário no caso de sucesso na Prova de vida)"
}

Exemplo de body:

{
"solicitante": {
        "cnpj": "33.683.111/0001-07",
        "nome": "Secretaria de Governo Digital",
        "servico": "AppGovBr"
       },
      "cpf": "01534562567",
      "motivo": "prova de vida para obtenção de selo",
      "tipo": "B",
      "selogovbr_reuso_em": "999999",
      "expiracao_em": "120",
      "mensagem_falha": "Não foi possível confirmar a prova de vida, volte ao sistema XYZ para obter mais informações",
      "mensagem_sucesso": "Sua prova de vida foi realizada com sucesso, volte ao sistema XYZ para continuar o processo de autorização"
}

Resultados esperados do Acesso à Transação com verificação do selo

A transação retornará, em caso de autorização automática com selo, no formato JSON, as informações conforme exemplo:

Response: 201

Caso o usuário realizar validação facial antes da data definida no atributo “reusar_apartir”, a transação não é autorizada automaticamente, e retornará, no formato JSON as informações conforme exemplo:

Response: 201

{
     "id": "0a4f7059-78b3-1b16-8179-56713d547f8a",
     "solicitante": {
     "cnpj": "33.683.111/0001-07",
     "nome": "Secretaria de Governo Digital",
     "servico": "AppGovBr"
  },
     "cpf": "01534562567",
     "motivo": "solicitação de prova de vida para liberação de benefício",
     "tipo": "B",
     "criado_em": "2021-05-10T14:14:38.083677-03:00",
     "expiracao_em": "2021-05-10T14:14:38.083677-03:00",
     "selogovbr": {

     "reusar_apartir": "2019-06-16T03:35.083677-03:00",
     "disponivel": true,
     "data": "2019-02-15T15:34:51-03:00",
     "usado": false
  }
}

No exemplo acima, como a transação não foi autorizada automaticamente, o JSON retornado não apresenta o atributo RESPOSTA.

Obter dados usando id das Transações

É possível fazer requisição para obter dados das Transações da Prova de vida usando o id (UUID) retornado pelos serviços:

Para acessar o serviço que disponibiliza os dados vinculados a uma determinada transação, a aplicação cliente deverá realizar uma requisição por meio do método GET à URL: https://h.meugov.estaleiro.serpro.gov.br/api/vbeta2/transacoes/{idtransacao}

Exemplo de requisição:

https://h.meugov.estaleiro.serpro.gov.br/api/vbeta2/transacoes/0a4f7059-78b3-1b16-8179-5746089d7fb7

Parâmetros para GET https://h.meugov.estaleiro.serpro.gov.br/api/vbeta2/transacoes/{idtransacao}

Variável

Descrição

Authorization

No header, palavra Bearer e o acess_token da requisição POST do https://h.meugov.estaleiro.serpro.gov.br/auth/oauth/token?grant_type=client_credentials

idtransação

id (UUID) da transação de prova de vida

O resultado em formato JSON depende se o id utilizado for de uma Transação simplificada da Prova de vida ou de uma Transação com verificação do selo de Biometria Facial.

Exemplos de Resultado:

  • O atributo RESPOSTA do código JSON abaixo indica que o usuário já respondeu a autorização para realizar prova de vida e qual foi a resposta. Caso o usuário não tivesse respondido a autorização, o atributo RESPOSTA não estaria presente.

Response: 200

{
  "id": "0a4f7059-78b3-1b16-8179-5746089d7fb7",
  "solicitante": {
  "cnpj": "Secretaria de Governo Digital",
  "nome": "SERPRO",
  "servico": "AppGovBr"
},
  "motivo": "string",
  "tipo": "B",
  "criado_em": "2020-06-08T19:42:54-03:00",
  "expiracao_em": "2020-06-08T23:42:54-03:00",
  "resposta": {
  "autorizado": true,
  "data": "2020-06-08T22:31:45-03:00"
}
}

  • O código JSON abaixo é um exemplo de resposta para um id cuja transação foi autorizada automaticamente.

Response: 200

{
  "id": "fb5g8247-95c1-2f23-9580-6813178c9bf8",
     "solicitante": {
     "cnpj": "33.683.111/0001-07",
     "nome": "Secretaria de Governo Digital",
     "servico": "AppGovBr"
  },
     "cpf": "01534562567",
     "motivo": "solicitação de prova de vida para liberação de benefício",
     "tipo": "B",
     "criado_em": "2021-05-10T14:14:38.083677-03:00",
     "expiracao_em": "2021-05-10T16:14:38.083677-03:00",
     "selogovbr": {

     "reusar_apartir": "2019-06-16T03:35.083677-03:00",
     "disponivel": true,
     "data": "2021-04-23T15:34:51-03:00",
     "usado": true
  },
     "resposta": {
     "autorizado": true,
     "data": "2021-05-10T14:14:38.083677-03:00"
    }
}

Enviar mensagens para o usuário

Para acessar o serviço que envia mensagem ao usuário, a aplicação cliente deverá realizar uma requisição por meio do método POST à URL: https://h.meugov.estaleiro.serpro.gov.br/api/vbeta1/mensagens

Parâmetros do Header para POST https://h.meugov.estaleiro.serpro.gov.br/api/vbeta1/mensagens

Variável

Descrição

Authorization

Palavra Bearer e o acess_token da requisição POST do https://h.meugov.estaleiro.serpro.gov.br/auth/oauth/token?grant_type=client_credentials

Content-Type

Tipo do conteúdo da requisição que está sendo enviada. Nesse caso estamos enviando como um application/json

Parâmetros do Body para POST https://h.meugov.estaleiro.serpro.gov.br/api/vbeta1/mensagens

{
"remetente": {
  "cnpj": "(CNPJ do orgão dono da aplicação cliente.)",
  "nome": "(Nome do Orgão.)"
},
"titulo": "(Título da mensagem a ser enviada para o usuário.)",
"conteudo": "(Conteúdo da mensagem.)",
"tipo": "(Tipo da requisição. Padrão B)",
"cpf": "(CPF do usuário para o qual deseja enviar a mensagem.)"
}

Ao chamar o serviço, a mensagem é enviada para o usuário, que recebe via push notification no aplicativo “Meu GovBr”. A mensagem pode ser enviada diretamente ao cidadão (CPF) ou enviada para todos (broadcast). Caso seja enviada para todos, o parâmetro “cpf” não deve ser informado na requisição.

O serviço retornará, em caso de sucesso, o código que identifica unicamente a mensagem (UUID), conforme exemplo:

Response: 201

Body

{“7f000101-729a-1bab-8172-9a9c74160001”}

A aplicação cliente, utilizando determinados serviços, pode utilizar o id da mensagem para receber informações sobre a mesma ou para deletá-la.

Exemplos de requisição:


Resultados Esperados e Erros do Acesso aos Serviços da Prova de Vida

Como visto anteriormente, os acessos aos serviços (transações) da Prova de Vida ocorrem por meio de chamadas de URLs e as respostas são códigos presentes conforme padrão do protocolo HTTP por meio do retorno JSON. O retorno mostra o código de sucesso ou de erro e a respectiva descrição.

Exemplos de códigos HTTP de sucesso:

  • 200: Sucesso

  • 201: Dado cadastrado com Sucesso, retornando o ID do dado


Exemplos de códigos HTTP de erro:

  • 400: Algum dado informado incorretamente. Exemplo:

{
"status": "BAD_REQUEST",
"message": "Argumentos não válidos",
"errors": {
  "cpf": "número do registro de contribuinte individual brasileiro (CPF) inválido"
  }
}

  • 401: Usuário não autenticado

  • 422: Erro de validação na requisição. Exemplo:

{
"timestamp": "2021-05-10T14:14:38.083677-03:00",
"status": 422,
"error": "Unprocessable Entity",
"message": "A não é um tipo válido [B,C]",
"path": "/vbeta1/transacoes"
}