Skip to main content

Gestão de Sessão

Ao criar uma sessão de autenticação, basta utilizar o link gerado para iniciar o fluxo de cadastro do usuário. Isso pode ser feito através do envio do link ou do uso dele diretamente em seu website, com ferramentas como iframe.

Objeto de retorno

O objeto de retorno da criação e resgate de uma auth_session contém as seguintes informações:

Response Body
  {
"id": "12345678",
"status": "pending",
"expiration_date": "2025-12-11T11:37:15.12-03:00",
"step_data": {
"face_recognition": {
"image_key": "65441d8d-015a-4a0f-97b6-b7d4fc5619b7",
"event_date": "2025-12-11T11:37:15.12-03:00"
},
"personal_document": {
"document_template": "rg",
"ocr_keys": [
"e13c71d0-ae0e-48e2-8c42-26f997412039",
"3991b716-0980-409f-8e33-e3a8dd9a671c"
],
"event_date": "2025-12-11T11:37:15.12-03:00"
},
"device_scan": {
"session_id": "4d450227-c77c-4487-830b-42dcd127798a",
"event_date": "2025-12-11T11:37:15.12-03:00"
}
}
"settings": {
...
},
"auth_session_hash": "1cFL1vM",
"step": "device_scan",
"auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
"token": "fc0aaa39-1c21-1bc1-a5a1-39a7ca01121b",
"token_expiration_date": "2025-12-10T11:37:15.12-03:00",
}

Esse objeto é retornado no enpoint de resgate da sessão:

GET https://api.caas.qitech.app/auth_session_manager/auth_session/{id}

Descrição do campos de resposta:

nometipodescrição
idstringId da sessão.
statusstringStatus da sessão.
expiration_datedateData de expiração da sessão. Após essa data, a sessão é invalidada.
step_dataobjectObjeto de retorno dos eventos da sessão.
settingsobjectObjeto de configuração da sessão.
auth_session_hashstringHash de identificação da sessão.
stepstringEtapa atual do usuário.
auth_session_urlstringUrl capaz de coletar as informações do cadastro.
tokenstringToken de autenticação da sessão.
token_expiration_datedateData de expiração do token temporário de autenticação. Padrão definido para 2 horas após a geração da sessão.

Status

Possíveis status:

  • pending
  • completed
  • expired

Objeto step_data

Objeto que contém os dados coletados de cada step.

Informação

Caso o step não esteja listado nas settings da sessão, o mesmo não estará presente como campo do objeto step_data

face_recognition

NomeTipoDescrição
image_keystringChave de identificação da etapa de face_recognition.
event_datedateData de finalização da etapa.

personal_document

NomeTipoDescrição
document_templatestringTemplate selecionado pelo usuário no momento da coleta do documento.
ocr_keyslistLista com as chaves de identificação de cada documento coletado.
event_datedateData de finalização da etapa.

device_scan

NomeTipoDescrição
session_idstringChave de identificação da etapa de scan do dispositivo.
event_datedateData de finalização da etapa.

Autenticação do fluxo web

Para garantir mais segurança para a aplicação, retornamos um token temporário para a página web. É possível resgatar o token, ou gerar um novo através do endpoint:

POST https://api.caas.qitech.app/auth_session_manager/auth_session/{id}/token

Request Body
  {}
Response Body
  {
"id": "12345678",
"token": "e7e99a40-0b26-4bb9-a068-9fa4886eeef3",
"token_expiration_date": "2025-12-10T13:37:15.12-03:00",
}

Assim, caso o token tenha expirado, é possível seguir com a sessão de autenticação gerando um novo token.

Comunicação com a página web

A página web poderá ser integrada através de uma ferramenta chamada iframe. Da seguinte maneira:

<iframe id="iframe" src="" href="{auth_session_url}"></iframe>

Caso o link seja chamado dessa maneira, a página web irá enviar mensagens de retorno para a página que a requisitou. As possíveis mensagens de retorno são:

  • success
  • canceled
  • invalid_token
  • expired

Que podem ser acessadas da seeguinte maneira:

window.addEventListener("message", (event) => {
if (event.data === "canceled") {
//close iframe
}
if (event.data === "invalid_token") {
//close iframe
}
if (event.data === "success") {
//close iframe
}
if (event.data === "expired") {
//close iframe
}
});

Finalização do fluxo

Este serviço irá gerenciar o fluxo de coleta de dados de autenticação, que poderão ser utilizados nos demais serviços. Para mais informações de como utilizar as chaves retornadas nos demais produtos, segue o exemplo da análise cadastral de pessoa física Análise Cadastral