# QI Tech — Risk Solutions › OCR Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 19 página(s). Índice: - Coletando os Retornos (/documentation/caas/ocr/android/collecting_response) - DocumentRecognitionStep (/documentation/caas/ocr/android/document_step) - Soluções híbridas (/documentation/caas/ocr/android/hybrid_solutions) - Introdução (/documentation/caas/ocr/android/introduction) - Integração nativa (/documentation/caas/ocr/android/native_java) - Status HTTP (/documentation/caas/ocr/api/http_status) - Introdução (/documentation/caas/ocr/api/introduction) - Enviando um Documento (/documentation/caas/ocr/api/send_image) - Coletando os Retornos (/documentation/caas/ocr/ios/collecting_response) - QITechIosOcrConfiguration (/documentation/caas/ocr/ios/configuration) - Soluções híbridas (/documentation/caas/ocr/ios/hybrid_solutions) - Introdução (/documentation/caas/ocr/ios/introduction) - Importando o SDK (/documentation/caas/ocr/ios/native_swift) - Coletando os Retornos (/documentation/caas/ocr/web/collecting_results) - O construtor QiTechWebOCR.WebOCR() (/documentation/caas/ocr/web/constructor_info) - Implementação (/documentation/caas/ocr/web/example) - Importando a biblioteca (/documentation/caas/ocr/web/import) - A função initialize() (/documentation/caas/ocr/web/initialize_info) - Introdução (/documentation/caas/ocr/web/introduction) --- # Coletando os Retornos URL: /documentation/caas/ocr/android/collecting_response Para obter o objeto **RequestResponseObject**, que contém as capturas obtidas pelo SDK, sobrescreva o método *onActivityResult* na mesma *activity* que você iniciou a **DocumentRecognitionActivity**: ```java @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); DocumentRecognition.RequestResponseObject result; if (requestCode == REQUEST_CODE){ if (resultCode == RESULT_OK && data != null){ DocumentRecognition.RequestResponseObject mRequestResponseObject = data.ParcelableExtra("result"); } } } ``` ### Descrição dos Atributos do Objeto RequestResponseObject Atributo | Descrição --------- | --------- ocr_key | Chave de identificação da imagem fornecida que pode ser utilizada em qualquer outro serviço do sistema QI Tech. template | Identifica a qual foto aquela OCR Key se refere. --- # DocumentRecognitionStep URL: /documentation/caas/ocr/android/document_step O fluxo de captura de documentos que o usuário será submetido é definido através de um array de objetos do tipo **DocumentRecognitionStep** (disponível no SDK), em que cada elemento é um dos passos de captura realizado pelo usuário. ```java DocumentSteps = new DocumentRecognitionStep[]{ new DocumentRecognitionStep(Document.cnh_front), new DocumentRecognitionStep(Document.cnh_back) }; ``` Acima, é implementado um fluxo que coletará do usuário primeiro a frente de seu CNH (cnh_front) e, depois de validada a coleta de uma foto de qualidade, o verso do CNH. O objeto DocumentRecognitionStep pode assumir os seguintes valores: ```java public enum Document { cnh, // Carteira Nacional de Habilitação brasileira completa cnh_front, // Carteira Nacional de Habilitação brasileira frente (Lado da foto) cnh_back, // Carteira Nacional de Habilitação brasileira frente (Lado da assinatura) cnh_digital, // PDF da Carteira Nacional de Habilitação brasileira digital rg_front, // Carteira de Identidade brasileira frente (Lado da foto) rg_back, // Carteira de Identidade brasileira verso (Lado dos dados) proof_of_address, // Comprovante de Residência other // Outros documentos de identificação } ``` --- # Soluções híbridas URL: /documentation/caas/ocr/android/hybrid_solutions Além de oferecer integração nativa em Java, nossas SDKs também são compatíveis com diversos frameworks híbridos. Isso é possível através da integração de plugins nativos específicos para cada um desses frameworks. Utilizando o sistema nativo de cada solução, é viável incorporar nosso SDK nativa no ambiente Android. Algumas das tecnologias híbridas mais utilizadas são o React Native ([Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)), Cordova ([Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)), Ionic ([Native](https://ionicframework.com/docs/v3/native/)), Unity ([Native Plug-in para Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)), Xamarin ([Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)), Appcelerator, Phonegap e Node. Para facilitar o processo de integração com nossas soluções nativas, disponibilizamos plugins para os frameworks React Native e Flutter. Caso tenha interesse, provemos a documentação e um exemplo de integração em nossos repositórios privados. Para as demais tecnologias híbridas, temos alguns exemplos de implementação dessa ponte para o código nativo. Fique à vontade para entrar em contato com nosso suporte para obter acesso. --- # Introdução URL: /documentation/caas/ocr/android/introduction Bem vindo ao SDK Android de OCR (Optical Character Recognition) para leitura de documentos da QI Tech. Este SDK realiza a captura de documentos e envio a API de OCR da QI Tech . Você pode utilizá-lo para capturar através do seu aplicativo uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech. ## Problemas? Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida! ### Adoramos Feedback Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu! :::danger Aviso Importante! Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech. ::: --- # Integração nativa URL: /documentation/caas/ocr/android/native_java Para importar nossas SDKs, é necessário realizar alteração no _build.gradle_ de Projeto e de Aplicativo. ## Adicionando ao Projeto Adicione o endereço de nosso repositório maven no _build.gradle_ do projeto (no Android Studio este arquivo aparece como: **"Project: \{nome_do_projeto\}"**), conforme exemplo abaixo. ```java maven { url 'https://sdks.qitech.com.br/' } ``` ## Adicionando ao Aplicativo Após isso, adicione a biblioteca que você pretende importar em seu build.gradle do app (no Android Studio este arquivo aparece como: **"Module: \{nome_do_projeto\}.app"**), incluindo a dependência apresentada abaixo. ```java dependencies { implementation 'com.qitech.android:documentrecognition:v5.0.0' } ``` :::warning Desde **abril de 2025**, novas políticas da Google Play requerem **Android API Level 35** para que aplicativos possam ser publicados ou atualizados na Google Play Store. Por isso recomendamos fortemente que utilize **targetSdkVersion na versão 35** pelo menos. ::: :::info A utilização de **targetSdkVersion 35** implica na utilização do **compileSdkVersion 35**, o que desencadeia alguns **requisitos mínimos** para ferramentas do ecossistema do Android: * compileSdkVersion 35 --> AGP 8.6.0 * AGP 8.6.0 --> Gradle 8.7 * AGP 8.6.0 --> Java 17 (JDK 17) * AGP 8.6.0 --> Kotlin 2+ ::: ## Iniciando o SDK Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através de um componente Builder e submetê-lo como parâmetro via Intent Extra para a DocumentRecognitionActivity. ```java Intent intent = new Intent(context, DocumentRecognitionActivity.class); var onboardingTextConfiguration = new OnboardingTextConfiguration( "Conselhos relevantes", // Título "Esteja com o documento visível", // Primeira Instrução "Encaixe seu documento nas marcas", // Segunda Instrução "Retire o plastico que cobre o documento" // Terceira Instrução ); DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder(sand_mobile_token) .setDocumentSteps(DocumentSteps) .setSandboxEnvironment() .setSessionId("SESSION_ID") .setFontColor("#000000") .setBackgroundColor("#FFFFFF") .setFontFamily(DocumentRecognition.FontFamily.open_sans) .setShowIntroductionScreens(true) .setShowSuccessScreen(true) .setOnboardingTextConfiguration(onboardingTextConfiguration) .setLogLevel(DocumentRecognition.LogLevel.debug) .build(); intent.putExtra("settings", mDocumentRecognition); startActivityForResult(intent, REQUEST_CODE); ``` **Versões anteriores à v4.0.0** ```java Intent intent = new Intent(context, DocumentRecognitionActivity.class); VisualConfiguration visualConfiguration = new VisualConfiguration() .setOnboardingDrawable(R.drawable.introscreen,500) .setDocumentFrontDrawable(R.drawable.documentfront, 500) .setDocumentBackDrawable(R.drawable.documentback, 500); TextConfiguration textConfiguration = new TextConfiguration() .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Vamos começar!") .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado") .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire o documento do plástico") .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu documento na moldura, aguardando que fique verde para realizar a captura."); DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH") .setDocumentSteps(DocumentSteps) .setVisualConfiguration(visualConfiguration) .setTextConfiguration(textConfiguration) .showIntroductionScreens(true) .setShowSuccessScreen(false) .setBackgroundColor("#000000") .setFontColor("#FFFFFF") .setFontFamily(DocumentRecognition.FontFamily.open_sans) .setSessionId("SESSION_ID") .setLogLevel(DocumentRecognition.LogLevel.debug) .build(); intent.putExtra("settings", mDocumentRecognition); startActivityForResult(intent, REQUEST_CODE); ``` Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br . Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente. :::info **Atenção** Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte. ::: ## DocumentRecognition.Builder | Parâmetro | Função | Obrigatório | |------------|--------------|--------------| |mobileToken |Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o mailto: suporte.caas@qitech.com.br.|Sim.| |.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|Define o fluxo de captura de documentos realizado pelo usuário. Mais informações [aqui](/documentation/caas/ocr/android/document_step)|Sim.| |.setSandboxEnvironment()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.|Não.| |.setSessionId(String sessionId)| Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da OCR através de logs. Este campo aceita até 255 caracteres. |Não.| |.setFontColor(String fontColor)|Permite a configuração da cor da fonte e dos ícones das activities do SDK.|Não. O padrão é "#1C49A5".| |.setBackgroundColor(String backgroundColor)|Permite a configuração da cor de background das activities do SDK.|Não. O padrão é "#FCFCFC".| |.setFontFamily(FontFamily fontFamily)| Permite a configuração da fonte das activities do SDK.| Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.|Não.| |.showIntroductionScreens(Boolean showIntroductionScreens)|Quando "false" desativa as telas de introdução à coleta de foto do documento que aparecem para o usuário.|Não. O padrão é "true".| |.setShowSuccessScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de sucesso após a coleta da foto.|Não. O padrão é "true".| |.setOnboardingTextConfiguration(OnboardingTextConfiguration onboardingTextConfiguration) |Permite a customização das instruções na tela de introdução. | Não.| |.setLogLevel(DocumentRecognition.LogLevel logLevel)| Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. |Não.| **Versões anteriores à v4.0.0** | Parâmetro | Função | Obrigatório | |------------|--------------|--------------| |mobileToken |Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o mailto: suporte.caas@qitech.com.br.|Sim.| |.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|Define o fluxo de captura de documentos realizado pelo usuário. Mais informações [aqui](/documentation/caas/ocr/android/document_step)|Sim.| |.setSandboxEnvironment()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.|Não.| |.showIntroductionScreens(Boolean showIntroductionScreens)|Quando "false" desativa as telas de introdução à coleta de foto do documento que aparecem para o usuário.|Não. O padrão é "true".| |.setShowSuccessScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de sucesso após a coleta da foto.|Não. O padrão é "true".| |.setBackgroundColor(String backgroundColor)|Permite a configuração da cor de background das activities do SDK.|Não. O padrão é "#ffffff".| |.setFontColor(String fontColor)|Permite a configuração da cor da fonte e dos ícones das activities do SDK.|Não. O padrão é "#000000".| | .setFontFamily(FontFamily fontFamily)| Permite a configuração da fonte das activities do SDK.| Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.|Não.| |.setVisualConfiguration(VisualConfiguration visualConfiguration)| Utilizado para customizar as imagens mostradas para o usuário ao longo da execução do SDK.|Não.| |.setTextConfiguration(TextConfiguration textConfiguration) | Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução do SDK.|Não.| |.setSessionId(String sessionId)| Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da OCR através de logs. Este campo aceita até 255 caracteres. |Não.| |.setLogLevel(DocumentRecognition.LogLevel logLevel)| Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. |Não.| ## O Objeto VisualConfiguration :::warning __DEPRECADO__ A PARTIR DA **v4.0.0**! ::: | Parâmetro | Função | Obrigatório | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | .setOnboardingDrawable(int onboarding_drawable, int onboarding_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de onboarding do SDK. O parâmetro _onboarding_drawable_ deve referenciar o id da imagem a ser mostrada e _onboarding_width_ é o tamanho desejado de exibição desta imagem. | Não. | | .setDocumentFullDrawable(int documentfull_drawable, int documentfull_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH inteira do SDK. O parâmetro _documentfull_drawable_ deve referenciar o id da imagem a ser mostrada e _documentfull_width_ é o tamanho desejado de exibição desta imagem. | Não. | | .setDocumentFrontDrawable(int documentfront_drawable, int documentfront_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH e RG frente do SDK. O parâmetro _documentfront_drawable_ deve referenciar o id da imagem a ser mostrada e _documentfront_width_ é o tamanho desejado de exibição desta imagem. | Não. | | .setDocumentBackDrawable(int documentback_drawable, int documentback_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH e RG verso do SDK. O parâmetro _documentback_drawable_ deve referenciar o id da imagem a ser mostrada e _documentback_width_ é o tamanho desejado de exibição desta imagem. | Não. | | .setButtonBorderSize(int border_size) | Utilizado para configurar a largura de borda dos botões do SDK. | Não. O padrão é _1_. | | .setButtonShadow(boolean button_shadow) | Quando setado para _false_ remove o efeito de sombra, padrão no android, utilizado pelos botões do SDK. | Não. O padrão é _true_. | ## O Objeto TextConfiguration :::warning __DEPRECADO__ A PARTIR DA **v4.0.0**! ::: | Parâmetro | Função | Obrigatório | | ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- | | .setCustomText(CustomLabel label, String text) | Utilizado para configurar os textos mostrados para o usuário na tela de onboarding do SDK | Não. | --- # Status HTTP URL: /documentation/caas/ocr/api/http_status Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 : Status HTTP | Significado | Descrição ---------- | ------- | --------------------------------- 400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro. 401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação . 403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key. 404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado. 405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado. 406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido. 409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor. 500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente. 503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores. --- # Introdução URL: /documentation/caas/ocr/api/introduction Bem vindo à API de OCR (Optical Character Recognition) para leitura de documentos da QI Tech. Você pode utilizar esta API para enviar uma imagem de um documento a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech. ## Problemas? Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida! ### Adoramos Feedback Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu! ## Ambientes Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são: * Produção - `https://api.caas.qitech.app/ocr/` * Sandbox - `https://api.sandbox.caas.qitech.app/ocr/` :::danger Aviso Importante! Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech. ::: ## Somente HTTPS Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas. ## Autenticação > Para autenticar uma chamada, utilize o código seguinte: ```shell # No shell, você somente precisa adicionar o header adequado em cada requisição curl "api_endpoint_here" -H "Authorization: EXAMPLE_API_KEY" ``` > Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte. Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br . Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo: `Authorization: EXAMPLE_API_KEY` :::info **Atenção** Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte. ::: --- # Enviando um Documento URL: /documentation/caas/ocr/api/send_image Envie um documento utilizando o endpoint `/image` conforme indicado abaixo. Este endpoint retornará um identificador GUID (Globally Unique Identifier) para o documento, que poderá então ser referenciado nos demais serviços do sistema QI Tech. ## Envio Para enviar um documento, basta realizar via método POST o envio do código base64 da imagem em formato json para o seguinte endereço: `https://api.caas.qitech.app/ocr/image` Request Body ```json { "document_b64": "\", "template": "cnh", "file_type": "jpeg" } ``` Substitua o código base64 de seu documento documento no lugar do placeholder. ### Descrição dos Atributos de Envio Atributo | Descrição --------- | --------- document_b64 | Campo obrigatório. Imagem do documento a ser análisado em formato base64. template | Campo obrigatório. Declara o template que deve ser aplicado para análise da imagem. file_type | Campo facultativo. Identifica o formato do arquivo enviado, `jpeg` ou `pdf`. Caso não seja enviado, o valor `jpeg` é assumido. ### Templates disponíveis Neste momento, a QI Tech apresenta os seguintes templates disponíveis para análise OCR. Caso o seu documento necessário não esteja incluso nesta lista, envie um e-mail para suporte.caas@qitech.com.br e informe-se dos detalhes quanto a implementação desta feature. Template | Descrição --------- | --------- cnh | Carteira Nacional de Habilitação brasileira completa. cnh_front | Carteira Nacional de Habilitação brasileira frente (Lado da foto). cnh_back | Carteira Nacional de Habilitação brasileira frente (Lado da assinatura). cnh_digital | PDF da Carteira Nacional de Habilitação brasileira digital. rg_front | Carteira de Identidade brasileira frente (Lado da foto). rg_back | Carteira de Identidade brasileira verso (Lado dos dados). danfe | Documento Auxiliar da Nota Fiscal Eletrônica (NF-e). proof_of_address | Comprovante de residência. letter_of_attorney | Procuração que concede poderem com relação a uma empresa. company_statute | Contrato social ou estatudo de uma empresa. ## Imagem Visando garantir uma maior confiabilidade das análises executadas, é necessário que o cliente siga algumas regras na hora de tirar a foto: * Remova o documento do plástico; * Garanta que o documento encontra-se centralizado na foto; * Garanta que o documento esteja iluminado; * Garanta que todos os dados do documento estejam nítidos, visíveis e legíveis; * Garanta que a foto esteja visível e nítida. ## Requisitos da Imagem Para o funcionamento adequado da API, atente-se aos seguintes parâmetros. * A imagem deve estar em formato JPEG ou PDF; * A imagem deve possuir, ao menos, 500 pixels de altura e 500 pixels de largura; * A API não suporta a leitura de documentos escritos à mão; * O tamanho máximo da imagem varia de acordo com o formato escolhido, seguindo os limites a seguir: Formato | Tamanho máximo suportado --------- | --------- .JPEG | 3MB .PNG | 10MB .PDF | 30MB ## Resposta Caso sua requisição de leitura de documento seja processada com sucesso, será retornado um HTTP status 200 e um objeto JSON com o identificador que aponta para o documento que foi enviada. Response Body ```json { "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9" } ``` ### Descrição dos Atributos de Resposta Atributo | Descrição --------- | --------- ocr_key | Chave de identificação da imagem fornecida que pode ser utilizada em qualquer outro serviço do sistema QI Tech. ## Recuperação de um documento > Recuperação de imagem ```shell curl "https://api.caas.qitech.app/ocr/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \ -H "Authorization: EXAMPLE_API_KEY" ``` Em qualquer momento é possível recuperar as imagens enviadas. Para isso, basta enviar uma requisição **GET** adequadamente autenticada no endpoint: `https://api.caas.qitech.app/ocr/image/{image_key}/file` Onde image_key é o valor retornado durante o envio da imagem. ## Validação de qualidade da imagem Response Body: Caso de imagem inválida ```json { "title": "document_quality", "description": "A imagem enviada não pode ser processada com êxito." } ``` Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado, como pode ser visto no exemplo ao lado. O Status Code 400 também é retornado quando o documento não atende aos requisitos de imagem, citados anteriormente. **Atenção -** Existem outros motivos pelos quais retornamos 400 (Todos relacionados a dados inválidos). Somente os retornos com o title "document_quality" são resultantes de uma validação de má qualidade da imagem e portanto devem ser repassados ao usuário. ## Validação de qualidade do rosto A validação de qualidade da imagem é aplicada **exclusivamente a documentos que contêm rostos**, como RG, CNH e passaportes. Quando uma imagem é enviada ao sistema, se ela for identificada como um dos tipos abaixo, uma **análise de face é realizada automaticamente**: - `national_migration_registry_front` - `passport_front` - `ctps_front` - `regional_nursing_council_registry_front` - `regional_nursing_council_registry` - `national_registry_of_foreigners_back` - `passport` - `national_migration_registry` - `national_registry_of_foreigners` - `cnh_digital` - `rg_front` - `rg` - `cnh_front` - `cnh` Durante essa análise, o sistema verifica se há **um rosto visível na imagem** e avalia aspectos como: - Iluminação adequada (brilho); - Presença de acessórios como óculos escuros; - Proximidade ou distância excessiva do rosto; - Ausência total de rostos na imagem. Se algum desses critérios indicar que a imagem não está adequada, será retornado um erro com `title: "face_validation"` e o respectivo `description`, conforme detalhado abaixo. ```json { "title": "face_validation", "description": "" } ``` ### Exemplo de retorno: **Nenhum rosto detectado** ```json { "title": "face_validation", "description": "no_faces" } ``` --- ### Tabela de tradução de mensagens para exibição ao usuário | Código de erro (`description`) | Mensagem amigável | |-------------------------------|-------------------| | `close_face` | A imagem foi capturada muito próxima do rosto. Reposicione o documento. | | `distant_face` | A imagem foi capturada muito distante do rosto. Reposicione o documento. | | `wearing_acessories` | A pessoa na imagem está usando óculos escuros ou acessórios que cobrem os olhos. | | `brightness_problem` | A imagem está muito escura. Reenvie com mais iluminação. | | `no_faces` | Não foi possível detectar um rosto na imagem. Verifique se o rosto está visível. | --- # Coletando os Retornos URL: /documentation/caas/ocr/ios/collecting_response ```swift class ViewController: UIViewController, QITechIosOcrControllerDelegate { // Do something if QI Tech OCR's SDK succesfully collected document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults response: QITechIosOcrControllerResponse) { } // Do something if QI Tech OCR's SDK found any error when collecting document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) { } // Do something if the user canceled the picture collection on any steps func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) { } } ``` Para obter as respostas do SDK , você deve implementar o delegate **QITechIosOcrControllerDelegate** em seu controller, conforme exemplo ao lado. ## QITechIosOcrControllerResponse A classe **QITechIosOcrControllerResponse** é utilizada para que você possa receber a resposta do SDK da QI Tech. Na tabela abaixo você encontra o detalhe de todas as propriedades desta classe: nome | tipo | descrição ---- | :----: | --------- OcrResponses | Lista de OcrResponse | Identifica ## Objeto OcrResponse nome | tipo | descrição ---- | :----: | --------- OcrKey | string | Identificador único da imagem na QI Tech. Você deve armazenar esse identificador para enviar na API da QI Tech que realizará a validação (ex.: API de Onboarding) DocumentTemplate | QITechIosOcrDocumentTemplate | Enumerador que identifica a qual foto aquela OCR Key se refere. Os valores possíveis do enumerador **QITechIosOcrDocumentTemplate** podem ser: * `QITechIosOcrDocumentTemplate.CnhFull` - Identifica o resultado da validação da CNH inteira. * `QITechIosOcrDocumentTemplate.CnhFront` - Identifica o resultado da validação da frente da CNH. * `QITechIosOcrDocumentTemplate.CnhBack` - Identifica o resultado da validação do verso da CNH. * `QITechIosOcrDocumentTemplate.RgFront` - Identifica o resultado da validação da frente do RG. * `QITechIosOcrDocumentTemplate.RgBack` - Identifica o resultado da validação do verso do RG. * `QITechIosOcrDocumentTemplate.NationalRegistryOfForeignersFront` - Identifica o resultado da validação da frente do Registro Nacional de Estrangeiros. * `QITechIosOcrDocumentTemplate.NationalRegistryOfForeignersBack` - Identifica o resultado da validação do verso do Registro Nacional de Estrangeiros. ## QITechIosOcrControllerError A classe **QITechIosOcrControllerError** é acionada no caso de algum erro que leve ao encerramento do SDK. Quando isso ocorrer, a QI Tech retornará uma subclasse que terá um nome correspondente ao erro que levou ao encerramento do SDK, conforme tabela abaixo: classe | descrição ---- | --------- InvalidMobileToken | MobileToken enviado nas configurações é inválido. MissingPermission | Alguma das permissões necessárias para a validação não foi suficiente. NetworkFailure | O usuário perdeu a conexão com a internet durante a validação. ServerFailure | O servidor da QI Tech devolveu alguma resposta de erro para o SDK. MissingStorage | Não há espaço de armazenamento suficiente no dispositivo do usuário para que seja realizada a coleta da imagem. LowImageQuality | Por algum motivo a qualidade da imagem coletada não foi o suficiente para realização da validação. Para mapear qual a subclasse, e portanto, qual o motivo do erro, utilize o método *isKindOfClass()* do swift. --- # QITechIosOcrConfiguration URL: /documentation/caas/ocr/ios/configuration ```swift let onboardingTextConfiguration = OnboardingTextConfiguration( onboardingTitle: "Conselhos relevantes", onboardingFirstLabel: "Esteja em um local iluminado", onboardingSecondLabel: "Tire o documento do envelope", onboardingThirdLabel: "Enquadre o documento nas marcas" ) let ocrConfig = QITechIosOcrConfiguration( environment: QITechIosOcrEnvironment.sandbox, mobileToken: "41fb4755-9bcf-4ae3-b981-b6009e51ce4a", sessionId: "288eb399-4936-4133-ab2c-5611d6e5bb7a", documentSteps: documentSteps, fontColor: "#337DFF", backgroundColor: "#C9CCD3", fontFamily: .open_sans, showIntroductionScreens: true, showSuccessScreen: false, onboardingTextConfiguration: onboardingTextConfiguration, logLevel: .debug ) ``` **Versões anteriores à v7.0.0** ```swift let visualConfiguration = VisualConfiguration() visualConfiguration.setOnboarding(onboardingFilePath: Bundle.main.path(forResource: "onboarding", ofType: "png")!, onboardingWidth: 200) let textConfiguration = TextConfiguration() textConfiguration.setCustomText(on: .onboardingTitle, text: "Vamos começar!") textConfiguration.setCustomText(on: .onboardingFirstLabel, text: "- Vá para um local com boa luminosidade") textConfiguration.setCustomText(on: .onboardingSecondLabel, text: "- Retire o documento do plástico") let ocrConfig = QITechIosOcrConfiguration(environment: QITechIosOcrEnvironment.Sandbox, mobileToken: "41fb4755-9bcf-4ae3-b981-b6009e51ce4a", sessionId: "288eb399-4936-4133-ab2c-5611d6e5bb7a", documentSteps: documentSteps, backgroundColor: "#C9CCD3", fontColor: "#337DFF", fontFamily: .open_sans, showIntroductionScreens: true, showSuccessScreen: false, logLevel: .debug ) ocrConfig.setVisualConfiguration(visualConfiguration: visualConfiguration) ocrConfig.setTextConfiguration(textConfiguration: textConfiguration) ``` A classe **QITechIosOcrConfiguration** é utilizada para que você possa configurar ambiente, credenciais, aspectos visuais e textuais, e o fluxo de coleta de imagens dos documentos, ou seja, todas as configurações necessárias para personalização e funcionamento do SDK. Na tabela abaixo você encontra o detalhe de todos os argumentos que devem ser utilizados na sua instanciação: | nome | tipo | descrição | | ----------------------- | :--------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | environment | QITechIosOcrEnvironment | _(obrigatório)_ Enumerador que descreve o ambiente. | | mobileToken | string | _(obrigatório)_ Token enviado pela QI Tech para autenticação do SDK. | | sessionId | string | _(opcional)_ ID único usado para rastrear todo fluxo percorrido pelo usuário na execução da OCR através de logs. Este campo aceita até 255 caracteres. | | documentSteps | QITechIosOcrDocumentFlow | _(obrigatório)_ Enumerador que descreve qual fluxo de validação será seguido, definindo qual documento e qual ordem de captura de imagem será realizado. | | fontColor | string | _(opcional)_ Hexadecimal da cor da fonte. Caso não seja informada o padrão é #1C49A5. | | backgroundColor | string | _(opcional)_ Hexadecimal da cor de fundo das telas. Caso não seja informada o padrão é #FCFCFC. | | fontFamily | FontFamily | _(opcional)_ Familia da fonte. Caso não seja informada o padrão é .open_sans. Fontes disponíveis: .open_sans, .futura, .verdana, .trebuchetms, .tamilsangammn e .system_font. | | showIntroductionScreens | booleano | _(opcional)_ Flag que indica se as telas de introdução, com instruções de como a foto deve ser capturada, devem ser mostradas. Caso não seja informada o padrão é _true_. | | showSuccessScreen | booleano | _(opcional)_ Flag que indica se a tela de sucesso, com a mensagem de sucesso na captura, deve ser mostrada. Caso não seja informada o padrão é _true_. | | onboardingTextConfiguration | OnboardingTextConfiguration | _(opcional)_ Permite configurar os textos da tela de instruções | | logLevel | LogLevel | _(opcional)_ . Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. Caso não seja informada o padrão é LogLevel.debug. | Na tabela abaixo você encontra todos os métodos aceitos pela instância para configuração: :::warning __DEPRECADO__ A PARTIR DA **v7.0.0**! ::: | método | argumentos | descrição | | ---------------------- | :---------------------------------------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------- | | setVisualConfiguration | visualConfiguration : VisualConfiguration | _(opcional)_ Classe que permite a modificação das imagens exibidas durante a execução do SDK; | | setTextConfiguration | textConfiguration : TextConfiguration | _(opcional)_ Classe que permite a modificação dos textos exibidos durante a execução do SDK; | --- # Soluções híbridas URL: /documentation/caas/ocr/ios/hybrid_solutions Além de oferecer integração nativa em Swift, nossas SDKs também são compatíveis com diversos frameworks híbridos. Isso é possível através da integração de plugins nativos específicos para cada um desses frameworks. Utilizando o sistema nativo de cada solução, é viável incorporar nosso SDK nativa no ambiente iOS. Algumas das tecnologias híbridas mais utilizadas são o React Native ([Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)), Cordova ([Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)), Ionic ([Native](https://ionicframework.com/docs/v3/native/)), Unity ([Native Plug-in para Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)), Xamarin ([Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)), Appcelerator, Phonegap e Node. Para facilitar o processo de integração com nossas soluções nativas, disponibilizamos plugins para os frameworks React Native e Flutter. Caso tenha interesse, provemos a documentação e um exemplo de integração em nossos repositórios privados. Para as demais tecnologias híbridas, temos alguns exemplos de implementação dessa ponte para o código nativo. Fique à vontade para entrar em contato com nosso suporte para obter acesso. --- # Introdução URL: /documentation/caas/ocr/ios/introduction Bem vindo ao SDK iOS de OCR (Optical Character Recognition) para leitura de documentos da QI Tech. Este SDK realiza a captura de documentos e envio a API de OCR da QI Tech . Você pode utilizá-lo para capturar através do seu aplicativo uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech. ## Problemas? Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida! ### Adoramos Feedback Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu! :::danger Aviso Importante! Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech. ::: --- # Importando o SDK URL: /documentation/caas/ocr/ios/native_swift ## Remotamente > Iniciando a instalação ```shell pod init ``` Nosso SDK pode ser importado utilizando CocoaPods. | SDK | Versão atual | | ---------- | ------------------------------ | | QITechIosOCR | `pod 'QITechIosOCR', '~> 8.0.0'` | :::info iOS Minimum Deployment Target 15.5 ::: :::danger Utilização de simuladores em MacBooks com chip arm64 Atualmente, nosso SDK de OCR para iOS infelizmente não suporta ser compilada para simuladores que estejam rodando em um MacBook com **chip de arquitetura arm64** (M1/M2/M3/M4), **a não ser que seja utilizado Rosetta**, que faz a tradução da arquitetura x86_64 para arm64. ::: Para iniciar a instalação, execute o comando ao lado na pasta raiz do seu projeto. > Adicionando a source no podfile ```ruby source 'https://github.com/QITechSDKs/iOS.git' ``` O próximo passo é adicionar no arquivo `podfile` o source da QI Tech. > Adicionando o pod no podfile ```ruby pod 'QITechIosOCR', '~> ' ``` Por fim, basta adicionar o nome do `pod` de acordo com o formato ao lado. :::danger Atenção: Mudança de Arquitetura (v6.0.0+) A partir da versão 6.0.0, o SDK passou a ser distribuída exclusivamente de forma estática. No seu Podfile, você deve utilizar a configuração :linkage => :static. ::: > Exemplo de podfile (Versão 6.0.0 ou superior) ```ruby source 'https://github.com/QITechSDKs/iOS.git' source 'https://cdn.cocoapods.org/' target 'ExampleApp' do use_frameworks! :linkage => :static pod 'QITechIosOCR', '~> 8.0.0' end post_install do |installer| installer.pods_project.targets.each do |target| if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name) target.build_configurations.each do |config| config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5' config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end end end end ``` > Exemplo de podfile (Versões Anteriores) ```ruby source 'https://github.com/QITechSDKs/iOS.git' source 'https://cdn.cocoapods.org/' target 'ExampleApp' do use_frameworks! pod 'QITechIosOCR', '~> 4.0.0' end post_install do |installer| installer.pods_project.targets.each do |target| if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name) target.build_configurations.each do |config| config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5' config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end end end end ``` :::warning Atenção Ao integrar dependências no iOS, pode surgir a necessidade de usar linkagem estática para algumas bibliotecas e dinâmica para outras. Essa configuração é relevante para garantir compatibilidade, evitar erros de build e otimizar o desempenho do projeto. ::: ### Linkagem Híbrida de Dependências (caso necessário) A necessidade de linkagem híbrida surge porque algumas bibliotecas têm requisitos específicos, sendo que algumas precisam de linkagem estática para evitar conflitos internos e duplicação de símbolos e outras dependências podem precisar linkagem dinâmica, pois são projetadas para modularidade e compartilhamento entre projetos. Diferenças Entre Linkagem Estática e Dinâmica * Estática (static_framework): O código da biblioteca é incorporado diretamente no binário final, reduzindo o tempo de carregamento em runtime e eliminando dependências externas durante a execução. * Dinâmica (dynamic_framework): A biblioteca é carregada em tempo de execução como um arquivo separado. Isso reduz o tamanho do binário final e facilita atualizações/modificações independentes. > Configurando linkagem híbrida no Podfile ```ruby ... use_frameworks! :linkage => :dynamic # CONFIGURANDO O MODO PADRÃO DE LINKAGEM PARA DINÂMICO ... static_frameworks = ['framework_1', 'framework_2', ...] # INCLUIR TODAS AS DEPENDÊNCIAS QUE PRECISAM SER LINKADAS DE MODO ESTÁTICO pre_install do |installer| installer.pod_targets.each do |pod| if static_frameworks.include?(pod.name) def pod.static_framework?; true end def pod.build_type; Pod::BuildType.static_framework end end end end ``` > Instalando as dependências ```shell pod install ``` Por fim, execute o comando `pod install` para baixar e instalar as dependências. ## Permissões Necessárias Para que o SDK possa acessar os recursos do dispositivo para coletar a foto, é necessário que sejam solicitadas permissões ao usuário. No arquivo **info.plist**, adicione as permissões abaixo: | Permissão | Motivo | | ---------------------------------- | ---------------------------------------------------- | | Privacy - Camera Usage Description | Acesso à câmera para capturar as fotos do documento. | ## Iniciando o SDK ```swift import QITechIosOcr class ViewController: UIViewController, QITechIosOcrControllerDelegate { var qitechOcrConfiguration : QITechIosOcrConfiguration? override func viewDidLoad() { super.viewDidLoad() self.setupOcr() } func setupOcr() -> Void { let onboardingTextConfiguration = OnboardingTextConfiguration( onboardingTitle: "Conselhos relevantes", // Título onboardingFirstLabel: "Esteja em um local iluminado", // Primeira Instrução onboardingSecondLabel: "Tire o documento do envelope", // Segunda Instrução onboardingThirdLabel: "Enquadre o documento nas marcas" // Terceira Instrução ) // The environment can be 'sandbox' ou 'production' let environment: QITechIosOcrEnvironment = .sandbox // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken. let mobileToken: String = "YOUR_MOBILE_TOKEN" // The documentFlow can be 'CnhFull' , 'CnhFrontAndBack' ou 'RgFrontAndBack' let documentFlow = QITechIosOcrDocumentFlow.CnhFrontAndBack let sessionId: String = "SESSION_ID" let fontColor: String = "#ED6C2D" let backgroundColor: String = "#EEEEEE" let fontFamily: FontFamily? = .verdana let showIntroductionScreens: Bool = true let showSuccessScreen: Bool = true let logLevel: QITechIosOCR.LogLevel = .debug self.ocrConfig = QITechIosOcrConfiguration( environment: environment, mobileToken: mobileToken, documentSteps: documentFlow, sessionId: sessionId, fontColor: fontColor, backgroundColor: backgroundColor, fontFamily: fontFamily, showIntroductionScreens: showIntroductionScreens, showSuccessScreen: showSuccessScreen, onboardingTextConfiguration: onboardingTextConfiguration, logLevel: logLevel ) } // Event where you intend to call QI Tech OCR View Controller - on this example, when the user press 'next' button @IBAction func pressNext(_ sender: Any) { let qitechOcrController = QITechIosOcrController(ocrConfiguration: self.ocrConfig) qitechOcrViewController.delegate = self let qitechOcrViewController = qitechOcrController.getViewController() present(qitechOcrViewController, animated: true, completion: nil) } // Do something if QI Tech OCR's SDK succesfully collected document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults results: QITechIosOcrControllerResponse) { } // Do something if QI Tech OCR's SDK found any error when collecting document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) { } // Do something if the user canceled the picture collection on any steps func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) { } } ``` **Versões anteriores à v7.0.0** ```swift import QITechIosOcr class ViewController: UIViewController, QITechIosOcrControllerDelegate { var qitechOcrConfiguration : QITechIosOcrConfiguration? override func viewDidLoad() { super.viewDidLoad() self.setupOcr() } func setupOcr() -> Void { // The environment can be 'Sandbox' ou 'Production' let environment = QITechIosOcrEnvironment.Sandbox // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken. let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" // The documentFlow can be 'CnhFull' , 'CnhFrontAndBack' ou 'RgFrontAndBack' let documentFlow = QITechIosOcrDocumentFlow.CnhFrontAndBack self.ocrConfig = QITechIosOcrConfiguration(environment: environment, mobileToken: mobileToken, sessionId: "UNIQUE_SESSION_ID", documentFlow: documentFlow, backgroundColor: "#000000", fontColor: "#FFFFFF", fontFamily: .open_sans, showIntroductionScreens: true, logLevel: .debug ) } // Event where you intend to call QI Tech OCR View Controller - on this example, when the user press 'next' button @IBAction func pressNext(_ sender: Any) { let qitechOcrController = QITechIosOcrController(ocrConfiguration: self.ocrConfig) qitechOcrViewController.delegate = self let qitechOcrViewController = qitechOcrController.getViewController() present(qitechOcrViewController, animated: true, completion: nil) } // Do something if QI Tech OCR's SDK succesfully collected document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults results: QITechIosOcrControllerResponse) { } // Do something if QI Tech OCR's SDK found any error when collecting document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) { } // Do something if the user canceled the picture collection on any steps func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) { } } ``` Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através da classe **QITechIosOcrConfiguration** e depois instanciar o **ViewController QITechIosOcrController** passando como argumento as configurações personalizadas. Para iniciar o processo de análise de documento, basta chamar a função _present_ para chamar o ViewController da QI Tech que realizará a coleta das imagens. Importante implementar o _Delegate_ responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação. Acima temos um exemplo completo da implementação. :::info **Atenção** Habilite o suporte as orientações _Portrait_ e _Landscape Right_ em sua aplicação para um funcionamento correto do SDK. ::: ## Mobile Token Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ele provavelmente já foi enviado por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br . Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente. :::info **Atenção** Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" pelo Mobile Token recebido do suporte. ::: --- # Coletando os Retornos URL: /documentation/caas/ocr/web/collecting_results A Web OCR SDK devolve uma _Promise_ que, em caso de sucesso, retorna um **array de objetos**, onde cada objeto representa um lado do documento capturado (frente e/ou verso). Em caso de erro, a Promise é rejeitada com uma string descrevendo o problema. Abaixo está um exemplo de como mapear cada caso e coletar seus resultados: ```html ``` ## Descrição do retorno da Web OCR ### Sucesso O retorno de sucesso é um **array** de objetos, um por lado do documento capturado: Atributo | Tipo | Descrição --------- | --------- | --------- ocr_results | Array | Lista de objetos com as informações de cada captura realizada. ### Atributos de cada objeto no array Atributo | Tipo | Descrição --------- | --------- | --------- ocr_key | String | Chave de identificação da imagem capturada. Pode ser utilizada em qualquer outro serviço do sistema QI Tech. template | String | Tipo e lado do documento capturado (ex: `rg_front`, `rg_back`, `cnh_front`, `cnh_back`, `cin_digital`). document_capture_session_key | String | Chave que identifica a sessão de captura do documento. ### Tipos de Erro Erro | Descrição --------- | --------- Invalid Web Token! Please verify your Web Token. | Web Token utilizado é inválido. Caso tenha certeza que esteja utilizando corretamente o Web Token provido pela QI Tech, entre em contato com nosso suporte (suporte.caas@qitech.com.br). Invalid Document Type! Please provide a valid document type. | Tipo de documento passado para **WebOCR.initialize()** não é válido. Verifique os tipos permitidos na página da [função initialize](./initialize_info.md). User left Web OCR. | O usuário saiu da Web OCR SDK antes de concluir o envio do documento. --- # O construtor QiTechWebOCR.WebOCR() URL: /documentation/caas/ocr/web/constructor_info :::info Novidade na versão 4.0.0 A partir da versão **4.0.0**, o construtor não recebe mais o `htmlComponent` como primeiro parâmetro — o SDK cria e gerencia seu próprio nó DOM internamente, adicionado ao `document.body`. ::: O método `.WebOCR()` é responsável pela configuração da instância do seu componente de documentoscopia. O construtor recebe dois parâmetros obrigatórios: | Parâmetro | Descrição | Obrigatório | |----------|----------|----------| | webToken | Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu web-token, entre em contato com o suporte. | Sim | | sessionId | Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da Web OCR através de logs. Este campo aceita uma string de até 255 caracteres. Deve ser único para cada sessão. | Sim | Após a instanciação, utilize os seguintes métodos encadeados para personalizar o comportamento: | Nome | Descrição | Obrigatório | |----------|----------|----------| | `.setThemeConfiguration(object)` | Personaliza a identidade visual do SDK. | Não | | `.setShowInstructionScreen(boolean)` | Exibe a tela de introdução com dicas de captura. Padrão: `true`. | Não | | `.setShowAllowedTemplatesScreen(boolean)` | Exibe a tela que informa os documentos aceitos. Recomendamos ativá-la para que o usuário saiba quais documentos pode enviar. | Não | | `.setShowSuccessScreen(boolean)` | Exibe a tela de sucesso ao final da captura. Padrão: `true`. | Não | | `.setSandboxEnvironment()` | Configura o SDK para apontar para o ambiente de Sandbox. | Não | O método `.setThemeConfiguration` deve receber um objeto com os seguintes campos: | Nome | Tipo | Descrição | | -------- | -------- | -------- | | primaryColor | String | _(recomendado)_ Hexadecimal da cor principal do SDK — usada em botões, ícones e elementos de destaque. Caso não seja informada, o padrão é `#555555`. | | companyLogo | String | _(recomendado)_ Caminho ou **URL pública** do logo da sua empresa (**PNG**). Caso não seja informado, será exibido um placeholder. | | fontFamily | String | _(recomendado)_ Nome da _Font Family_ a ser configurada nos textos do SDK. Caso não seja informada, será utilizada a fonte padrão. | :::caution Compatibilidade Os campos `backgroundColor` e `buttonColor` ainda são aceitos pelo método `.setThemeConfiguration`, mas são utilizados apenas como fallback para derivar o `primaryColor` quando este não for informado. Prefira usar `primaryColor` diretamente. ::: ## Versões Anteriores (< 4.0.0) Nas versões anteriores, o construtor recebia o `htmlComponent` como primeiro parâmetro: ```js var htmlComponent = document.getElementById('webOCR'); var webOCR = new QiTechWebOCR.WebOCR( htmlComponent, "", "" ) ``` --- # Implementação URL: /documentation/caas/ocr/web/example :::info Novidade na versão 4.0.0 A partir da versão **4.0.0**, o construtor `WebOCR` não recebe mais o `htmlComponent` — o SDK cria e gerencia seu próprio nó DOM internamente. ::: A inicialização da Web OCR SDK é realizada através da chamada do método `.initialize()`, que pertence à classe `WebOCR`. O processo é dividido em duas etapas principais: 1. **Configuração e Instanciação:** Preparar e configurar a instância do SDK. 2. **Inicialização da Captura:** Iniciar o fluxo de captura de documentos para o usuário final. ## Exemplo completo ```html ``` ## Configuração e Instanciação Para começar, crie uma nova instância da classe `WebOCR`. O construtor exige dois parâmetros obrigatórios, na ordem especificada abaixo: - **webToken** `(String)`: Seu token de autenticação para uso da API. - **sessionId** `(String)`: Um identificador único para a sessão do usuário. ### Personalização (Opcional) Após criar a instância, utilize os seguintes métodos encadeados para personalizar a experiência: - **`setThemeConfiguration`** `(object)`: Personaliza a aparência do SDK. Campos aceitos: - `primaryColor` `(String)`: Cor principal em formato hexadecimal — usada em botões, ícones e destaques (ex: `'#0000FF'`). - `companyLogo` `(String)`: URL ou path para o logo da sua empresa. - `fontFamily` `(String)`: Família da fonte (ex: `'Arial'`). - **`setShowInstructionScreen`** `(boolean)`: Define se a tela inicial de instruções será exibida. - **`setShowAllowedTemplatesScreen`** `(boolean)`: Define se a tela que informa os documentos aceitos será exibida. Recomendamos ativá-la para que o usuário saiba quais documentos pode enviar. - **`setShowSuccessScreen`** `(boolean)`: Define se a tela de sucesso ao final da captura será exibida. - **`setSandboxEnvironment`**: Configura o SDK para apontar para o ambiente de homologação (Sandbox). ### Build Por fim, você **deve** chamar a função **build()** para instanciar a classe **WebOCR** com as configurações passadas. Para mais detalhes sobre o construtor, veja a página sobre o [construtor](./constructor_info.md). ## Inicializando a Captura de Documentos Com a instância da `WebOCR` devidamente configurada, chame o método `initialize()` para iniciar o fluxo de captura. Este método recebe como parâmetro uma lista (array) de strings, onde cada string representa um tipo de documento que o usuário poderá enviar. ### Tabela com templates aceitos Nome | Tipo | Descrição ---- | ---- | --------- cnh | String | Captura de CNH física (fechada), em duas etapas, FRENTE e VERSO rg | String | Captura de RG físico (fechado), em duas etapas, FRENTE e VERSO cin_digital | String | Envio da CIN **digital** (pdf) emitida por um aplicativo oficial rg_digital | String | Envio do RG **digital** (pdf) emitido por um aplicativo oficial rne | String | Captura do RNE físico, em duas etapas, FRENTE e VERSO crnm | String | Captura da CRNM física, em duas etapas, FRENTE e VERSO others | String | Deve ser usado para permitir o envio de outros documentos além dos listados acima :::caution Atenção Adicionar o tipo `others` nos templates permitidos faz com que todo documento enviado seja aceito. Assim, mesmo documentos não oficiais serão aceitos. ::: ### Tratamento do Retorno O método `initialize()` retorna uma Promise: - **Sucesso:** A Promise é resolvida com um **array de objetos**, onde cada objeto representa um lado do documento capturado. Consulte a página [Coletando os Retornos](./collecting_results.md) para detalhes sobre o formato. - **Erro:** A Promise é rejeitada. Você pode capturar esses erros utilizando o método `.catch()`. --- # Importando a biblioteca URL: /documentation/caas/ocr/web/import Para importar a nossa biblioteca, adicione a URL no _src_ de uma TAG **script** no HTML de seu website, assim como o exemplo abaixo: ```html ``` --- # A função initialize() URL: /documentation/caas/ocr/web/initialize_info Para iniciar a Web OCR SDK, após ter instanciado a classe **WebOCR**, chame a função **initialize()** passando uma lista de documentos permitidos como parâmetro. Abaixo temos o detalhamento de cada um dos possíveis tipos de documento: Nome | Tipo | Descrição ---- | ---- | --------- cnh | String | Captura de CNH física (fechada), em duas etapas, FRENTE e VERSO rg | String | Captura de RG físico (fechado), em duas etapas, FRENTE e VERSO cin_digital | String | Envio da CIN **digital** (pdf) emitida por um aplicativo oficial rg_digital | String | Envio do RG **digital** (pdf) emitido por um aplicativo oficial rne | String | Captura do RNE físico, em duas etapas, FRENTE e VERSO crnm | String | Captura da CRNM física, em duas etapas, FRENTE e VERSO others | String | Deve ser usado para permitir o envio de outros documentos além dos listados acima :::caution Atenção Adicionar o tipo `others` nos templates permitidos faz com que todo documento enviado seja aceito. Assim, mesmo documentos não oficiais serão aceitos. ::: ## Exemplo de Implementação Um exemplo de implementação da Web OCR SDK pode ser visto abaixo: ```html Web OCR
``` No exemplo acima, a instância da classe **WebOCR** é criada com os parâmetros obrigatórios e opcionais. Com o SDK instanciado, a função **initOCR()** inicializa o fluxo de captura e, ao final, registra em log o array de resultados retornados ou o erro, caso ocorra. ## Tratamento do Retorno O método `initialize()` retorna uma Promise: - **Sucesso:** A Promise é resolvida com um **array de objetos**, onde cada objeto representa um documento capturado. Consulte a página [Coletando os Retornos](./collecting_results.md) para detalhes sobre o formato. - **Erro:** A Promise é rejeitada. Você pode capturar esses erros utilizando o método `.catch()`. --- # Introdução URL: /documentation/caas/ocr/web/introduction Bem-vindo à Web OCR SDK (Optical Character Recognition) da QI Tech para leitura de documentos. Este SDK realiza a captura de documentos e o envio a API de OCR da QI Tech . Você pode utilizá-lo para capturar através do seu aplicativo web uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de Identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech. ## Problemas? Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida! ### Adoramos Feedback Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu! :::danger Aviso Importante! Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech. :::