# QI Tech — Portabilidade Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 2 página(s). Índice: - Portabilidade Out - Evidências de rentenção (/documentation/manual_portabilidade/evidencias_de_retencao) - Portabilidade Out (/documentation/manual_portabilidade/portabilidade_out) --- # Portabilidade Out - Evidências de rentenção URL: /documentation/manual_portabilidade/evidencias_de_retencao # Evidências de Retenção :::info Objetivo Para efetivar a retenção de um contrato atacado por portabilidade, é **obrigatório** o envio de evidências que comprovem: 1. A realização do contato com o tomador; 2. O aceite explícito do tomador em relação à retenção. ::: ## 1. Coleta das Evidências As evidências podem ser coletadas via mensagem (WhatsApp, Chat), e-mail ou ligação gravada. Independentemente do canal, a interação deve seguir estritamente os roteiros (scripts) de atendimento listados abaixo para cada motivo de retenção. ### 1.1 Caso haja refinanciamento Utilize este roteiro quando a retenção for realizada mediante uma oferta de refinanciamento do contrato atual. ```text title="Script - Retenção com Refinanciamento" Sr. (a) XXXXX, com final de CPF XXX-XX, conforme sua aprovação, na data de hoje XX/XX/XXXX, estamos cancelando a sua solicitação(ões) de portabilidade de número(s) final(is) XXXX, efetuada pelo Banco XX, referente ao(s) contratos finais XXXX mediante a oferta de refinanciamento. O Sr.(a) confirma? SIM / OK / CONFIRMO ``` ### 1.2 Caso NÃO haja refinanciamento Utilize este roteiro quando a retenção for realizada mantendo as condições originais, sem refinanciamento. ```text title="Script - Retenção sem Refinanciamento" Sr. (a) XXXXX, com final de CPF XXX-XX, conforme sua aprovação, na data de hoje XX/XX/XXXX, estamos cancelando a sua solicitação(ões) de portabilidade de número(s) final(is) XXXX, efetuada pelo Banco XX, referente ao(s) contratos finais XXXX mantendo-o junto ao [NOME DA IF]. O Sr.(a) confirma? SIM / OK / CONFIRMO ``` ### 1.3 Quando o cliente NÃO SOLICITOU a portabilidade Utilize este roteiro quando o cliente informa que não reconhece a solicitação de portabilidade. ```text title="Script - Ataque indevido" Sr. (a) XXXXX, com final de CPF XXX-XX, conforme sua aprovação, na data de hoje XX/XX/XXXX, estamos cancelando a sua solicitação(ões) de portabilidade de número(s) final(is) XXXX, efetuada pelo Banco XX sem o seu consentimento, referente ao(s) contratos finais XXXX mantendo-o junto ao [NOME DA IF]. O Sr.(a) confirma? SIM / OK / CONFIRMO ``` --- # Portabilidade Out URL: /documentation/manual_portabilidade/portabilidade_out :::danger Atenção! Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs. ::: :::info Reenvio de Webhooks Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes). ::: ## 1. Notificação de recebimento de portabilidade out Assim que uma solicitação de portabilidade for recepcionada pela QI SCD via CTC (Central de Transferência de Crédito), o parceiro será notificado através do seguinte webhook: WEBHOOK_TYPE credit_transfer.received_portability STATUS Received Webhook Body ```json { "webhook_type": "credit_transfer.received_portability", "received_portability_status": "received", "key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1", "event_datetime": "2022-07-24T18:29:45", "data": { "annual_interest_rate": "20.27", "annual_effective_interest_rate": "20.27", "number_of_installments": "6", "installment_face_value": "201.71", "phone_number": "(05)541997558", "address": { "street": "Rua Longe de Casa", "city": "Rio de Janeiro", "state": "RJ", "number": "112", "postal_code": "38300569" }, "due_balance": "1000", "due_balance_date": "2022-07-29", "issuer_name": "A Random Name", "issuer_document_number": "37197645832", "reference_date": "2022-08-01", "contract_number": "0000049045/UO", "origin_credit_operation_key": "7daef1ad-5497-4ec3-92f4-26f8d63bcd80", "retention_limit_date": "2022-08-03", "due_balance_limit_date": "2022-08-08", "portability_number": "202207150000001642808", "corban_document_number": "08289470514408", "source_ispb_number": "0" } } ``` Confira a descrição dos campos na tabela [Detalhamento do webhook received_portability](#received_portability) ## 2. Resposta ao ataque de portabilidade ### 2.1. Retenção de contrato :::warning Reenvio de Webhooks Para realizar a retenção do cliente, o parceiro deve realizar o **[upload](../upload_de_documentos)** das **[evidências de retenção](./evidencias_de_retencao)** e anexá-las à operação até às 18:00 horas do 4° dia útil após o recebimento do evento de ataque (_**credit_transfer.received_portability**_). ::: ENDPOINT /credit_transfer/received_portability/ [received_portability_key] MÉTODO PATCH Testar no Playground ```json title='Request Body { "received_portability_status": "retained", "retention_reason": "issuer_retention", "document_type": "received_portability_retention_proof", "documents": [ { "file_type": "jpeg", "document_key": "3d6fbbbf-55e9-4275-8050-b83b33fdefa6", "retention_type": "whatsapp" } ] } ``` :::danger Atenção **NÃO serão aceitos arquivos COMPRIMIDOS.** ::: Consulte o descritivo dos campos da requisição na tabela [Detalhamento do objeto authorization_term](#authorization_term). ### 2.2 Aprovação de portabilidade out Caso o cliente não seja retido o parceiro deve informar sobre a não retenção até as 10:00 do 4o. dia útil após o recebimento da notificação de ataque de portabilidade (_**credit_transfer.received_portability**_). :::danger Atenção **Caso a solicitação de portabilidade não seja respondida em até 4 dias úteis, a QI Tech retornará o saldo devedor da operação ao proponente (solicitante da portabilidade).** ::: ENDPOINT /credit_transfer/received_portability/ [received_portability_key] MÉTODO PATCH Testar no Playground ```json title='Request Body' { "received_portability_status": "accepted_by_creditor" } ``` ## 3. Consultando solicitações de portabilidade out ### 3.1. Consulta de solicitação de portabilidade Para verificar os possíveis status da ENDPOINT /credit_transfer/received_portability/ [received_portability_key] MÉTODO GET Testar no Playground Response Body ```json { "received_portability_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "received_portability_status": "accepted", "annual_interest_rate": "20.27", "annual_effective_interest_rate": "20.27", "number_of_installments": "6", "installment_face_value": "201.71", "phone_number": "(05)541997558", "address": { "street": "Rua Longe de Casa", "city": "Rio de Janeiro", "state": "RJ", "number": "112", "postal_code": "38300569" }, "due_balance": 1000, "due_balance_date": "2022-07-29", "issuer_name": "A Random Name", "issuer_document_number": "37197645832", "reference_date": "2022-08-01", "contract_number": "0000049045/UO", "origin_credit_operation_key": "key", "retention_limit_date": "2022-08-03", "due_balance_limit_date": "2022-08-08", "portability_number": "202207150000001642808", "retention_reason": null, "canceled_reason": null, "corban_document_number": "08289470514408", "attached_documents": [ ], "financial_institution_code_number": "001", "financial_institution_name": "Banco do Brasil", "ispb": "00000000", "requester_key": "8511012c-3a3c-4f4d-9f23-dbe437211a8e", "requester_name": "Corban LTDA", "response_date": null, "settlement_date": null, "settlement_due_balance": null } ``` ### 3.2. Listar solicitação de portabilidade ENDPOINT /credit_transfer/received_portability MÉTODO GET PARÂMETROS settlement_date, max_portability_date, due_balance_limit_date, received_portability_status, portability_number, contract_number, credit_operation_key Testar no Playground Response Body ```json { "data": [{ "received_portability_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "received_portability_status": "accepted", "annual_interest_rate": 1, "annual_effective_interest_rate": 1, "number_of_installments": 6, "installment_face_value": 201.71, "phone_number": "(05)541997558", "address": { "street": "Rua Longe de Casa", "city": "Rio de Janeiro", "state": "RJ", "number": "112", "postal_code": "38300569" }, "due_balance": 1000, "due_balance_date": "2022-07-29", "issuer_name": "A Random Name", "issuer_document_number": "37197645832", "reference_date": "2022-08-01", "contract_number": "0000049045/UO", "origin_credit_operation_key": "key", "retention_limit_date": "2022-08-03", "due_balance_limit_date": "2022-08-08", "portability_number": "202207150000001642808", "retention_reason": null, "canceled_reason": null }], "pagination": { "next_page": null, "current_page": 1, "total_rows": 0, "rows_per_page": 1, "total_pages": 0 } } ``` ## 4. Webhooks A seguir estão os possíveis webhooks recebidos durante o fluxo, a [máquina de estados](#state-machine) pode ser consultada para verificar as possíveis alterações de status (o status de canceled_by_proponent pode ser alcançado a partir de qualquer status não final) ### 4.1. Aguardando pagamento do saldo devedor WEBHOOK_TYPE credit_transfer.received_portability STATUS waiting_settlement ```json title='Webhook Body' { "webhook_type": "credit_transfer.received_portability", "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1", "received_portability_status": "waiting_settlement", "event_datetime": "2022-07-24T18:29:45", "data": { "settlement_due_balance": 120.00, "settlement_date": "2022-08-02" } } ``` ### 4.2. Proposta cancelada pelo proponente WEBHOOK_TYPE credit_transfer.received_portability STATUS canceled_by_proponent ```json title='Webhook Body' { "webhook_type": "credit_transfer.received_portability", "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1", "received_portability_status": "canceled_by_proponent", "event_datetime": "2022-07-24T18:29:45", "data": {} } ``` ### 4.3. Portabilidade liquidada WEBHOOK_TYPE credit_transfer.received_portability STATUS settled ```json title='Webhook Body' { "webhook_type": "credit_transfer.received_portability", "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1", "received_portability_status": "settled", "event_datetime": "2022-07-24T18:29:45Z", "data": {} } ``` ### 4.4. Portabilidade não liquidada Caso o proponente não realiza o pagamento do saldo devedor retornado na resposta da portabilidade out (ataque de portabilidade), a proposta será cancelada por falta de pagamento dentro do prazo. WEBHOOK_TYPE credit_transfer.received_portability STATUS canceled_by_creditor ```json title='Webhook Body' { "webhook_type": "credit_transfer.received_portability", "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1", "received_portability_status": "canceled_by_creditor", "event_datetime": "2022-07-24T18:29:45", "data": { "canceled_reason": { "enumerator": "not_paid", "description": "Decurso de prazo por STR não paga dentro do prazo" } } } ``` ## 5. Mocks para validação em sandbox :::info Ambiente Sandbox Utilize estes endpoints para simular o fluxo de portabilidade out no sandbox sem depender de eventos reais do CTC/STR. ::: :::danger Aviso Importante! Não utilize dados pessoais reais (CPF, CNPJ, etc.) em ambientes sandbox. ::: ### 5.1. Simular portabilidade recebida Ao chamar este endpoint, você receberá o webhook `credit_transfer.received_portability` (descrito na [seção 1](#1-notificação-de-recebimento-de-portabilidade-out)) com os dados calculados a partir da operação de crédito informada. ENDPOINT /mock/credit_transfer/received_portability MÉTODO POST #### Atributos credit_operation_key string (UUID) obrigatório Chave da operação de crédito a ser portada. reference_date string obrigatório Data de referência para a portabilidade (formato `YYYY-MM-DD`). ispb_number string obrigatório Número ISPB da instituição de origem (máx. 8 caracteres). origin_contract_type string opcional Tipo do contrato de origem. Valores permitidos: `payroll`, `public_agency`. Padrão: `payroll`. proposal_type string opcional Tipo da proposta. Valores permitidos: `inss`. Padrão: `inss`. ```json title='Request Body' { "credit_operation_key": "3571e292-3a83-4011-904d-20ee963022ef", "reference_date": "2026-04-13", "ispb_number": "00000000", "origin_contract_type": "payroll", "proposal_type": "inss" } ``` ```json title='Response — 202 Accepted' {} ``` ### 5.2. Simular liquidação STR Após aprovar a portabilidade ([seção 2.2](#22-aprovação-de-portabilidade-out)) e receber o webhook `waiting_settlement` ([seção 4.1](#41-aguardando-pagamento-do-saldo-devedor)), utilize este endpoint para simular a liquidação ou rejeição do pagamento via STR. O webhook correspondente (`settled` ou `canceled_by_creditor`) será disparado conforme o `event_type` escolhido. ENDPOINT /mock/credit_transfer/str MÉTODO POST #### Atributos proposal_key string (UUID) obrigatório Chave da proposta (retornada no webhook `waiting_settlement`). event_type string obrigatório Tipo do evento. Valores permitidos: `settlement`, `payment_rejected`. source_branch string opcional Código da agência de origem. Padrão: `"0001"`. target_branch string opcional Código da agência de destino. Padrão: `"0001"`. provider_ispb string opcional Número ISPB do provedor. Padrão: `"99999999"`. ```json title='Request Body (settlement)' { "proposal_key": "9ff557c3-b640-4862-b2c1-ef6f7d9a6a61", "event_type": "settlement", "source_branch": "0001", "target_branch": "0001", "provider_ispb": "99999999" } ``` ```json title='Response — 202 Accepted' {} ``` ## Anexos --- ### Detalhamento do webhook received_portability {#received_portability} | Campo | Descrição | |------------------------- |------------------------------------| |key |Chave do ataque (received_portability_key) | |webhook_type |Tipo de evento | |received_portability_status |Status do ataque | |event_datetime |Data do evento | |annual_interest_rate |Taxa informada no ataque | |annual_effective_interest_rate |CET informado no ataque | |number_of_installments |Quantidade de parcelas informadas no ataque | |installment_face_value |Valor de parcela informado no ataque | |phone_number |Número de telefone informado no ataque | |address |Endereço informado no ataque | |due_balance |Saldo devedor informado no ataque| |due_balance_date |Data de referência do saldo devedor informado no ataque| |issuer_name |Nome do tomador informado no ataque| |issuer_document_number |Número de documento do tomador informado no ataque| |reference_date |informado no ataque| |contract_number |Número de contrato informado no ataque| |origin_credit_operation_key |Chave da operação de crédito (DEBT_KEY/CREDIT_OPERATION_KEY)| |retention_limit_date |Data limite para retenção| |due_balance_limit_date |Data limite para informar o saldo devedor| |portability_number |Número da portabilidade (NU)| |corban_document_number |informado no ataque| |source_ispb_number |informado no ataque| ### Detalhamento do objeto authorization_term {#authorization_term} | Campo | Obrigatoriedade | Descrição | |------------------------- |----------------- |------------------------------------| |received_portability_status |Obrigatório |Liberação ou não do saldo | |retention_reason |Obrigatório no caso de retenção |Motivo da rentenção, consulte os possíveis enumeradores na tabela [Motivo de retenção](#retention_reason)| |document_type |Obrigatório no caso de retenção |Necessariamente "received_portability_retention_proof"| |documents |Obrigatório no caso de retenção |Evidências de retenção| |file_type |Obrigatório no caso de retenção |Tipo de documento, consulte os possíveis enumeradores na tabela [Tipo de documento](document_type)| |document_key |Obrigatório no caso de retenção |Chave do documento retornada após feito o [upload](../upload_de_documentos)| |retention_type |Obrigatório no caso de retenção |Tipo de evidência de retenção, consulte os possíveis enumeradores na tabela [Tipos de retenção](#retention_type)| ### Motivo de retenção {#retention_reason} | Enumerador | Descrição | |------------------------------------------|--------------------------------------------------------| | **issuer_retention** | Retenção do Cliente | | **portability_not_requested** | O cliente não solicitou a portabilidade | ### Tipo de documento {#document_type} |enumerador | |------------| | **pdf** | | **jpeg** | | **jpg** | | **png** | | **mp3** | | **wav** | :::note Para evidências de retenção (`retention_type`), apenas os formatos **jpg**, **jpeg**, **png** e **pdf** são aceitos. ::: ### Tipos de retenção {#retention_type} |enumerador | |----------------| | **sms** | | **whatsapp** | ### Status do ataque {#received_portability_status} | Enumerador | Descrição | |------------------------------|----------------------------------------------------------| | **received** | Recebido | | **waiting_validation** | Aguardando validação do Documento comprovante da Retenção| | **canceled_by_proponent** | Cancelado pelo Proponente | | **canceled_by_creditor** | Cancelado pelo Credor Original | | **retained** | Retido | | **waiting_settlement** | Portabilidade aprovada esperando liquidação | | **settled** | Liquidado | ### Máquina de estados do ataque {#state-machine} ![Máquina de estados do ataque de portabilidade](/img/diagrams/manual-portabilidade-portabilidade-out.svg)