# QI Tech — Banking-as-a-Service › Gestão de Dispositivos Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 6 página(s). Índice: - Consultar dispositivo (/documentation/baas/dispositivo/consultar_dispositivo) - Aprovar criação de dispositivo (/documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo) - Solicitar Criação de Dispositivo (/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo) - Solicitar reenvio de token (/documentation/baas/dispositivo/create/solicitacao_reenvio_token) - Desativar dispositivo (/documentation/baas/dispositivo/delete/desativar_dispositivo) - Introdução (/documentation/baas/dispositivo/introducao) --- # Consultar dispositivo URL: /documentation/baas/dispositivo/consultar_dispositivo ## Request ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |---------------|--------|----------------------------------------|------------| | `account_key` | uuidv4 | Chave única de identificação da conta. | 36 | | `device_key` | uuidv4 | Chave única de identificação do dispositivo. | 36 | ## Response STATUS 200 Response Body: Dispositivo encontrado ```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 | Campo | Tipo | Descrição | Caracteres | |-------------------------|--------|-------------------------------------------------------------------------------------|------------| | `device_key` * | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4 | 36 | | `session_id` * | uuidv4 | Identificador da sessão obtido via device_scan | 36 | | `analysis_status` * | string | Status da análise do motor de fraude | **[Enumeradores analysis_status](#enumeradores-analysis_status)** | | `status` * | string | Status do dispositivo | **[Enumeradores status](#enumeradores-status)** | | `device_registration_data` * | object | Dados de registro do dispositivo | **[Objeto device_registration_data](#objeto-device_registration_data)** | | `analysis_status_events` * | array | Histórico de eventos de mudança de status de análise | - | | `status_events` * | array | Histórico de eventos de mudança de status do dispositivo | - | | `registration_date` * | string | Data de registro do dispositivo no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 | | `created_at` * | string | Data de criação do dispositivo no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 | ### Objeto device_registration_data | Campo | Tipo | Descrição | Caracteres | |-------------------------|--------|-------------------------------------------------------------------------------------|------------| | `device_key` * | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4 | 36 | | `session_id` * | uuidv4 | Identificador da sessão obtido via device_scan | 36 | | `document_number` | string | Número do documento (CPF/CNPJ) do usuário | 14 | | `registration_date` * | string | Data de registro no formato ISO com fuso horário | 25 | | `face_recognition_key` | uuidv4 | Chave de reconhecimento facial (quando aplicável) | 36 | ### Objeto analysis_status_event | Campo | Tipo | Descrição | Caracteres | |-------------------------|--------|-------------------------------------------------------------------------------------|------------| | `new_analisys_status` * | string | Novo status de análise | **[Enumeradores analysis_status](#enumeradores-analysis_status)** | | `reason` | string | Razão da mudança de status (quando aplicável) | - | | `reason_description` | string | Descrição da razão da mudança de status (quando aplicável) | - | | `event_date` * | string | Data do evento no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 | ### Objeto status_event | Campo | Tipo | Descrição | Caracteres | |-------------------------|--------|-------------------------------------------------------------------------------------|------------| | `new_status` * | string | Novo status do dispositivo | **[Enumeradores status](#enumeradores-status)** | | `event_date` * | string | Data do evento no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 | ### Enumeradores analysis_status | Enumerador | Descrição | |-------------------------|-----------------------------------------| | automatically_approved | Aprovado automaticamente pelo motor de fraude | | automatically_reproved | Reprovado automaticamente pelo motor de fraude | | pending | Pendente de análise | ### Enumeradores status | Enumerador | Descrição | |--------------------|-----------------------------------------| | registered | Dispositivo registrado | | disabled | Dispositivo desativado | | pending | Dispositivo pendente de aprovação | STATUS 4xx Response Body: Error ```json { "title": "titulo", "description": "description in English", "translation": "descrição em portugues", "code": "codigo", "extra_fields": {} } ``` | Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (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. | --- # Aprovar criação de dispositivo URL: /documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo ## Request ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /validate MÉTODO PUT ### Path Params | Campo | Tipo | Descrição | Caracteres | |---------------|--------|----------------------------------------|------------| | `account_key` | uuidv4 | Chave única de identificação da conta. | 36 | | `device_key` | uuidv4 | Chave única de identificação do dispositivo. | 36 | Request Body ```json { "token": "329adf" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |-----------|--------|-----------------------------------------------------------------------|------------| | `token` * | string | Código de autenticação enviado ao aprovador de movimentações da conta | 6 | ## Response STATUS 201 Response Body: Dispositivo Criado ```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": {} } ``` | Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (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 | --- # Solicitar Criação de Dispositivo URL: /documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo ## Request ENDPOINT /account/ ACCOUNT_KEY /device MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |---------------|--------|----------------------------------------|------------| | `account_key` | uuidv4 | Chave única de identificação da conta. | 36 | **SMS** Request Body: Autenticação via SMS ```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 | Campo | Tipo | Descrição | Caracteres | |-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------| | `device_key` * | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador). | 36 | | `session_id` * | uuidv4 | Chave única de identificação da sessão no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador). | 36 | | `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato ou `image_key`. | **[Objeto tfa_info](#objeto-tfa_info)** | ### Objeto tfa_info | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|-------------------------------------------------------------------------------------|------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 11 | | `contact_type`* | string | Indica o método de contato com a pessoa responsável pela aprovação da conta. Os valores possíveis são **sms**, **email**, ou **liveness** (quando a autenticação for realizada utilizando image_key).| | ## Response STATUS 202 Response Body: Transação Solicitada ```json { "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "device_status": "pending_2fa_approval", "created_at": "2024-12-22T20:30:23.459Z" } ``` **Email** Request Body: Autenticação via Email ```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 | Campo | Tipo | Descrição | Caracteres | |-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------| | `device_key` * | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador). | 36 | | `session_id` * | uuidv4 | Chave única de identificação da sessão no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador). | 36 | | `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato ou `image_key`. | **[Objeto tfa_info](#objeto-tfa_info)** | ### Objeto tfa_info | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|-------------------------------------------------------------------------------------|------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 11 | | `contact_type`* | string | Indica o método de contato com a pessoa responsável pela aprovação da conta. Os valores possíveis são **sms**, **email**, ou **liveness** (quando a autenticação for realizada utilizando image_key).| | ## Response STATUS 202 Response Body: Transação Solicitada ```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: Autenticação via Image Key ```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 | Campo | Tipo | Descrição | Caracteres | |----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| | `device_key` * | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador). | 36 | | `session_id` * | uuidv4 | Chave única de identificação da sessão no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador). | 36 | | `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato ou `image_key`. | **[Objeto tfa_info](#objeto-tfa_info)** | ### Objeto tfa_info | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|-------------------------------------------------------------------------------------|------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 11 | | `contact_type`* | string | Indica o método de contato com a pessoa responsável pela aprovação da conta. Os valores possíveis são **sms**, **email**, ou **liveness** (quando a autenticação for realizada utilizando image_key).| | | `image_key` * | uuidv4 | Chave única de identificação da imagem utilizada para reconhecimento facial, no formato UUID v4, obtida por meio do processo de **liveness**. | 36 | ## Response STATUS 202 Response Body: Dispositivo Criado ```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": {} } ``` | Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (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 | --- # Solicitar reenvio de token URL: /documentation/baas/dispositivo/create/solicitacao_reenvio_token Um novo token será gerado e enviado ao aprovador responsável pela criação do dispositivo (apenas nos casos de contato por email ou SMS). Caso o limite de tentativas de validação do token seja excedido, o reenvio não será permitido. ## Request ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /resend_token MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |---------------|--------|----------------------------------------|------------| | `account_key` | uuidv4 | Chave única de identificação da conta. | 36 | | `device_key` | uuidv4 | Chave única de identificação do dispositivo. | 36 | ### Body Params | Campo | Tipo | Descrição | Caracteres | |---------------|--------|----------------------------------------|------------| | `contact_type`* | string | Indica o método de contato com a pessoa responsável pela aprovação da conta. Os valores possíveis são **sms**, **email**| **[Enumerador contact_type](#enumerador-contact_type)** | :::info Informação Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente. ::: | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por Mensagem de Texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response STATUS 202 Response Body: Reenvio Solicitado ```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": {} } ``` | Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (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. | --- # Desativar dispositivo URL: /documentation/baas/dispositivo/delete/desativar_dispositivo ## Request ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /disable MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |---------------|--------|----------------------------------------|------------| | `account_key` | uuidv4 | Chave única de identificação da conta. | 36 | | `device_key` | uuidv4 | Chave única de identificação do dispositivo. | 36 | ## Response STATUS 200 Response Body: Dispositivo desativado ```json { "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "device_status": "disabled", "created_at": "2024-12-22T20:30:23.459Z" } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres | |-------------------------|--------|-------------------------------------------------------------------------------------|------------| | `device_key` * | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4 | 36 | | `device_status` * | string | Status do dispositivo | **[Enumeradores device_status](#enumeradores-device_status)** | | `created_at` * | string | Data de criação do dispositivo no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 | ### Enumeradores device_status | Enumerador | Descrição | |--------------------|-----------------------------------------| | active | Dispositivo ativo e disponível para uso | | disabled | Dispositivo desativado | | pending | Dispositivo pendente de aprovação | STATUS 4xx Response Body: Error ```json { "title": "titulo", "description": "description in English", "translation": "descrição em portugues", "code": "codigo", "extra_fields": {} } ``` | Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (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. | --- # Introdução URL: /documentation/baas/dispositivo/introducao A API de Onboarding oferece a funcionalidade de Gestão de Dispositivos, permitindo que parceiros cadastrem dispositivos específicos a usuários vinculados a uma conta. Com essa funcionalidade, é possível reforçar a segurança das operações, garantindo que apenas dispositivos autorizados possam realizar transações, as quais serão validadas por meio do **token do dispositivo**. ### Cadastro de Dispositivo O cadastro de um novo dispositivo para validação de transações é realizado por meio de um fluxo dividido em três etapas: --- **I. Solicitação de Cadastro (POST)** Nesta etapa, é enviada uma requisição `POST` contendo: - Dados do dispositivo obtidos via `device_scan` - Informações necessárias para a autenticação de dois fatores(2FA) Ao concluir a solicitação, um token 2FA é gerado e encaminhado ao usuário (por e-mail ou SMS). Esse token assegura que o cadastro está sendo realizado pela pessoa efetivamente autorizada a vincular o dispositivo. :::info Observação Caso a autenticação seja feita por reconhecimento facial, a **image_key** adquirida através da [liveness](/documentation/caas/face_recognition/api/introduction) deverá ser enviada no campo de 2FA. Nesse caso, não será necessário passar pelos próximos passos de validação. ::: --- **II. Validação do Token 2FA (PUT/PATCH)** Após receber o token 2FA, o usuário deve validá-lo utilizando uma requisição `PUT`. Caso o código precise ser reenviado (por perda, não recebimento ou expiração), utiliza-se uma requisição `PATCH` para solicitar um novo token. Uma vez que o token seja validado com sucesso, o dispositivo será efetivamente registrado no sistema. --- **III. Autenticação com o Token do Dispositivo em Transações Futuras** Com o dispositivo devidamente cadastrado, ele poderá ser utilizado na validação de transações futuras. As transações serão autenticadas utilizando o token do dispositivo, tornando o processo mais seguro e confiável. --- ### Consultar um Dispositivo É possível consultar as informações de um dispositivo específico através de uma requisição `GET`, fornecendo a `account_key` e a `device_key`. Esta operação retorna os detalhes do dispositivo, incluindo seu status atual, data de criação e última atualização. --- ### Desativar um Dispositivo Quando necessário, um dispositivo pode ser desativado através de uma requisição `DELETE`. Uma vez desativado, o dispositivo não poderá mais ser utilizado para validação de transações, garantindo maior controle sobre a segurança das operações.