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:
nome | tipo | descrição |
---|---|---|
id | string | Id da sessão. |
status | string | Status da sessão. |
expiration_date | date | Data de expiração da sessão. Após essa data, a sessão é invalidada. |
step_data | object | Objeto de retorno dos eventos da sessão. |
settings | object | Objeto de configuração da sessão. |
auth_session_hash | string | Hash de identificação da sessão. |
step | string | Etapa atual do usuário. |
auth_session_url | string | Url capaz de coletar as informações do cadastro. |
token | string | Token de autenticação da sessão. |
token_expiration_date | date | Data 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.
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
Nome | Tipo | Descrição |
---|---|---|
image_key | string | Chave de identificação da etapa de face_recognition. |
event_date | date | Data de finalização da etapa. |
personal_document
Nome | Tipo | Descrição |
---|---|---|
document_template | string | Template selecionado pelo usuário no momento da coleta do documento. |
ocr_keys | list | Lista com as chaves de identificação de cada documento coletado. |
event_date | date | Data de finalização da etapa. |
device_scan
Nome | Tipo | Descrição |
---|---|---|
session_id | string | Chave de identificação da etapa de scan do dispositivo. |
event_date | date | Data 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