# QI Tech — Banking-as-a-Service › Device Management
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
6 página(s).
Índice:
- Query device (/en/documentation/baas/dispositivo/consultar_dispositivo)
- Approve device creation (/en/documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo)
- Request Device Creation (/en/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)
- Request token resend (/en/documentation/baas/dispositivo/create/solicitacao_reenvio_token)
- Disable device (/en/documentation/baas/dispositivo/delete/desativar_dispositivo)
- Introduction (/en/documentation/baas/dispositivo/introducao)
---
# Query device
URL: /en/documentation/baas/dispositivo/consultar_dispositivo
## Request
ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `device_key` | uuidv4 | Unique device identification key. | 36 |
## Response
STATUS 200
Response Body: Device found
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "05894BAD-C94E-4A61-B2A8-57EDAE868A0F",
"analysis_status": "automatically_approved",
"status": "registered",
"device_registration_data": {
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "05894BAD-C94E-4A61-B2A8-57EDAE868A0F",
"document_number": "438.858.048-16",
"registration_date": "2025-06-30T14:52:13-03:00",
"face_recognition_key": "367195fc-de24-46b0-9ddb-79231dc7eeff"
},
"analysis_status_events": [
{
"new_analisys_status": "automatically_approved",
"reason": null,
"reason_description": null,
"event_date": "2025-06-30T14:52:13Z"
}
],
"status_events": [
{
"new_status": "registered",
"event_date": "2025-06-30T14:52:13Z"
}
],
"registration_date": "2025-06-30T14:52:14Z",
"created_at": "2025-06-30T14:52:13Z"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format | 36 |
| `session_id` * | uuidv4 | Session identifier obtained via device_scan | 36 |
| `analysis_status` * | string | Fraud engine analysis status | **[analysis_status Enumerators](#analysis_status-enumerators)** |
| `status` * | string | Device status | **[status Enumerators](#status-enumerators)** |
| `device_registration_data` * | object | Device registration data | **[device_registration_data Object](#device_registration_data-object)** |
| `analysis_status_events` * | array | History of analysis status change events | - |
| `status_events` * | array | History of device status change events | - |
| `registration_date` * | string | Device registration date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
| `created_at` * | string | Device creation date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
### device_registration_data Object
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format | 36 |
| `session_id` * | uuidv4 | Session identifier obtained via device_scan | 36 |
| `document_number` | string | User's document number (CPF/CNPJ) | 14 |
| `registration_date` * | string | Registration date in ISO format with timezone | 25 |
| `face_recognition_key` | uuidv4 | Face recognition key (when applicable) | 36 |
### analysis_status_event Object
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `new_analisys_status` * | string | New analysis status | **[analysis_status Enumerators](#analysis_status-enumerators)** |
| `reason` | string | Reason for status change (when applicable) | - |
| `reason_description` | string | Description of the reason for status change (when applicable) | - |
| `event_date` * | string | Event date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
### status_event Object
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `new_status` * | string | New device status | **[status Enumerators](#status-enumerators)** |
| `event_date` * | string | Event date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
### analysis_status Enumerators
| Enumerator | Description |
|-------------------------|-----------------------------------------|
| automatically_approved | Automatically approved by fraud engine |
| automatically_reproved | Automatically rejected by fraud engine |
| pending | Pending analysis |
### status Enumerators
| Enumerator | Description |
|--------------------|-----------------------------------------|
| registered | Registered device |
| disabled | Disabled device |
| pending | Device pending approval |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code
`status` | QI Code
`code` | Title
`title` | Description (eng)
`description` | Description (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 404 | OBD000100 | Device not found | No device is associated with the provided device_key. | Nenhum dispositivo está associado à device_key fornecida. |
---
# Approve device creation
URL: /en/documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo
## Request
ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /validate
METHOD PUT
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `device_key` | uuidv4 | Unique device identification key. | 36 |
Request Body
```json
{
"token": "329adf"
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token` * | string | Authentication code sent to the account transaction approver | 6 |
## Response
STATUS 201
Response Body: Device Created
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "created",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code
`status` | QI Code
`code` | Title
`title` | Description (eng)
`description` | Description (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 400 | OBD000088 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | OBD000089 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 400 | OBD000099 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 404 | OBD000100 | Device not found | No device is associated with the provided device_key. | Nenhum dispositivo está associado à device_key fornecida. |
| 400 | OBD0000100 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
---
# Request Device Creation
URL: /en/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo
## Request
ENDPOINT /account/ ACCOUNT_KEY /device
METHOD POST
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
**SMS**
Request Body: SMS Authentication
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "sms",
},
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `session_id` * | uuidv4 | Unique session identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `tfa_info`* | Object | Object containing the approver's document number and contact method or `image_key`. | **[tfa_info Object](#tfa_info-object)** |
### tfa_info Object
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Document number of the account approver. | 11 |
| `contact_type`* | string | Indicates the contact method with the person responsible for account approval. Possible values are **sms**, **email**, or **liveness** (when authentication is performed using image_key).| |
## Response
STATUS 202
Response Body: Transaction Requested
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "pending_2fa_approval",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
**Email**
Request Body: Email Authentication
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email",
},
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `session_id` * | uuidv4 | Unique session identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `tfa_info`* | Object | Object containing the approver's document number and contact method or `image_key`. | **[tfa_info Object](#tfa_info-object)** |
### tfa_info Object
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Document number of the account approver. | 11 |
| `contact_type`* | string | Indicates the contact method with the person responsible for account approval. Possible values are **sms**, **email**, or **liveness** (when authentication is performed using image_key).| |
## Response
STATUS 202
Response Body: Transaction Requested
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "pending_2fa_approval",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
**Image Key**
Request Body: Image Key Authentication
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "liveness",
"image_key": "367195fc-de24-46b0-9ddb-79231dc7eeff",
},
}
```
### Body Params
| Field | Type | Description | Characters |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `session_id` * | uuidv4 | Unique session identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `tfa_info`* | Object | Object containing the approver's document number and contact method or `image_key`. | **[tfa_info Object](#tfa_info-object)** |
### tfa_info Object
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Document number of the account approver. | 11 |
| `contact_type`* | string | Indicates the contact method with the person responsible for account approval. Possible values are **sms**, **email**, or **liveness** (when authentication is performed using image_key).| |
| `image_key` * | uuidv4 | Unique identification key of the image used for facial recognition, in UUID v4 format, obtained through the **liveness** process. | 36 |
## Response
STATUS 202
Response Body: Device Created
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "created",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code
`status` | QI Code
`code` | Title
`title` | Description (eng)
`description` | Description (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 400 | OBD000088 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | OBD000089 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 403 | OBD000090 | No approver permission | Given document number does not belong to an approver for this account string | Número de documento enviado não pertence a um aprovador da conta |
| 400 | OBD000091 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info. |
| 400 | OBD000092 | Invalid device info | Session ID and Device Key must be a valid UUID4 | A Session ID e o Device Key devem ser um UUID4 válidos |
| 404 | OBD000093 | Requester Configuration not found | There is no Requester Configuration attributed to requester_key | Não há Requester Configuration para a requester_key enviada |
| 403 | OBD000094 | Requester not allowed to create a device | Requester has no permission to create a device | Requester não possui permissão para criar um dispositivo |
| 400 | OBD000097 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
---
# Request token resend
URL: /en/documentation/baas/dispositivo/create/solicitacao_reenvio_token
A new token will be generated and sent to the approver responsible for creating the device (only for email or SMS contact cases). If the token validation attempt limit is exceeded, resending will not be allowed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /resend_token
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `device_key` | uuidv4 | Unique device identification key. | 36 |
### Body Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `contact_type`* | string | Indicates the contact method with the person responsible for account approval. Possible values are **sms**, **email**| **[contact_type Enumerator](#contact_type-enumerator)** |
:::info Information
If no `contact_type` is sent, the token will be sent in the originally requested format.
:::
| Enumerator | Description |
|------------|---------------------------------------------------|
| **sms** | Send via Text Message to mobile phone |
| **email** | Send via electronic mail |
## Response
STATUS 202
Response Body: Resend Requested
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "pending_2fa_approval",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code
`status` | QI Code
`code` | Title
`title` | Description (eng)
`description` | Description (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 400 | OBD000088 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | OBD000089 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 400 | OBD000097 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
| 400 | OBD000099 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 404 | OBD000100 | Device not found | No device is associated with the provided device_key. | Nenhum dispositivo está associado à device_key fornecida. |
---
# Disable device
URL: /en/documentation/baas/dispositivo/delete/desativar_dispositivo
## Request
ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /disable
METHOD DELETE
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `device_key` | uuidv4 | Unique device identification key. | 36 |
## Response
STATUS 200
Response Body: Device disabled
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "disabled",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format | 36 |
| `device_status` * | string | Device status | **[device_status Enumerators](#device_status-enumerators)** |
| `created_at` * | string | Device creation date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
### device_status Enumerators
| Enumerator | Description |
|--------------------|-----------------------------------------|
| active | Device active and available for use |
| disabled | Device disabled |
| pending | Device pending approval |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code
`status` | QI Code
`code` | Title
`title` | Description (eng)
`description` | Description (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 400 | OBD000088 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | OBD000089 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 404 | OBD000100 | Device not found | No device is associated with the provided device_key. | Nenhum dispositivo está associado à device_key fornecida. |
---
# Introduction
URL: /en/documentation/baas/dispositivo/introducao
The Onboarding API offers Device Management functionality, allowing partners to register specific devices to users linked to an account. With this functionality, it is possible to reinforce transaction security, ensuring that only authorized devices can perform transactions, which will be validated through the **device token**.
### Device Registration
The registration of a new device for transaction validation is performed through a flow divided into three steps:
---
**I. Registration Request (POST)**
In this step, a `POST` request is sent containing:
- Device data obtained via `device_scan`
- Information required for two-factor authentication (2FA)
Upon completing the request, a 2FA token is generated and sent to the user (by email or SMS). This token ensures that the registration is being performed by the person effectively authorized to link the device.
:::info Note
If authentication is performed through facial recognition, the **image_key** acquired through [liveness](/documentation/caas/face_recognition/api/introduction) must be sent in the 2FA field.
In this case, it will not be necessary to go through the next validation steps.
:::
---
**II. 2FA Token Validation (PUT/PATCH)**
After receiving the 2FA token, the user must validate it using a `PUT` request. If the code needs to be resent (due to loss, non-receipt, or expiration), a `PATCH` request is used to request a new token.
Once the token is successfully validated, the device will be effectively registered in the system.
---
**III. Authentication with Device Token in Future Transactions**
With the device properly registered, it can be used for validation of future transactions. Transactions will be authenticated using the device token, making the process more secure and reliable.
---
### Query a Device
It is possible to query information about a specific device through a `GET` request, providing the `account_key` and `device_key`. This operation returns device details, including its current status, creation date, and last update.
---
### Deactivate a Device
When necessary, a device can be deactivated through a `DELETE` request. Once deactivated, the device can no longer be used for transaction validation, ensuring greater control over operation security.