# QI Tech — 薪资贷款 › INSS Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 30 página(s). Índice: - Consulta de Dados do Benefício (/zh-Hans/documentation/guides/INSS/inquiries/dados-do-beneficio) - Consulta da Lista de Benefícios (/zh-Hans/documentation/guides/INSS/inquiries/lista-de-beneficios) - Consulta Offline de Saldo (/zh-Hans/documentation/guides/INSS/inquiries/offline-balance-request) - Lista de Participantes do CTC (/zh-Hans/documentation/guides/INSS/inquiries/participantes-ctc) - Consulta de Portabilidade de Origem (/zh-Hans/documentation/guides/INSS/inquiries/portabilidade-de-origem) - Última Resposta da Averbação (/zh-Hans/documentation/guides/INSS/inquiries/ultima-resposta) - Mocks (Sandbox) (/zh-Hans/documentation/guides/INSS/mocks-sandbox) - Emissão da Operação (/zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/emissao) - INSS 手册 - 新增信贷或再融资 (/zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/end-to-end) - Envio de Documentos e Formalização (/zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/formalizacao) - Falha no Desembolso e Reapresentação (/zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/pos-desembolso) - 重新计算信贷操作 (/zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/recalculate) - Simulação da Dívida (/zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/simulacao) - Anuência (pending confirmation) (/zh-Hans/documentation/guides/INSS/pending_confirmation) - Alterando o Cessionário (/zh-Hans/documentation/guides/INSS/portability+refinancing/alterando-cessionario) - Consultas e Enumeradores (/zh-Hans/documentation/guides/INSS/portability+refinancing/consultas-e-enumeradores) - Correção de Dados da Proposta (/zh-Hans/documentation/guides/INSS/portability+refinancing/correcao-de-dados) - Diminuir o Valor das Parcelas (/zh-Hans/documentation/guides/INSS/portability+refinancing/diminuir-parcela) - INSS 贷款转移 + 再融资手册 (/zh-Hans/documentation/guides/INSS/portability+refinancing/end-to-end) - Envio de Documentos e Formalização (/zh-Hans/documentation/guides/INSS/portability+refinancing/formalizacao) - Máquinas de Status (/zh-Hans/documentation/guides/INSS/portability+refinancing/maquinas-de-status) - Digitação da Proposta (/zh-Hans/documentation/guides/INSS/portability+refinancing/proposta) - Recálculo da Portabilidade (/zh-Hans/documentation/guides/INSS/portability+refinancing/recalculate-portability) - Recálculo e Reformalização do Refinanciamento (/zh-Hans/documentation/guides/INSS/portability+refinancing/reformalization) - Simulação da Proposta (/zh-Hans/documentation/guides/INSS/portability+refinancing/simulacao) - Enumeradores (/zh-Hans/documentation/guides/INSS/reference/enumeradores) - Averbação e Desaverbação (/zh-Hans/documentation/guides/INSS/reservations/averbacao-e-desaverbacao) - Fura-fila (priority request) (/zh-Hans/documentation/guides/INSS/reservations/priority-request) - Fila prioritária (/zh-Hans/documentation/guides/INSS/reservations/priority-reservation) - Assinatura em grupo (INSS) (/zh-Hans/documentation/guides/INSS/signatures/batch-group-signature) --- # Consulta de Dados do Benefício URL: /zh-Hans/documentation/guides/INSS/inquiries/dados-do-beneficio Consulta de Dados do Benefício Consulta saldo, margem e situação de um benefício (`POST /social_security/balance_request`). Uma consulta de dados **válida** é pré-requisito da averbação: sem ela, o pedido de averbação fica pendente de ação do parceiro. A consulta pode ser feita com o Termo de Autorização já enviado na [consulta da lista de benefícios](/documentation/guides/INSS/inquiries/lista-de-beneficios), ou enviando o termo na própria requisição. ## Caso 1 — Termo de Autorização previamente enviado Consulta de dados do benefício com o Termo de Autorização previamente enviado. ### Request ENDPOINT /social_security/balance_request MÉTODO POST Testar no Playground Request Body ```json { "document_number": "14950479032", "benefit_number": "22255220" } ``` ### Response ENDPOINT /social_security/balance_request MÉTODO POST Response Body ```json { "balance_request_key": "", "status": "pending_search" } ``` ## Caso 2 — Termo de Autorização enviado na própria consulta Consulta de dados do benefício com envio do Termo de Autorização. ### Request ENDPOINT /social_security/balance_request MÉTODO POST Request Body ```json { "document_number": "14950479032", "benefit_number": "22255220", "authorization_term": { "document_number": "14950479032", "legal_representative_document_number": "87237271016", "signature": { "signer": { "name": "Maria da Silva", "email": "maria.silva@email.com", "phone": { "number": "999538380", "area_code": "11", "country_code": "55" }, "document_number": "87237271016" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2024-11-07T14:28:23.382748Z", "ip_address": "179.145.48.219", "fingerprint": {}, "third_party_additional_data": {}, "session_id": "3571e292-3a83-4011-904d-20ee963022ef" }, "signed_object": { "document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383" } } } } ``` :::info Duração de Termo de Autorização O termo de autorização tem validade de 30 dias após a assinatura. Durante o periodo hábil, é possível consultar os dados do benefício sem reenviar autorização do cliente. Caso não tenha sido enviada a autorização, é necessário enviar o termo durante esta requisição. ::: :::caution Atenção Nos casos em que houver representante legal, é necessário preencher o campo **"legal_representative_document_number"** com o CPF do representante legal, e os dados do objeto **"signer"** devem ser preenchidos com os dados do mesmo. ::: --- ### Response ENDPOINT /social_security/balance_request MÉTODO POST Response Body ```json { "balance_request_key": "", "status": "pending_authorization" } ``` ## Webhook de sucesso Em caso de sucesso na consulta de dados do benefício WEBHOOK_TYPE social_security_balance_request STATUS Success Webhook Body ```json { "webhook_type": "social_security_balance_request", "key": "", "event_datetime": "", "status": "success", "data": { "name": "IVOLANDO MIRANDA", "state": "SP", "alimony": "not_payer", "birth_date": "07021961", "grant_date": "2022-09-02", "credit_type": "checking_account", "block_type": "not_blocked", "benefit_card": { "limit": 2083.2, "balance": 0 }, "benefit_number": "22255220", "benefit_status": "elegible", "payroll_card": { "limit": 2083.2, "balance": 0 }, "assistance_type": "retirement_by_age", "document_number": "14950479032", "benefit_end_date": "2020-12-01", "consigned_credit": { "balance": 1000 }, "benefit_situation": "active", "max_total_balance": 2000, "used_total_balance": 1000, "politically_exposed": { "type": "politically_exposed_level_1", "is_politically_exposed": true }, "has_power_of_attorney": false, "available_total_balance": 1000, "has_judicial_concession": false, "number_of_portabilities": 0, "disbursement_bank_account": { "bank_code": "341", "account_digit": "6", "account_branch": "0155", "account_number": "000059923" }, "has_entity_representation": false, "social_benefit_max_balance": 2000, "social_benefit_used_balance": 1000, "benefit_quota_expiration_date": null, "number_of_active_reservations": 0, "number_of_suspended_reservations": 0, "number_of_refinanced_reservations": 0, "number_of_active_suspended_reservations": 3 } } ``` ### Detalhamento de campos no webhook de sucesso | Campo | Descrição | Valores | |---------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| | assistance_type | Tipo do benefício | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#benefit_type_enumerator) | | benefit_status | Status do beneficio | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#benefit_status_enumerator) | | has_entity_representation | Possui entidade de representação (não permite averbação) | True ou False | | alimony_code | Classificador da Pensão alimentícia | not_payer, payer, benefit | | has_judicial_concession | Benefício concedido por liminar | True ou False | | has_power_of_attorney | Possui procurador? | True ou False | | credit_type | Tipo de crédito - recebimento do benefício | Magnetic_card, checking_account | | benefit_situation | Situação do benefício | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#benefit_situation_enumerator) | | used_total_balance | Valor total comprometido em averbações de empréstimos, reservado para portabilidade, refinanciamento, alterações, RMC e RCC | Numérico | | max_total_balance | Valor comprometido possível para a respectiva espécie do benefício | Numérico | | available_total_balance | Valor total disponível para empréstimo, somando todas as modalidades (diferença entre max_total_balance e used_total_balance) | Numérico | | benefit_quota_expiration_date | Data de extinção do benefício. A informação está disponível apenas para alguns benefícios de pensão por morte. | String ou nulo | block_type | Tipo de bloqueio do benefício | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#block_type_enumerator) | politically_exposed.type | Pessoa politicamente exposta | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#politically_exposed_enumerator) | is_politically_exposed | Pessoa politicamente exposta | True ou False ## Webhook de bloqueio Para os casos que o benefício está bloqueado WEBHOOK_TYPE social_security_balance_request STATUS Blocked Webhook Body ```json { "webhook_type": "social_security_balance_request", "key": "", "event_datetime": "", "status": "blocked", "data": { "benefit_blocked": true, "document_number": "12345678910", "balance_request_date": "2025-12-01", "block_date": "2025-11-17", "assistance_type": "retirement_by_age", "block_type": "blocked_by_benefitiary" } } ``` ### Detalhamento de campos no webhook de bloqueio | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | benefit_blocked | Status do bloqueio | True | | balance_request_date | Data da consulta | String | | block_date | Data do bloqueio | String ou nulo | | block_type | Tipo de bloqueio | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#block_type_enumerator) | ## Webhook de falha Em caso de falha na consulta da lista de benefícios WEBHOOK_TYPE social_security_balance_request STATUS Failure Webhook Body ```json { "webhook_type": "social_security_balance_request", "key": "", "event_datetime": "", "status": "failure", "data": { "enumerator": "not_found_legal_representative", "description": "no legal representative for the beneficiary" } } ``` ### Detalhamento de campos no webhook de falha | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_balance_errors_enumerators) | ## Simulando cenários de sucesso e insucesso na consulta de benefício em Sandbox: A simulação de cenários é baseado no primeiro dígito do CPF informado na operação. **11.1.** Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook. **11.2.** Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo. | Início do CPF | Enumerador | Descrição | |---------------|------------------------|----------------------| | 2 | inexistent_beneficiary | no beneficiary found | :::caution Atenção Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado. | Enumerador | Descrição | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: **11.3.** O CPF `18166261553` simula, com sucesso (HTTP 200, sem erro), um benefício com **margem consignável negativa** (`available_total_balance: -7.84`). Use este CPF para testar a rejeição de novas operações quando o beneficiário já excedeu a margem disponível. Lista completa de CPFs e cenários mockados: [Mocks (Sandbox)](/documentation/guides/INSS/mocks-sandbox). --- --- # Consulta da Lista de Benefícios URL: /zh-Hans/documentation/guides/INSS/inquiries/lista-de-beneficios Consulta da Lista de Benefícios Consulta os benefícios do INSS de um CPF (`POST /social_security/benefits_request`), com a formalização do Termo de Autorização feita pelo parceiro. É o **primeiro passo de qualquer operação INSS** — crédito novo, refinanciamento ou portabilidade. Próximo passo: [Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio). ## Request Caso 1: Titular do benefício é o assinante do Termo de Autorização. ENDPOINT /social_security/benefits_request MÉTODO POST Testar no Playground Request Body ```json { "document_number": "14950479032", "authorization_term": { "document_number": "14950479032", "signature": { "signer": { "name": "Maria da Silva", "email": "maria.silva@email.com", "phone": { "number": "999538380", "area_code": "11", "country_code": "55" }, "document_number": "87237271016" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2024-11-07T14:28:23.382748Z", "ip_address": "179.145.48.219", "fingerprint": {}, "third_party_additional_data": {}, "session_id": "3571e292-3a83-4011-904d-20ee963022ef" }, "signed_object": { "document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383" } } } } ``` Caso 2: Titular do benefício não é o assinante do Termo de Autorização (com representante legal). :::caution O assinante é o representante legal Quando o titular do benefício **não** é o assinante do Termo de Autorização, os dados que preenchem o objeto `signature.signer` são os **do representante legal**, não os do titular. ::: ENDPOINT /social_security/benefits_request MÉTODO POST Request Body ```json { "document_number": "14950479032", "authorization_term": { "document_number": "14950479032", "legal_representative_document_number": "87237271016", "signature": { "signer": { "name": "Maria da Silva", "email": "maria.silva@email.com", "phone": { "number": "999538380", "area_code": "11", "country_code": "55" }, "document_number": "87237271016" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2024-11-07T14:28:23.382748Z", "ip_address": "179.145.48.219", "fingerprint": {}, "third_party_additional_data": {}, "session_id": "3571e292-3a83-4011-904d-20ee963022ef" }, "signed_object": { "document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383" } } } } ``` :::caution Atenção Nos casos em que houver representante legal, é necessário preencher o campo **"legal_representative_document_number"** com o CPF do representante legal, e os dados do objeto **"signer"** devem ser preenchidos com os dados do mesmo. ::: --- "***document_key***": utilizar a GUID retornada no endpoint /upload Ao invés da chave do documento pdf assinado no objeto "authorization_term.signed_object.document_key", também é possível enviar o texto corrido do Termo de Autorização, através do objeto "authorization_term.signed_object.raw_text". ## Response ENDPOINT /social_security/benefits_request MÉTODO POST Response Body ```json { "benefits_request_key": "", "status": "pending_search" } ``` Resposta quando o Termo de Autorização ainda está pendente de autorização: Response Body ```json { "benefits_request_key": "c9d2aa83-006b-4753-92ad-64411a7aa700", "document_number": "18028522041", "status": "pending_authorization", "authorization_term": { "authorization_term_key": "5a7b6489-8a47-4b61-a85a-6986b058fda6", "status": "signed" }, "status_events": [ { "status": "pending_authorization", "event_date": "2023-12-22T16:12:50" } ] } ``` Em caso de sucesso na consulta da lista de benefícios: ## Webhooks WEBHOOK_TYPE social_security_benefits_request STATUS Success Webhook Body ```json { "webhook_type": "social_security_benefits_request", "key": "", "event_datetime": "", "status": "success", "data": [{ "benefit_number": "", "benefit_status": "inelegible", "grant_date": "2023-06-13" }] } ``` | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | benefit_number | Número do benefício | - | | benefit_status | Status do beneficio | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#benefit_status_enumerator) | Em caso de falha na consulta da lista de benefícios WEBHOOK_TYPE social_security_benefits_request STATUS Failure Webhook Body ```json { "webhook_type": "social_security_benefits_request", "key": "", "event_datetime": "", "status": "failure", "data": { "enumerator": "not_found_legal_representative", "description": "no legal representative for the beneficiary" } } ``` ## Detalhamento de campos no webhook de falha | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_benefits_errors_enumerators) | ## Simulando cenários de sucesso e insucesso na consulta de benefício em Sandbox: A simulação de cenários é baseado no primeiro dígito do CPF informado na operação. **11.1.** Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook. **11.2.** Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo. | Início do CPF | Enumerador | Descrição | |---------------|------------------------|----------------------| | 2 | inexistent_beneficiary | no beneficiary found | :::caution Atenção Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado. | Enumerador | Descrição | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: --- --- # Consulta Offline de Saldo URL: /zh-Hans/documentation/guides/INSS/inquiries/offline-balance-request Consulta Offline de Saldo Consulta os dados de saldo mais recentes salvos no nosso banco, de forma instantânea. :::tip Vantagens Técnicas - **Retorno síncrono** — sem fila de processamento ou espera por webhook; - **Acesso a benefícios bloqueados** — retorna os últimos dados salvos no sistema, mesmo que o benefício esteja bloqueado; - **Consulta em cache** — independe da disponibilidade da Dataprev e não gera consumo de chamadas. ::: Request ENDPOINT /social_security/balance_request/offline MÉTODO GET Query Params document_number string obrigatório CPF do beneficiário (apenas números, 11 dígitos). benefit_number string obrigatório Número do benefício INSS. **Python** ```python title="ENDPOINT" GET /social_security/balance_request/offline?document_number=14950479032&benefit_number=22255220 ``` **curl** ```bash title="ENDPOINT" curl -X GET \ 'https://api-auth.sandbox.qitech.app/social_security/balance_request/offline?document_number=14950479032&benefit_number=22255220' \ -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \ -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \ -H 'Content-Type: application/json' ``` Response STATUS 200 Atributos last_successful_balance_request object | null Última consulta bem-sucedida. `null` se nunca houve sucesso. **Atributos de last_successful_balance_request** consulted_at string Data e hora da consulta (ISO 8601). data object Dados completos de saldo do benefício. Mesma estrutura do [webhook de consulta de saldo](/documentation/roteiros_laas/webhooks_inss). Veja [detalhamento dos campos](#campos-de-data). **Atributos de data** name string Nome do beneficiário. document_number string CPF do beneficiário. benefit_number string Status do benefício (`elegible`, `inelegible`). block_type string Tipo de bloqueio (`not_blocked`, `blocked_by_tbm`, etc.). benefit_situation string Situação do benefício (`active`, `inactive`, etc.). assistance_type string Tipo de assistência/aposentadoria. available_total_balance number Margem total disponível para consignação. consigned_credit object Saldo de crédito consignado (`balance`). payroll_card object Cartão consignado (`balance`, `limit`). benefit_card object Cartão benefício (`balance`, `limit`). number_of_active_reservations integer Número de reservas ativas. disbursement_bank_account object Dados da conta bancária de desembolso (`bank_code`, `account_digit`, `account_branch`, `account_number`). last_blocked_status object | null Status de bloqueio mais recente. `null` se não há informação disponível. Derivado automaticamente da fonte **mais recente** — seja consulta de saldo, tentativa de reserva ou verificação do benefício. **Atributos de last_blocked_status** consulted_at string Data e hora da verificação mais recente (ISO 8601). status string `"blocked"` ou `"unblocked"`. :::info Ao menos um dos dois campos será preenchido em uma resposta 200. Caso não exista nenhum dado para a combinação informada, o endpoint retorna 404. ::: ```json title="RESPONSE BODY" { "last_successful_balance_request": { "consulted_at": "2025-01-15T14:32:10-03:00", "data": { "name": "NOME BENEFICIARIO", "state": "RS", "alimony": "not_payer", "birth_date": "18021978", "block_type": "not_blocked", "grant_date": "2006-05-22", "credit_type": "checking_account", "benefit_card": { "limit": 2259.20, "balance": 0 }, "benefit_number": "22255220", "benefit_status": "elegible", "payroll_card": { "limit": 2259.20, "balance": 0 }, "assistance_type": "retirement_invalidity_social_security", "document_number": "14950479032", "benefit_end_date": null, "consigned_credit": { "balance": 0 }, "benefit_situation": "active", "last_inquiry_date": "2018-06-18", "max_total_balance": 635.40, "used_total_balance": 635.40, "politically_exposed": { "type": "not_politically_exposed", "is_politically_exposed": false }, "has_power_of_attorney": false, "available_total_balance": 0, "has_judicial_concession": false, "number_of_portabilities": 0, "disbursement_bank_account": { "bank_code": "748", "account_digit": "4", "account_branch": "0155", "account_number": "000070963" }, "has_entity_representation": false, "social_benefit_max_balance": 635.40, "social_benefit_used_balance": 635.40, "benefit_quota_expiration_date": null, "number_of_active_reservations": 3, "number_of_suspended_reservations": 0, "number_of_refinanced_reservations": 0, "number_of_active_suspended_reservations": 3 } }, "last_blocked_status": { "consulted_at": "2025-01-15T14:32:10-03:00", "status": "unblocked" } } ``` ### Cenários de resposta | Cenário | `last_successful_balance_request` | `last_blocked_status.status` | |---------|-----------------------------------|------------------------------| | Apenas consultas com sucesso | Dados da última consulta | `"unblocked"` | | Apenas consultas com bloqueio | `null` | `"blocked"` | | Consulta com sucesso seguida de bloqueio posterior | Dados da última consulta | `"blocked"` | | Bloqueio seguido de consulta com sucesso | Dados da última consulta | `"unblocked"` | --- ## Erros | Código HTTP | Código QI | Descrição | |-------------|-----------|-----------| | 401/403 | (padrão) | Headers de autenticação ausentes ou inválidos | | 404 | `SSC000101` | Nenhum dado encontrado para a combinação de `document_number` + `benefit_number` | **Exemplo de resposta 404** ```json { "title": "Offline Balance Not Found", "description": "No balance data found for document_number {document_number} and benefit_number {benefit_number}.", "translation": "Nenhum dado de saldo encontrado para document_number {document_number} e benefit_number {benefit_number}", "code": "SSC000101" } ``` --- # Lista de Participantes do CTC URL: /zh-Hans/documentation/guides/INSS/inquiries/participantes-ctc Lista de Participantes do CTC Consulta as instituições financeiras participantes do CTC (Núclea/CIP) — a lista de onde sai a instituição credora original de uma portabilidade. **Request** - MÉTODO GET - ENDPOINT /v2/credit_transfer/participants Testar no Playground *Response:* **response.json** ```json [ { "name": "", "bank_code": "", "ispb": "" } ] ``` --- # Consulta de Portabilidade de Origem URL: /zh-Hans/documentation/guides/INSS/inquiries/portabilidade-de-origem Consulta de Portabilidade de Origem Recupera os dados do contrato de origem de uma portabilidade — o contrato que está sendo portado da instituição credora original. É possível consultar os dados da portabilidade do banco de origem como, por exemplo, o número do benefício, a data de início da portabilidade, o número dos contratos excluídos, os valores das parcelas desaverbadas, ultima parcela paga, data de exclusão, entre outros. **Request** - MÉTODO POST - ENDPOINT /social_security/reservation/external_key/CREDIT-OPERATION-KEY/portability_origin_contract *Payload:* **payload.json** ```json { "request_type":"portability_number", "portability_number": "202402070000298096242" } ``` **Response** - MÉTODO POST - ENDPOINT /social_security/reservation/external_key/CREDIT-OPERATION-KEY/portability_origin_contract **body.json** ```json { "origin_contract_request_key": "9bb68c89-4b88-400d-9359-99ad8d42a69e", "status": "pending_search", "status_events": [ { "status": "pending_search" } ] } ``` Em caso de sucesso na consulta do número de benefício **Webhook** - WEBHOOK_TYPE social_security_portability_origin_contract_request - STATUS Success **body.json** ```json { "webhook": { "key": "25e93655-4713-488b-8800-7ac4fddf745f", "data": { "portability_number": 9223372036854776000, "portability_status": "open", "benefit_number": 1544326820, "portability_start_date": "2024-02-22", "deleted_contracts": [ { "origin_bank": { "bank_code": 752, "name": "CETELEM-BNP" }, "contract_number": "22-844817807/20", "last_installment_paid": 84, "exclusion_date": "22022024", "period_amount": 165.73 } ] }, "status": "success", "webhook_type": "social_security_portability_origin_contract_request", "event_datetime": "2024-02-26T21:36:22" } } ``` Em caso de falha na consulta do número de benefício **Webhook** - WEBHOOK_TYPE social_security_portability_origin_contract_request - STATUS Failure **body.json** ```json { "webhook": { "key": "522b5d7d-2dfc-4e92-99b7-d4df3d97edb2", "data": { "enumerator": "invalid_bank_code", "description": "Invalid bank code" }, "status": "failure", "webhook_type": "social_security_portability_origin_contract_request", "event_datetime": "2024-02-26T21:36:22" } } ``` --- # Última Resposta da Averbação URL: /zh-Hans/documentation/guides/INSS/inquiries/ultima-resposta Última Resposta da Averbação Recupera, sob demanda, o **último retorno da Dataprev** para a averbação de uma operação — sem esperar um novo webhook. Use quando o webhook foi perdido, quando a operação está em retentativa ("teimosinha") ou para reconciliar o estado da garantia. O endpoint muda conforme a família da operação: a operação de crédito responde por `/debt/.../collateral`; a proposta de portabilidade, por `/v2/credit_transfer/proposal/.../collateral`. ## Crédito novo e refinanciamento A garantia da operação de crédito responde em `GET /debt/{credit_operation_key}/collateral`. O last response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Dataprev, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador). Os enumeradores estão diretamente relacionados aos códigos de retorno da Dataprev e são divididos em duas formas: "errors" e "success". Cada enumerador tem uma descrição detalhada e o código de referência da Dataprev. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response. ### Casos de sucesso #### Request ENDPOINT /debt/DEBT-KEY/collateral MÉTODO GET Testar no Playground #### Response Response Body ```json { "collateral_constituted": true, "collateral_type": "type", "updated_at": "2023-05-24 19:13:02", "collateral_data": { "state": "SP", "benefit_number": 1976703155, "status": "reserved", "last_response": { "success": [ { "enumerator": "succesfully_included", "reservation_method" : "new_credit" } ] }, "last_response_event_datetime": "2023-05-22T19:13:02Z" } } ``` ### Detalhamento de campos no retorno da request | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_success)| | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ### Casos de erro #### Request ENDPOINT /debt/DEBT-KEY/collateral MÉTODO GET #### Response Response Body ```json { "collateral_constituted": false, "collateral_type": "type", "updated_at": "2023-05-24 19:13:02", "collateral_data": { "state": "SP", "benefit_number": 1976703155, "status": "pending_reservation", "last_response": { "errors": [ { "enumerator": "benefit_blocked_by_tbm", "reservation_method" : "new_credit" } ] }, "last_response_event_datetime": "2023-05-22T19:13:02Z" } } ``` ### Detalhamento de campos no retorno da request | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_errors)| | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ## Portabilidade e refinanciamento (Troco) Na portabilidade a garantia é consultada pela proposta, informando em `credit-operation-type` qual das duas operações se quer ler. O last response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Dataprev, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador). Os enumeradores estão diretamente relacionados aos códigos de retorno da Dataprev e são divididos em duas formas: "errors" e "success". Cada enumerador tem uma descrição detalhada e o código de referência da Dataprev. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response. ### Casos de sucesso #### Request ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral MÉTODO GET #### Path Params — `credit-operation-type` | Enumerador | Descrição | |-------------------------------------------|--------------------------------| | refinancing_credit_operation | Operação de refinanciamento | | portability_credit_operation | Operação de portabilidade | #### Response Response Body ```json { "collateral_data":{ "benefit_number":1976703155, "state":"PI", "last_response":{ "success":[ { "enumerator":"succesfully_included", "reservation_method":"portability" } ] }, "last_response_event_datetime":"2023-05-22T19:13:02Z", "status":"reserved" }, "collateral_constituted":true, "collateral_type":"social_security" } ``` ### Detalhamento de campos no retorno da request | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_success)| | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ### Casos de erro #### Request ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral MÉTODO GET #### Response Response Body ```json { "collateral_constituted": false, "collateral_type": "type", "updated_at": "2023-05-24 19:13:02", "collateral_data": { "state": "SP", "benefit_number": 1976703155, "status": "pending_reservation", "last_response": { "errors": [ { "enumerator": "benefit_blocked_by_tbm", "reservation_method" : "portability" }, { "enumerator": "benefit_blocked_by_tbm", "reservation_method" : "new_credit" } ] }, "last_response_event_datetime": "2023-05-22T19:13:02Z" } } ``` ### Detalhamento de campos no webhook de falha | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_errors) | | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ## Última consulta do benefício Por esse endpoint é possível consultar quando foi a última consulta do benefício na Dataprev. ### Request ENDPOINT /social_security/benefit/BENEFIT-NUMBER MÉTODO GET Testar no Playground ### Response Response Body ```json { "last_balance_check": "2025-08-22T19:13:02Z", "status": "pending_balance_request" } ``` ## Webhook da última tentativa de averbação Caso a operação não tenha sucesso na averbação, a mesma ficará em retentativa e será enviado o seguinte webhook, detalhando o motivo da não averbação, o horário desta tentativa e o método de averbação utilizado: **Ver exemplos de webhook** **Webhook portabilidade** WEBHOOK_TYPE credit_transfer.proposal.credit_operation ```json { "webhook_type": "credit_transfer.proposal.collateral", "proposal_key": "", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "portability", "credit_operation_key": "", "collateral_type": "social_security", "collateral_constituted": false, "collateral_data": { "status": "pending_reservation", "last_response": { "errors": [{ "enumerator": "consignable_margin_excceded" }] }, "last_response_event_datetime": "2023-05-22T19:13:02Z", "reservation_method": "new_credit", } } } ``` **Webhook refinanciamento** WEBHOOK_TYPE credit_operation.collateral ```json { "webhook_type": "credit_operation.collateral", "key": "", "event_time": "2022-11-24T15:42:12", "data": { "collateral_type": "social_security", "collateral_constituted": false, "collateral_data": { "status": "pending_reservation", "last_response": { "errors": [{ "enumerator": "consignable_margin_excceded" }] }, "last_response_event_datetime": "2023-05-22T19:13:02Z", "reservation_method": "refinancing", } } } ``` ### Detalhamento de campos no webhook de falha | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_errors) | | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| --- # Mocks (Sandbox) URL: /zh-Hans/documentation/guides/INSS/mocks-sandbox Mocks (Sandbox) :::danger Aviso Importante! Não utilize dados pessoais reais (CPF, CNPJ etc.) em ambiente sandbox. ::: A `social-security-api` intercepta as chamadas à Dataprev em ambiente sandbox/dev e retorna respostas mockadas via [`dataprev_mocker.py`](https://gitlab.qitech.com.br/qilaas/social-security-api/-/blob/master/src/connectors/dataprev_mocker.py). Cada etapa da jornada tem sua própria chave de simulação: | Etapa | O que decide o cenário | |---|---| | [Consulta de saldo/margem](#consulta-de-saldo) | CPF — match exato ou **primeiro dígito** | | [Averbação da reserva](#averbacao) | **Primeiro dígito** do CPF | | [Anuência (`pending_confirmation`)](#anuencia) | **Último dígito** do número do benefício | :::tip Jornada completa em sandbox Para que a operação percorra a jornada inteira até o desembolso, o CPF e o número do benefício precisam cair, ao mesmo tempo, num cenário de sucesso de **saldo**, de **averbação** e de **anuência**. Combinação recomendada: CPF iniciado em `1` e benefício terminado em `0`. ::: ## Consulta de saldo {#consulta-de-saldo} A consulta de saldo/margem (`DataprevMocker.get_balance_mocker`) resolve o `document_number` em duas etapas: 1. Tenta um **match exato** do CPF contra a massa de teste. 2. Se não encontrar, usa o **primeiro dígito** do CPF como chave. Se nenhuma das duas resolver, retorna o erro fixo: ```json { "erros": [ { "codigo": "QIE", "mensagem": "CPF divergente da massa de teste informada na documentação." } ] } ``` com HTTP `412`. ### Cenários por primeiro dígito (fallback) Qualquer CPF de teste cujo primeiro dígito seja um dos abaixo cai num destes cenários genéricos — útil quando você não precisa de um CPF fixo: | 1º dígito | Cenário | `margemDisponivel` | Status | |---|---|---|---| | `1` | Margem completa, elegível, sem bloqueios | 431.3 | 200 | | `2` | Erro Dataprev `D1` — dados do benefício incompletos/inconsistentes/nulos | — | 412 | | `3` | Margem de cartão/RCC reduzida (R$ 75,90) | 431.3 | 200 | | `4` | Margem completa (idêntico ao dígito `1`) | 431.3 | 200 | | `8` | Margem de cartão/RCC zerada | 431.3 | 200 | CPFs com primeiro dígito `0`, `5`, `6`, `7` ou `9` (e que não tenham match exato) caem no erro `QIE` acima. Além desses, o mocker reconhece 42 CPFs com match exato — a tabela completa está abaixo. ### CPFs com match exato Campos já mapeados para o schema público da QI: `consigned_credit.balance` vem de `margemDisponivel`, `available_total_balance` vem de `valorDisponivelAverbacaoEmprestimo`. Boa parte dos CPFs com `retirement_invalidity_work_accident` existe só pra cobrir uma faixa de valores de `available_total_balance` (de R$ 50 a R$ 900) — útil pra testar simulação de dívida contra um teto de margem específico. | CPF | Benefício (código) | Elegível | Situação | Bloqueio | `consigned_credit.balance` | `available_total_balance` | Status | |---|---|---|---|---|---|---|---| | `18166261553` | retirement_by_contribution_time (42) — **margem negativa** | Sim | ATIVO | - | **-7.84** | **-7.84** | 200 | | `30449750345` | pension_by_death_statute (22) | Não | INATIVO | Bloqueado por TBM | 1000 | 0 | 200 | | `58992386400` | pension_by_death_statute (22) | Não | ATIVO | Bloqueado por TBM | 1000 | 0 | 200 | | `15588881010` | retirement_capin_extra_emploee (37) | Sim | ATIVO | - | 1000 | 200 | 200 | | `80436724154` | retirement_invalidity_work_accident (92) | Não | INATIVO | Bloqueado por TBM | 1000 | 5000 | 200 | | `34166302540` | pension_by_death_federal_emploee (27) | Não | ATIVO | Bloqueado por TBM | 1000 | 5000 | 200 | | `71020884851` | pension_by_death_diplomat (20) | Não | ATIVO | Bloqueado por TBM | 1000 | 5000 | 200 | | `76241089684` | retirement_invalidity_work_accident (92) | Não | ATIVO | Bloqueado por TBM | 1000 | 5000 | 200 | | `44559483922` | pension_by_death (21) | Não | ATIVO | Bloqueado por TBM | 1000 | 5000 | 200 | | `14429281238` | pension_by_death_statute (22) | Sim | ATIVO | - | 1000 | 300 | 200 | | `15843101037` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 2000 | 200 | | `13686315092` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 2000 | 200 | | `14937159097` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 50 | 200 | | `15986213009` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 1000 | 200 | | `17427272048` | retirement_by_age (41) | Sim | ATIVO | - | 1000 | 1600 | 200 | | `16110575070` | retirement_by_age (41) | Sim | ATIVO | - | 1000 | 2000 | 200 | | `14996024054` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 100 | 200 | | `17702273003` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 150 | 200 | | `12228342009` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 200 | 200 | | `11709160071` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 250 | 200 | | `12452312002` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 300 | 200 | | `10650137019` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 350 | 200 | | `17287554097` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 400 | 200 | | `19815793039` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 450 | 200 | | `11985375079` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 500 | 200 | | `14732376029` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 750 | 200 | | `10178596043` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 600 | 200 | | `17859801060` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 650 | 200 | | `11524380857` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 700 | 200 | | `19447847056` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 800 | 200 | | `10813389038` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 850 | 200 | | `35776131499` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 900 | 200 | | `17283313079` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 | | `14552515004` | retirement_by_age (41) | Sim | ATIVO | - | 1000 | 300 | 200 | | `14036419005` | retirement_invalidity_social_security (32) | Sim | ATIVO | - | 1000 | 300 | 200 | | `13423241020` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 200 | 200 | | `12382929090` | retirement_special (46) | Sim | ATIVO | - | 1000 | 200 | 200 | | `73527133011` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 | | `55111830081` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 | | `83995332030` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 | | `65954790019` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 | | `16257311080` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 | Todos os CPFs acima retornam `bloqueadoParaEmprestimo: false`, exceto os marcados com "Bloqueado por TBM" na coluna Bloqueio (que ainda assim respondem HTTP 200 com `elegivelEmprestimo: false`). **Exemplo de requisição** (funciona com qualquer CPF da tabela): ENDPOINT /social_security/balance_request/synchronous MÉTODO POST ```python title="ENDPOINT" POST /social_security/balance_request/synchronous { "document_number": "18166261553", "benefit_number": "2052711150" } ``` Resposta (HTTP 200) para o CPF de margem negativa, já mapeada para o schema público: ```json { "assistance_type": "retirement_by_contribution_time", "available_total_balance": -7.84, "consigned_credit": { "balance": -7.84 }, "payroll_card": { "balance": 0, "limit": 2083.2 }, "benefit_card": { "balance": 0, "limit": 2083.2 }, "block_type": "not_blocked", "benefit_situation": "active" } ``` ## Averbação {#averbacao} O envio da reserva à Dataprev (`DataprevMocker.send_reserve_balance`) é resolvido **apenas pelo primeiro dígito do CPF** — o número do benefício não influencia esta etapa: | 1º dígito do CPF | Retorno mockado | Status | |---|---|---| | `1` | Sucesso `BZ` — "Averbação registrada" | 200 | | `2` | Erro `AN` — "Conta corrente/DV do favorecido inválidos" | 412 | | `3` | Depende do valor da operação: até R$ 1.000,00 sucesso `BZ`; acima disso, erro `HW` — "Margem consignável excedida" | 200 / 412 | | `4` | Sucesso `BZ` — "Averbação registrada" | 200 | Qualquer outro primeiro dígito retorna o erro `QIE` ("CPF divergente da massa de teste informada na documentação"), com HTTP `412`. :::note Averbação bem-sucedida **não** conclui a reserva: em crédito novo e refinanciamento ela entra em [anuência](#anuencia). Portabilidade não exige anuência e segue direto para `reserved`. ::: ## Anuência {#anuencia} Depois da averbação, crédito novo e refinanciamento ficam em `pending_confirmation` até a Dataprev informar a confirmação do beneficiário — veja [Anuência (pending confirmation)](/documentation/guides/INSS/pending_confirmation) para o fluxo e os webhooks. Em sandbox, a resposta dessa consulta é determinada pelo **último dígito do número do benefício** informado na reserva: | Último dígito do benefício | Situação Dataprev simulada | Desfecho da reserva | |---|---|---| | `0`, `1`, `6` | 0 — Ativo | ✅ Confirmada → `reserved`, webhook de averbação e desembolso | | `5` | 5 — Averbação programada | ✅ Confirmada → `reserved` | | `3` | 18 na 1ª página, 0 na 2ª | ✅ Confirmada → `reserved` (exercita a paginação) | | `8` | 18 — Pendente de confirmação | ⏳ Permanece em `pending_confirmation` | | `9` | 19 — Não confirmado pelo beneficiário | ❌ Cancelada — `social_security_confirmation_denied_by_beneficiary` | | `7` | 20 — Confirmação expirada | ❌ Nova tentativa de reserva ou cancelamento — `social_security_confirmation_expired` | | `2` | Resposta sem registros | ⏳ Permanece em `pending_confirmation` | | `4` | Erro `GR` — "O período está inválido" | ⏳ Permanece em `pending_confirmation` | :::warning Benefícios terminados em `2` e `4` Nesses dois cenários a consulta nunca devolve uma situação conclusiva, então a reserva fica em `pending_confirmation` indefinidamente e os webhooks de averbação e de pagamento não são emitidos. Se o objetivo é testar a jornada completa, use um benefício terminado em `0`, `1`, `3`, `5` ou `6`. ::: ## Referências - [`dataprev_mocker.py`](https://gitlab.qitech.com.br/qilaas/social-security-api/-/blob/master/src/connectors/dataprev_mocker.py) — massa de teste completa - [Consulta Offline de Saldo](/documentation/guides/INSS/inquiries/offline-balance-request) — schema de resposta completo --- # Emissão da Operação URL: /zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/emissao Emissão da Operação Cria a operação de crédito (`POST /debt`) para um benefício do INSS, com a garantia `social_security` que dá origem ao pedido de averbação na Dataprev. Antes: [Simulação da Dívida](/documentation/guides/INSS/new-credit-and-refinancing/simulacao) e [Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio). Depois: [Formalização](/documentation/guides/INSS/new-credit-and-refinancing/formalizacao). :::caution Atenção Para operações em que ainda não se passaram 90 dias desde a data de Despacho Benefício e a averbação não é permitida, é necessário garantir que a soma de disbursement_date e limit_days_to_disburse resulte em uma data posterior aos 90 dias. Caso essa regra não seja cumprida, a operação será cancelada permanentemente, com o CancelReason: social_security_margin_release_after_disbursement_end_date. ::: O campo "assistance_type", localizado dentro do objeto "collateral_data", refere-se ao tipo de benefício que está sendo utilizado para o empréstimo. O mesmo é retornado na consulta de dados do benefício. Para visualizar os valores possíveis (enumeradores), consultar a tabela [Tabela de enumerador](/documentation/guides/INSS/reference/enumeradores#benefit_type_enumerator) :::warning Atenção O objeto `credit_agent` representa o agente de crédito, por vezes conhecido como pastinha, responsável pela originação desta dívida. Este campo é obrigatório para a emissão de dívidas de consignados. ::: :::warning CIN — Carteira de Identidade Nacional O campo `document_identification_type` agora aceita o valor `cin` (Carteira de Identidade Nacional). Quando utilizado, o campo `document_identification_number` **deve ser igual ao CPF** do portador (`individual_document_number`). O número do CIN é o próprio CPF. Valores aceitos em `document_identification_type`: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. **Atenção:** o envio do documento de identificação (`document_identification`) passará a ser **obrigatório** nas operações de crédito INSS (crédito novo e portabilidade). Comunique seus integradores com antecedência. ::: :::info Assinatura em grupo (opcional) Para reunir esta dívida com outras operações INSS do **mesmo beneficiário** e coletar **uma única assinatura**, envie `document_batch_group_key` na **raiz** do payload (mesmo nível de `borrower`, `financial` etc.). Nesse caso, a assinatura fica vinculada à pasta do grupo e o link único é obtido no envio do grupo para assinatura. Consulte o fluxo de [Assinatura em grupo](/documentation/guides/INSS/signatures/batch-group-signature). ::: ## Request Caso 1: Emissão sem representante legal ENDPOINT /debt MÉTODO POST Testar no Playground **Crédito Novo** ```json title='Request Body' { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "financial": { "interest_type": "pre_price_days", "first_due_date": "2023-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.0166, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 101.84, "limit_days_to_disburse": 7, "number_of_installments": 10, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644799" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ] } ``` **Refinanciamento** ```json title='Request Body' { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ], "refinanced_credit_operations": [ { "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b" } ] } ``` **Crédito Novo - Aumento Salarial** ```json title='Request Body' { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "operation_category": "minimum_wage_increase", "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ] } ``` Caso 2: Emissão com representante legal ENDPOINT /debt MÉTODO POST **Crédito Novo** ```json { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "related_parties": [ { "name": "Representante legal", "email": "teste@qitech.com.br", "phone": { "number": "991294043", "area_code": "55", "country_code": "055" }, "address": { "street": "AV LEONOR", "state": "SP", "city": "GUARULHOS", "neighborhood": "", "number": "1", "postal_code": "07025200", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "is_pep": false, "individual_document_number": "19125869086", "birth_date": "1970-04-20", "mother_name": " Ana Lúcia" } ], "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ] } ``` **Refinanciamento** ```json { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "related_parties": [ { "name": "Representante legal", "email": "teste@qitech.com.br", "phone": { "number": "991294043", "area_code": "55", "country_code": "055" }, "address": { "street": "AV LEONOR", "state": "SP", "city": "GUARULHOS", "neighborhood": "", "number": "1", "postal_code": "07025200", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "is_pep": false, "individual_document_number": "19125869086", "birth_date": "1970-04-20", "mother_name": " Ana Lúcia" } ], "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ], "refinanced_credit_operations": [ { "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b" } ] } ``` **Crédito Novo - Aumento Salarial** ```json { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "related_parties": [ { "name": "Representante legal", "email": "teste@qitech.com.br", "phone": { "number": "991294043", "area_code": "55", "country_code": "055" }, "address": { "street": "AV LEONOR", "state": "SP", "city": "GUARULHOS", "neighborhood": "", "number": "1", "postal_code": "07025200", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "is_pep": false, "individual_document_number": "19125869086", "birth_date": "1970-04-20", "mother_name": " Ana Lúcia" } ], "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "operation_category": "minimum_wage_increase", "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ], "refinanced_credit_operations": [ { "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b" } ] } ``` Exemplo de objeto financial com rebates ```json { "financial": { "first_due_date": "2022-12-07", "installment_face_value": 100, "disbursement_date": "2022-11-03", "limit_days_to_disburse": 3, "number_of_installments": 24, "disbursed_amount": 1876, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0, "rebates": [ { "amount": 20, "rebate_bank_account": { "name": "Teste Ltda", "document_number": "18533555000164", "account_digit": "0", "account_number": "4290001", "branch_number": "0001", "bank_code": "329" }, "amount_type": "percentage", "fee_type": "spread" } ] } } ``` ## Response ENDPOINT /debt MÉTODO POST A resposta traz **uma opção por data de desembolso disponível** em `disbursement_options`, todas idênticas em estrutura e diferindo apenas na data e nos valores que ela move (juros, IOF, valor de cessão e o cronograma de parcelas). No exemplo real desta operação vieram 8 opções, de 2024-11-07 a 2024-11-14; o corpo abaixo mantém as **duas primeiras**. Response Body ```json { "webhook_type": "debt", "key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00", "status": "waiting_signature", "event_datetime": "2024-11-07 23:19:22", "data": { "borrower": { "name": "Nome devedor", "document_number": "14471835092", "related_party_key": "28b7fc16-6d1f-467d-9667-62a8c13daea6" }, "contract": { "number": "TST0000644710", "urls": [ "https://storage.googleapis.com/sandbox-doc-api/documents/a2e9c83a-3666-4def-8b27-e96fabb8705c/NOME_DEVEDOR-CCB-TST0000644710-20241107231916.pdf" ], "signature_information": [ { "signer_name": "Nome devedor", "signer_document_number": "14471835092", "signer_role": "issuer", "signer_email": null, "signer_external_key": null, "signature_url": null } ] }, "requester_identifier_key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00", "iof_charge_method": "financed", "collaterals": [ { "absolute_amount": null, "collateral_constituted": false, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "reservation_method": "issuing", "subcorban_document_number": "12123456000101" }, "collateral_key": "26c7f4f4-51f3-41fa-b880-9691211136aa", "collateral_type": "social_security", "created_at": "2024-11-07T23:19:16.413448", "external_key": null, "percentage": 1, "reservation_method": { "enumerator": "issuing" }, "updated_at": "2024-11-07T23:19:16.413441" } ], "disbursement_options": [ { "disbursement_date": "2024-11-07", "contract_fees": [ { "fee_type": "spread", "fee_amount": 4.55 }, { "fee_type": "ted_fee", "fee_amount": 1.5 } ], "external_contract_fees": [ { "fee_type": "spread", "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0 } ], "contract_fee_amount": 6.05, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "assignment_amount": 914.3, "issue_amount": 909.75, "cet": "2,0100%", "annual_cet": "27,0481%", "base_iof": 16.259002146803677, "additional_iof": 3.45705, "total_iof": 19.72, "total_pre_fixed_amount": 108.6508885851, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 74, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 909.75, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 37.1789024864, "principal_amortization_amount": 64.6610975136, "tax_amount": 0.3923635397125248, "total_amount": 101.84, "workdays": 49.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-02-20", "calendar_days": 31, "due_date": "2025-02-20", "due_interest": 0.0, "due_principal": 845.0889024864, "fine_amount": null, "has_interest": true, "installment_number": 2, "post_fixed_amount": null, "pre_fixed_amount": 14.2997636051, "principal_amortization_amount": 87.5402363949, "tax_amount": 0.753721435360089, "total_amount": 101.84, "workdays": 23.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-03-20", "calendar_days": 28, "due_date": "2025-03-20", "due_interest": 0.0, "due_principal": 757.5486660915, "fine_amount": null, "has_interest": true, "installment_number": 3, "post_fixed_amount": null, "pre_fixed_amount": 11.5685715131, "principal_amortization_amount": 90.2714284869, "tax_amount": 0.9845001990781314, "total_amount": 101.84, "workdays": 18.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-04-22", "calendar_days": 33, "due_date": "2025-04-22", "due_interest": 0.0, "due_principal": 667.2772376046, "fine_amount": null, "has_interest": true, "installment_number": 4, "post_fixed_amount": null, "pre_fixed_amount": 12.025984633, "principal_amortization_amount": 89.814015367, "tax_amount": 1.222548377175604, "total_amount": 101.84, "workdays": 21.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-05-20", "calendar_days": 28, "due_date": "2025-05-20", "due_interest": 0.0, "due_principal": 577.4632222376, "fine_amount": null, "has_interest": true, "installment_number": 5, "post_fixed_amount": null, "pre_fixed_amount": 8.8184725787, "principal_amortization_amount": 93.0215274213, "tax_amount": 1.4797864582180404, "total_amount": 101.84, "workdays": 19.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-06-20", "calendar_days": 31, "due_date": "2025-06-20", "due_interest": 0.0, "due_principal": 484.4416948163, "fine_amount": null, "has_interest": true, "installment_number": 6, "post_fixed_amount": null, "pre_fixed_amount": 8.1972396908, "principal_amortization_amount": 93.6427603092, "tax_amount": 1.72770892770474, "total_amount": 101.84, "workdays": 22.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-07-21", "calendar_days": 31, "due_date": "2025-07-21", "due_interest": 0.0, "due_principal": 390.7989345071, "fine_amount": null, "has_interest": true, "installment_number": 7, "post_fixed_amount": null, "pre_fixed_amount": 6.6127072945, "principal_amortization_amount": 95.2272927055, "tax_amount": 1.999011328473856, "total_amount": 101.84, "workdays": 21.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-08-20", "calendar_days": 30, "due_date": "2025-08-20", "due_interest": 0.0, "due_principal": 295.5716418016, "fine_amount": null, "has_interest": true, "installment_number": 8, "post_fixed_amount": null, "pre_fixed_amount": 4.8387153664, "principal_amortization_amount": 97.0012846336, "tax_amount": 2.274874127227187, "total_amount": 101.84, "workdays": 22.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-09-22", "calendar_days": 33, "due_date": "2025-09-22", "due_interest": 0.0, "due_principal": 198.570357168, "fine_amount": null, "has_interest": true, "installment_number": 9, "post_fixed_amount": null, "pre_fixed_amount": 3.5787172455, "principal_amortization_amount": 98.2612827545, "tax_amount": 2.570318634292211, "total_amount": 101.84, "workdays": 23.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-10-20", "calendar_days": 28, "due_date": "2025-10-20", "due_interest": 0.0, "due_principal": 100.3090744135, "fine_amount": null, "has_interest": true, "installment_number": 10, "post_fixed_amount": null, "pre_fixed_amount": 1.5318141716, "principal_amortization_amount": 100.3081858284, "tax_amount": 2.8541691195612935, "total_amount": 101.84, "workdays": 20.0, "installment_status": null, "installment_type": null } ], "first_due_date": "2025-01-20", "prefixed_interest_rate": { "monthly_rate": 0.0166, "daily_rate": 0.00054142, "annual_rate": 0.21843191, "interest_base": "calendar_days_365" } }, { "disbursement_date": "2024-11-08", "contract_fees": [ { "fee_type": "spread", "fee_amount": 4.55 }, { "fee_type": "ted_fee", "fee_amount": 1.5 } ], "external_contract_fees": [ { "fee_type": "spread", "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0 } ], "contract_fee_amount": 6.05, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "assignment_amount": 914.79, "issue_amount": 910.24, "cet": "2,0200%", "annual_cet": "27,0539%", "base_iof": 16.187351160427028, "additional_iof": 3.458912, "total_iof": 19.65, "total_pre_fixed_amount": 108.1583324947, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 73, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 910.24, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 36.6863463961, "principal_amortization_amount": 65.1536536039, "tax_amount": 0.3900097704729454, "total_amount": 101.84, "workdays": 48.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-02-20", "calendar_days": 31, "due_date": "2025-02-20", "due_interest": 0.0, "due_principal": 845.0863463961, "fine_amount": null, "has_interest": true, "installment_number": 2, "post_fixed_amount": null, "pre_fixed_amount": 14.2997636051, "principal_amortization_amount": 87.5402363949, "tax_amount": 0.7465431359757072, "total_amount": 101.84, "workdays": 23.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-03-20", "calendar_days": 28, "due_date": "2025-03-20", "due_interest": 0.0, "due_principal": 757.5461100012, "fine_amount": null, "has_interest": true, "installment_number": 3, "post_fixed_amount": null, "pre_fixed_amount": 11.5685715131, "principal_amortization_amount": 90.2714284869, "tax_amount": 0.9770979419422056, "total_amount": 101.84, "workdays": 18.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-04-22", "calendar_days": 33, "due_date": "2025-04-22", "due_interest": 0.0, "due_principal": 667.2746815143, "fine_amount": null, "has_interest": true, "installment_number": 4, "post_fixed_amount": null, "pre_fixed_amount": 12.025984633, "principal_amortization_amount": 89.814015367, "tax_amount": 1.21518362791551, "total_amount": 101.84, "workdays": 21.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-05-20", "calendar_days": 28, "due_date": "2025-05-20", "due_interest": 0.0, "due_principal": 577.4606661473, "fine_amount": null, "has_interest": true, "installment_number": 5, "post_fixed_amount": null, "pre_fixed_amount": 8.8184725787, "principal_amortization_amount": 93.0215274213, "tax_amount": 1.4721586929694939, "total_amount": 101.84, "workdays": 19.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-06-20", "calendar_days": 31, "due_date": "2025-06-20", "due_interest": 0.0, "due_principal": 484.439138726, "fine_amount": null, "has_interest": true, "installment_number": 6, "post_fixed_amount": null, "pre_fixed_amount": 8.1972396908, "principal_amortization_amount": 93.6427603092, "tax_amount": 1.7200302213593857, "total_amount": 101.84, "workdays": 22.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-07-21", "calendar_days": 31, "due_date": "2025-07-21", "due_interest": 0.0, "due_principal": 390.7963784168, "fine_amount": null, "has_interest": true, "installment_number": 7, "post_fixed_amount": null, "pre_fixed_amount": 6.6127072945, "principal_amortization_amount": 95.2272927055, "tax_amount": 1.991202690472005, "total_amount": 101.84, "workdays": 21.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-08-20", "calendar_days": 30, "due_date": "2025-08-20", "due_interest": 0.0, "due_principal": 295.5690857113, "fine_amount": null, "has_interest": true, "installment_number": 8, "post_fixed_amount": null, "pre_fixed_amount": 4.8387153664, "principal_amortization_amount": 97.0012846336, "tax_amount": 2.266920021887232, "total_amount": 101.84, "workdays": 22.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-09-22", "calendar_days": 33, "due_date": "2025-09-22", "due_interest": 0.0, "due_principal": 198.5678010777, "fine_amount": null, "has_interest": true, "installment_number": 9, "post_fixed_amount": null, "pre_fixed_amount": 3.5787172455, "principal_amortization_amount": 98.2612827545, "tax_amount": 2.562261209106342, "total_amount": 101.84, "workdays": 23.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-10-20", "calendar_days": 28, "due_date": "2025-10-20", "due_interest": 0.0, "due_principal": 100.3065183232, "fine_amount": null, "has_interest": true, "installment_number": 10, "post_fixed_amount": null, "pre_fixed_amount": 1.5318141715, "principal_amortization_amount": 100.3081858285, "tax_amount": 2.845943848326202, "total_amount": 101.84, "workdays": 20.0, "installment_status": null, "installment_type": null } ], "first_due_date": "2025-01-20", "prefixed_interest_rate": { "monthly_rate": 0.0166, "daily_rate": 0.00054142, "annual_rate": 0.21843191, "interest_base": "calendar_days_365" } } ] } } ``` Caso a operação não seja assinada ou averbada até a última opção de data de desembolso o parceiro receberá um webhook informando a respeito do cancelamento da operação: WEBHOOK_TYPE debt STATUS Canceled **Webhook Body** ```json { "key": "", "data": { "cancel_reason": "Operacao cancelada manualmente", "cancel_reason_enumerator": "manual" }, "status": "canceled", "webhook_type": "debt", "event_datetime": "2022-11-01 03:46:31" } ``` ## Simulando cenários de sucesso e insucesso na averbação em Sandbox: A simulação de cenários é baseado no primeiro dígito do CPF informado na operação. **11.1.** Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook. **11.2.** Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo. **11.3.** Erros com Ação "cancel" receberá um webhook com o resultado final da operação. | Início do cpf | Enumerador | Descrição | Ação | |---------------|------------------------------|-----------------------------------------------------------------------------------|--------| | 2 | invalid_disbursement_account | Invalid disbursemente bank account | cancel | | 3 | operation_not_allowed_IR | Operation not allowed due to operation deadline greatter than benefit termination | cancel | :::caution Atenção Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado. | Enumerador | Descrição | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: --- # INSS 手册 - 新增信贷或再融资 URL: /zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/end-to-end :::info 另请参阅 - [转入移植 + 再融资](/documentation/guides/INSS/portability+refinancing/end-to-end) ::: :::danger 注意！ QI Tech 的 webhook 不应以严格方式映射。 返回的 webhook payload 中可能会添加额外字段。 ::: :::info Webhook 重发 您可以按照文档中的详细说明查询并重发 webhook：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。 ::: :::info 授权条款有效期 授权条款自签署之日起有效期为 30 天。在有效期内，可以在无需重新发送客户授权的情况下查询福利数据。 ::: ## 1 - 通过合作方完成授权条款后查询福利列表： ### Request 情形 1：福利持有人即为授权条款的签署人。 ENDPOINT /social_security/benefits_request MÉTODO POST 在 Playground 中测试 Request Body ```json { "document_number": "14950479032", "authorization_term": { "document_number": "14950479032", "signature": { "signer": { "name": "Maria da Silva", "email": "maria.silva@email.com", "phone": { "number": "999538380", "area_code": "11", "country_code": "55" }, "document_number": "87237271016" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2024-11-07T14:28:23.382748Z", "ip_address": "179.145.48.219", "fingerprint": {}, "third_party_additional_data": {}, "session_id": "3571e292-3a83-4011-904d-20ee963022ef" }, "signed_object": { "document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383" } } } } ``` 情形 2：福利持有人不是授权条款的签署人（有法定代表人）。 ENDPOINT /social_security/benefits_request MÉTODO POST Request Body ```json { "document_number": "14950479032", "authorization_term": { "document_number": "14950479032", "legal_representative_document_number": "87237271016", "signature": { "signer": { "name": "Maria da Silva", "email": "maria.silva@email.com", "phone": { "number": "999538380", "area_code": "11", "country_code": "55" }, "document_number": "87237271016" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2024-11-07T14:28:23.382748Z", "ip_address": "179.145.48.219", "fingerprint": {}, "third_party_additional_data": {}, "session_id": "3571e292-3a83-4011-904d-20ee963022ef" }, "signed_object": { "document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383" } } } } ``` :::caution 注意 在有法定代表人的情况下，需要在 **"legal_representative_document_number"** 字段中填写法定代表人的 CPF，且 **"signer"** 对象中的数据也应填写法定代表人的信息。 ::: --- "***document_key***"：使用 /upload 端点返回的 GUID。 除了在 "authorization_term.signed_object.document_key" 对象中使用已签署 PDF 文档的密钥外，也可以通过 "authorization_term.signed_object.raw_text" 对象发送授权条款的原始文本。 ### Response ENDPOINT /social_security/benefits_request MÉTODO POST Response Body ```json { "benefits_request_key": "\", "status": "pending_search" } ``` 福利列表查询成功时： ### Webhooks WEBHOOK_TYPE social_security_benefits_request STATUS Success Webhook Body ```json { "webhook_type": "social_security_benefits_request", "key": "\", "event_datetime": "\", "status": "success", "data": [{ "benefit_number": "\", "benefit_status": "inelegible", "grant_date": "2023-06-13" }] } ``` | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|------------------------------------------| | benefit_status | 福利状态 | [枚举值](#benefit_status_enumerator) | 福利列表查询失败时 WEBHOOK_TYPE social_security_benefits_request STATUS Failure Webhook Body ```json { "webhook_type": "social_security_benefits_request", "key": "\", "event_datetime": "\", "status": "failure", "data": { "enumerator": "not_found_legal_representative", "description": "no legal representative for the beneficiary" } } ``` ### 失败 webhook 字段详解 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|------------------------------------------| | enumerator | Dataprev 代码的映射返回值 | [枚举值](#dataprev_benefits_errors_enumerators) | ### 在 Sandbox 中模拟福利查询的成功与失败场景： 场景模拟基于操作中提供的 CPF 的第一位数字。 **11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。 **11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字，按照下表返回异步错误响应。 | CPF 首位数字 | 枚举值 | 描述 | |--------------|------------------------|----------------------| | 2 | inexistent_beneficiary | no beneficiary found | :::caution 注意 所有第一位数字未映射到对应场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。 | 枚举值 | 描述 | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: --- ## 2 - 查询福利数据：{#consulta-de-dados} ### 情形 1 使用已提交的授权条款查询福利数据。 #### Request ENDPOINT /social_security/balance_request MÉTODO POST 在 Playground 中测试 Request Body ```json { "document_number": "14950479032", "benefit_number": "22255220" } ``` #### Response ENDPOINT /social_security/balance_request MÉTODO POST Response Body ```json { "balance_request_key": "\", "status": "pending_search" } ``` ### 情形 2 提交授权条款时查询福利数据。 #### Request ENDPOINT /social_security/balance_request MÉTODO POST Request Body ```json { "document_number": "14950479032", "benefit_number": "22255220", "authorization_term": { "document_number": "14950479032", "legal_representative_document_number": "87237271016", "signature": { "signer": { "name": "Maria da Silva", "email": "maria.silva@email.com", "phone": { "number": "999538380", "area_code": "11", "country_code": "55" }, "document_number": "87237271016" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2024-11-07T14:28:23.382748Z", "ip_address": "179.145.48.219", "fingerprint": {}, "third_party_additional_data": {}, "session_id": "3571e292-3a83-4011-904d-20ee963022ef" }, "signed_object": { "document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383" } } } } ``` :::info 授权条款有效期 授权条款自签署之日起有效期为 30 天。在有效期内，可以在无需重新发送客户授权的情况下查询福利数据。如果尚未发送授权，则需要在此请求中发送条款。 ::: :::caution 注意 在有法定代表人的情况下，需要在 **"legal_representative_document_number"** 字段中填写法定代表人的 CPF，且 **"signer"** 对象中的数据也应填写法定代表人的信息。 ::: --- #### Response ENDPOINT /social_security/balance_request MÉTODO POST Response Body ```json { "balance_request_key": "\", "status": "pending_authorization" } ``` ### 成功 webhook 福利数据查询成功时 WEBHOOK_TYPE social_security_balance_request STATUS Success Webhook Body ```json { "webhook_type": "social_security_balance_request", "key": "\", "event_datetime": "\", "status": "success", "data": { "name": "IVOLANDO MIRANDA", "state": "SP", "alimony": "not_payer", "birth_date": "07021961", "grant_date": "2022-09-02", "credit_type": "checking_account", "block_type": "not_blocked", "benefit_card": { "limit": 2083.2, "balance": 0 }, "benefit_number": "22255220", "benefit_status": "elegible", "payroll_card": { "limit": 2083.2, "balance": 0 }, "assistance_type": "retirement_by_age", "document_number": "14950479032", "benefit_end_date": "2020-12-01", "consigned_credit": { "balance": 1000 }, "benefit_situation": "active", "max_total_balance": 2000, "used_total_balance": 1000, "politically_exposed": { "type": "politically_exposed_level_1", "is_politically_exposed": true }, "has_power_of_attorney": false, "available_total_balance": 1000, "has_judicial_concession": false, "number_of_portabilities": 0, "disbursement_bank_account": { "bank_code": "341", "account_digit": "6", "account_branch": "0155", "account_number": "000059923" }, "has_entity_representation": false, "social_benefit_max_balance": 2000, "social_benefit_used_balance": 1000, "benefit_quota_expiration_date": null, "number_of_active_reservations": 0, "number_of_suspended_reservations": 0, "number_of_refinanced_reservations": 0, "number_of_active_suspended_reservations": 3 } } ``` #### 成功 webhook 字段详解 | 字段 | 描述 | 值 | |-----------------------------|------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| | assistance_type | 福利类型 | [枚举值](#benefit_type_enumerator) | | benefit_status | 福利状态 | [枚举值](#benefit_status_enumerator) | | has_entity_representation | 是否有代理实体（不允许批注） | True 或 False | | alimony_code | 赡养费分类 | not_payer, payer, benefit | | has_judicial_concession | 福利是否通过临时禁令批准 | True 或 False | | has_power_of_attorney | 是否有代理人？ | True 或 False | | credit_type | 信贷类型 - 福利收款方式 | Magnetic_card, checking_account | | benefit_situation | 福利状态 | [枚举值](#benefit_situation_enumerator) | | used_total_balance | 已用于贷款批注、保留用于可携性、再融资、变更、RMC 和 RCC 的总金额 | 数值 | | max_total_balance | 对应福利种类可承诺的金额 | 数值 | | available_total_balance | 所有方式下可用于贷款的总金额（max_total_balance 与 used_total_balance 的差值） | 数值 | | benefit_quota_expiration_date | 福利终止日期。该信息仅适用于部分遗属抚恤金福利。 | 字符串或空值 | block_type | 福利锁定类型 | [枚举值](#block_type_enumerator) | politically_exposed.type | 政治敏感人士 | [枚举值](#politically_exposed_enumerator) | is_politically_exposed | 是否为政治敏感人士 | True 或 False ### 锁定 webhook 福利被锁定时 WEBHOOK_TYPE social_security_balance_request STATUS Blocked Webhook Body ```json { "webhook_type": "social_security_balance_request", "key": "\", "event_datetime": "\", "status": "blocked", "data": { "benefit_blocked": true, "document_number": "12345678910", "balance_request_date": "2025-12-01", "block_date": "2025-11-17", "assistance_type": "retirement_by_age", "block_type": "blocked_by_benefitiary" } } ``` #### 锁定 webhook 字段详解 | 字段 | 描述 | 值 | |---------------------------|-----------------------|------------------------------------------| | benefit_blocked | 锁定状态 | True | | balance_request_date | 查询日期 | 字符串 | | block_date | 锁定日期 | 字符串或空值 | | block_type | 锁定类型 | [枚举值](#block_type_enumerator) | ### 失败 webhook 福利列表查询失败时 WEBHOOK_TYPE social_security_balance_request STATUS Failure Webhook Body ```json { "webhook_type": "social_security_balance_request", "key": "\", "event_datetime": "\", "status": "failure", "data": { "enumerator": "not_found_legal_representative", "description": "no legal representative for the beneficiary" } } ``` #### 失败 webhook 字段详解 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|------------------------------------------| | enumerator | Dataprev 代码的映射返回值 | [枚举值](#dataprev_balance_errors_enumerators) | ### 在 Sandbox 中模拟福利查询的成功与失败场景： 场景模拟基于操作中提供的 CPF 的第一位数字。 **11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。 **11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字，按照下表返回异步错误响应。 | CPF 首位数字 | 枚举值 | 描述 | |--------------|------------------------|----------------------| | 2 | inexistent_beneficiary | no beneficiary found | :::caution 注意 所有第一位数字未映射到对应场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。 | 枚举值 | 描述 | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: --- ## 3 - 债务模拟： ### 新增信贷 Request ENDPOINT /debt_simulation MÉTODO POST 在 Playground 中测试 **分期金额** ```json title='Request Body' { "borrower": { "person_type": "natural" }, "financial": { "first_due_date": "2024-12-07", "installment_face_value": 100, "disbursement_date": "2024-11-05", "limit_days_to_disburse": 3, "number_of_installments": 4, "monthly_interest_rate": 0.018, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0 }, "collaterals": [ { "collateral_type": "social_security" } ] } ``` **放款金额** ```json title='Request Body' { "borrower": { "person_type": "natural" }, "financial": { "first_due_date": "2024-12-07", "disbursed_amount": 1000, "disbursement_date": "2024-11-05", "limit_days_to_disburse": 3, "number_of_installments": 4, "monthly_interest_rate": 0.018, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0 }, "collaterals": [ { "collateral_type": "social_security" } ] } ``` ### 再融资 Request ENDPOINT /debt_simulation MÉTODO POST **分期金额** ```json { "borrower": { "person_type": "natural" }, "financial": { "first_due_date": "2024-12-07", "installment_face_value": 100, "disbursement_date": "2024-11-05", "limit_days_to_disburse": 3, "number_of_installments": 4, "monthly_interest_rate": 0.018, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0 }, "collaterals": [ { "collateral_type": "social_security" } ], "refinanced_credit_operations": [ { "operation_key": "324caa35-ba10-4590-ae2b-5efef71709c3" } ] } ``` **放款金额** ```json { "borrower": { "person_type": "natural" }, "financial": { "first_due_date": "2024-12-07", "disbursed_amount": 1000, "disbursement_date": "2024-11-05", "limit_days_to_disburse": 3, "number_of_installments": 4, "monthly_interest_rate": 0.018, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0 }, "collaterals": [ { "collateral_type": "social_security" } ], "refinanced_credit_operations": [ { "operation_key": "324caa35-ba10-4590-ae2b-5efef71709c3" } ] } ``` :::info 上述请求中包含 2 次模拟。第一次固定客户的分期金额（放款金额可变），第二次固定放款金额（分期金额可变）。 ::: ### Response ENDPOINT /debt_simulation MÉTODO POST Response Body ```json { "type": "debt", "key": "8f01672d-9910-43a6-9e7d-07c031bc6fed", "status": "finished", "event_datetime": "2024-11-05 16:50:00", "data": { "interest_type": "pre_price_days", "credit_operation_type": "ccb", "interest_grace_period": 0, "interest_payment_month_period": 1, "principal_grace_period": 0, "principal_amortization_month_period": 1, "operation_type": "structured_operation", "post_fixed_interest_base": "workdays", "post_fixed_interest_rate": null, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 }, "issue_date": "2024-11-05", "number_of_installments": 4, "requester_key": "e5eb6a0a-e003-4cbd-b702-5a25bf71af0a", "final_disbursement_amount": 0.0, "disbursement_options": [ { "iof_amount": 3.93, "total_pre_fixed_amount": 17.8715883143, "cet": 0.0257, "annual_cet": 0.355163, "contract_fees": [ { "fee_type": "tac", "amount_type": "percentage", "amount": 0.6, "fee_amount": 2.29 }, { "fee_type": "ted_fee", "amount_type": "absolute", "amount": 1.0, "fee_amount": 1.0 } ], "external_contract_fees": [ { "fee_type": "spread", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "insurance_premium", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "tac", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null } ], "contract_fee_amount": 2.29, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "disbursement_date": "2024-11-05", "first_due_date": "2024-12-09", "installments": [ { "calendar_days": 34, "workdays": 23.0, "business_due_date": "2024-12-09", "due_date": "2024-12-09", "due_principal": 382.13, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 7.6967422515, "tax_amount": 0.257341482602818, "total_amount": 100, "principal_amortization_amount": 92.3032577485, "installment_number": 1 }, { "calendar_days": 29, "workdays": 19.0, "business_due_date": "2025-01-07", "due_date": "2025-01-07", "due_principal": 289.8267422515, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 4.9718040699, "tax_amount": 0.4909156601748966, "total_amount": 100, "principal_amortization_amount": 95.0281959301, "installment_number": 2 }, { "calendar_days": 31, "workdays": 23.0, "business_due_date": "2025-02-07", "due_date": "2025-02-07", "due_principal": 194.7985463214, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 3.5742034136, "tax_amount": 0.7432500400879712, "total_amount": 100, "principal_amortization_amount": 96.4257965864, "installment_number": 3 }, { "calendar_days": 28, "workdays": 18.0, "business_due_date": "2025-03-07", "due_date": "2025-03-07", "due_principal": 98.372749735, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 1.6288385793, "tax_amount": 0.9841050988526828, "total_amount": 100, "principal_amortization_amount": 98.3711614207, "installment_number": 4 } ], "issue_amount": 382.13, "disbursed_issue_amount": 374.91, "assignment_amount": 382.13, "final_disbursement_amount": 374.91, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 } }, { "iof_amount": 4.77, "total_pre_fixed_amount": 24.2597288075, "cet": 0.0243, "annual_cet": 0.334037, "contract_fees": [ { "fee_type": "tac", "amount_type": "percentage", "amount": 0.6, "fee_amount": 2.25 }, { "fee_type": "ted_fee", "amount_type": "absolute", "amount": 1.0, "fee_amount": 1.0 } ], "external_contract_fees": [ { "fee_type": "spread", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "insurance_premium", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "tac", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null } ], "contract_fee_amount": 2.25, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "disbursement_date": "2024-11-06", "first_due_date": "2025-01-07", "installments": [ { "calendar_days": 62, "workdays": 41.0, "business_due_date": "2025-01-07", "due_date": "2025-01-07", "due_principal": 375.74, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 13.9149280115, "tax_amount": 0.437656505989534, "total_amount": 100, "principal_amortization_amount": 86.0850719885, "installment_number": 1 }, { "calendar_days": 31, "workdays": 23.0, "business_due_date": "2025-02-07", "due_date": "2025-02-07", "due_principal": 289.6549280115, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 5.3146959395, "tax_amount": 0.722070128765373, "total_amount": 100, "principal_amortization_amount": 94.6853040605, "installment_number": 2 }, { "calendar_days": 28, "workdays": 18.0, "business_due_date": "2025-03-07", "due_date": "2025-03-07", "due_principal": 194.969623951, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 3.2283291407, "tax_amount": 0.9601685182659746, "total_amount": 100, "principal_amortization_amount": 96.7716708593, "installment_number": 3 }, { "calendar_days": 31, "workdays": 21.0, "business_due_date": "2025-04-07", "due_date": "2025-04-07", "due_principal": 98.1979530917, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 1.8017757158, "tax_amount": 1.2239426674782687, "total_amount": 100, "principal_amortization_amount": 98.1982242842, "installment_number": 4 } ], "issue_amount": 375.74, "disbursed_issue_amount": 367.72, "assignment_amount": 375.74, "final_disbursement_amount": 367.72, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 } }, { "iof_amount": 4.74, "total_pre_fixed_amount": 24.0392857898, "cet": 0.0243, "annual_cet": 0.334673, "contract_fees": [ { "fee_type": "tac", "amount_type": "percentage", "amount": 0.6, "fee_amount": 2.26 }, { "fee_type": "ted_fee", "amount_type": "absolute", "amount": 1.0, "fee_amount": 1.0 } ], "external_contract_fees": [ { "fee_type": "spread", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "insurance_premium", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "tac", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null } ], "contract_fee_amount": 2.26, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "disbursement_date": "2024-11-07", "first_due_date": "2025-01-07", "installments": [ { "calendar_days": 61, "workdays": 40.0, "business_due_date": "2025-01-07", "due_date": "2025-01-07", "due_principal": 375.96, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 13.6944849939, "tax_amount": 0.4317001860605122, "total_amount": 100, "principal_amortization_amount": 86.3055150061, "installment_number": 1 }, { "calendar_days": 31, "workdays": 23.0, "business_due_date": "2025-02-07", "due_date": "2025-02-07", "due_principal": 289.6544849939, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 5.3146959395, "tax_amount": 0.714305933832412, "total_amount": 100, "principal_amortization_amount": 94.6853040605, "installment_number": 2 }, { "calendar_days": 28, "workdays": 18.0, "business_due_date": "2025-03-07", "due_date": "2025-03-07", "due_principal": 194.9691809334, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 3.2283291407, "tax_amount": 0.952233241255512, "total_amount": 100, "principal_amortization_amount": 96.7716708593, "installment_number": 3 }, { "calendar_days": 31, "workdays": 21.0, "business_due_date": "2025-04-07", "due_date": "2025-04-07", "due_principal": 98.1975100741, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 1.8017757157, "tax_amount": 1.2158904130882027, "total_amount": 100, "principal_amortization_amount": 98.1982242843, "installment_number": 4 } ], "issue_amount": 375.96, "disbursed_issue_amount": 367.96, "assignment_amount": 375.96, "final_disbursement_amount": 367.96, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 } }, { "iof_amount": 4.71, "total_pre_fixed_amount": 23.8187134405, "cet": 0.0244, "annual_cet": 0.335196, "contract_fees": [ { "fee_type": "tac", "amount_type": "percentage", "amount": 0.6, "fee_amount": 2.26 }, { "fee_type": "ted_fee", "amount_type": "absolute", "amount": 1.0, "fee_amount": 1.0 } ], "external_contract_fees": [ { "fee_type": "spread", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "insurance_premium", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "tac", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null } ], "contract_fee_amount": 2.26, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "disbursement_date": "2024-11-08", "first_due_date": "2025-01-07", "installments": [ { "calendar_days": 60, "workdays": 39.0, "business_due_date": "2025-01-07", "due_date": "2025-01-07", "due_principal": 376.18, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 13.4739126445, "tax_amount": 0.42570834978906, "total_amount": 100, "principal_amortization_amount": 86.5260873555, "installment_number": 1 }, { "calendar_days": 31, "workdays": 23.0, "business_due_date": "2025-02-07", "due_date": "2025-02-07", "due_principal": 289.6539126445, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 5.3146959395, "tax_amount": 0.706541738899451, "total_amount": 100, "principal_amortization_amount": 94.6853040605, "installment_number": 2 }, { "calendar_days": 28, "workdays": 18.0, "business_due_date": "2025-03-07", "due_date": "2025-03-07", "due_principal": 194.968608584, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 3.2283291407, "tax_amount": 0.9442979642450494, "total_amount": 100, "principal_amortization_amount": 96.7716708593, "installment_number": 3 }, { "calendar_days": 31, "workdays": 21.0, "business_due_date": "2025-04-07", "due_date": "2025-04-07", "due_principal": 98.1969377247, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 1.8017757158, "tax_amount": 1.20783815869566, "total_amount": 100, "principal_amortization_amount": 98.1982242842, "installment_number": 4 } ], "issue_amount": 376.18, "disbursed_issue_amount": 368.21, "assignment_amount": 376.18, "final_disbursement_amount": 368.21, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 } } ] } } ``` --- ## 4 - 发行操作： :::caution 注意 对于自福利发放日起未满 90 天且不允许批注的操作，需确保 disbursement_date 与 limit_days_to_disburse 之和所得日期晚于 90 天之后。 如果不满足此规则，操作将被永久取消，CancelReason 为：social_security_margin_release_after_disbursement_end_date。 ::: "collateral_data" 对象中的 "assistance_type" 字段指贷款所使用的福利类型，该值在福利数据查询中返回。查看可能的值（枚举值），请参阅[枚举值表](#benefit_type_enumerator)。 :::warning 注意 `credit_agent` 对象代表信贷代理人，有时称为推销员，负责发起此债务。此字段在发行代扣贷款债务时为必填项。 ::: ### Request 情形 1：无法定代表人的发行 ENDPOINT /debt MÉTODO POST 在 Playground 中测试 **新增信贷** ```json title='Request Body' { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "financial": { "interest_type": "pre_price_days", "first_due_date": "2023-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.0166, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 101.84, "limit_days_to_disburse": 7, "number_of_installments": 10, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644799" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ] } ``` **再融资** ```json title='Request Body' { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ], "refinanced_credit_operations": [ { "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b" } ] } ``` **新增信贷 - 薪资增长** ```json title='Request Body' { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "operation_category": "minimum_wage_increase", "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ] } ``` 情形 2：有法定代表人的发行 ENDPOINT /debt MÉTODO POST **新增信贷** ```json { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "related_parties": [ { "name": "Representante legal", "email": "teste@qitech.com.br", "phone": { "number": "991294043", "area_code": "55", "country_code": "055" }, "address": { "street": "AV LEONOR", "state": "SP", "city": "GUARULHOS", "neighborhood": "", "number": "1", "postal_code": "07025200", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "is_pep": false, "individual_document_number": "19125869086", "birth_date": "1970-04-20", "mother_name": " Ana Lúcia" } ], "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ] } ``` **再融资** ```json { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "related_parties": [ { "name": "Representante legal", "email": "teste@qitech.com.br", "phone": { "number": "991294043", "area_code": "55", "country_code": "055" }, "address": { "street": "AV LEONOR", "state": "SP", "city": "GUARULHOS", "neighborhood": "", "number": "1", "postal_code": "07025200", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "is_pep": false, "individual_document_number": "19125869086", "birth_date": "1970-04-20", "mother_name": " Ana Lúcia" } ], "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ], "refinanced_credit_operations": [ { "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b" } ] } ``` **新增信贷 - 薪资增长** ```json { "borrower": { "name": "Nome devedor", "phone": { "number": "999538380", "area_code": "84", "country_code": "055" }, "gender": "female", "is_pep": false, "address": { "city": "Natal", "state": "RN", "number": "1984", "street": "Rua", "complement": "complemento", "postal_code": "59065720", "neighborhood": "bairro" }, "role_type": "issuer", "birth_date": "1959-07-08", "mother_name": "NOME DA MAE", "nationality": "Brasileiro", "person_type": "natural", "marital_status": "single", "attached_documents_list": [], "individual_document_number": "14471835092", "document_identification_date": "2015-10-02", "document_identification_type": "rg", "document_identification_number": "003709888" }, "related_parties": [ { "name": "Representante legal", "email": "teste@qitech.com.br", "phone": { "number": "991294043", "area_code": "55", "country_code": "055" }, "address": { "street": "AV LEONOR", "state": "SP", "city": "GUARULHOS", "neighborhood": "", "number": "1", "postal_code": "07025200", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "is_pep": false, "individual_document_number": "19125869086", "birth_date": "1970-04-20", "mother_name": " Ana Lúcia" } ], "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-09-20", "disbursement_date": "2024-11-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "monthly_interest_rate": 0.0166, "installment_face_value": 1000, "limit_days_to_disburse": 7, "number_of_installments": 84, "principal_grace_period": 0 }, "simplified": true, "collaterals": [ { "percentage": 1, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "operation_category": "minimum_wage_increase", "subcorban_document_number": "12123456000101" }, "collateral_type": "social_security" } ], "additional_data": { "contract": { "contract_number": "TST0000644715" } }, "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "disbursement_bank_accounts": [ { "name": "NOME DEVEDOR", "bank_code": "001", "account_digit": "0", "branch_number": "2874", "account_number": "000057555", "document_number": "14471835092", "transfer_method": "pix", "percentage_receivable": 100 } ], "refinanced_credit_operations": [ { "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b" } ] } ``` 含折扣的 financial 对象示例 ```json { "financial": { "first_due_date": "2022-12-07", "installment_face_value": 100, "disbursement_date": "2022-11-03", "limit_days_to_disburse": 3, "number_of_installments": 24, "disbursed_amount": 1876, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0, "rebates": [ { "amount": 20, "rebate_bank_account": { "name": "Teste Ltda", "document_number": "18533555000164", "account_digit": "0", "account_number": "4290001", "branch_number": "0001", "bank_code": "329" }, "amount_type": "percentage", "fee_type": "spread" } ] } } ``` ### Response ENDPOINT /debt MÉTODO POST Response Body ```json { "webhook_type": "debt", "key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00", "status": "waiting_signature", "event_datetime": "2024-11-07 23:19:22", "data": { "borrower": { "name": "Nome devedor", "document_number": "14471835092", "related_party_key": "28b7fc16-6d1f-467d-9667-62a8c13daea6" }, "contract": { "number": "TST0000644710", "urls": [ "https://storage.googleapis.com/sandbox-doc-api/documents/a2e9c83a-3666-4def-8b27-e96fabb8705c/NOME_DEVEDOR-CCB-TST0000644710-20241107231916.pdf" ], "signature_information": [ { "signer_name": "Nome devedor", "signer_document_number": "14471835092", "signer_role": "issuer", "signer_email": null, "signer_external_key": null, "signature_url": null } ] }, "requester_identifier_key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00", "iof_charge_method": "financed", "collaterals": [ { "absolute_amount": null, "collateral_constituted": false, "collateral_data": { "state": "SP", "benefit_number": 2052711150, "reservation_method": "issuing", "subcorban_document_number": "12123456000101" }, "collateral_key": "26c7f4f4-51f3-41fa-b880-9691211136aa", "collateral_type": "social_security", "created_at": "2024-11-07T23:19:16.413448", "external_key": null, "percentage": 1, "reservation_method": { "enumerator": "issuing" }, "updated_at": "2024-11-07T23:19:16.413441" } ], "disbursement_options": [ { "disbursement_date": "2024-11-07", "contract_fees": [ { "fee_type": "spread", "fee_amount": 4.55 }, { "fee_type": "ted_fee", "fee_amount": 1.5 } ], "external_contract_fees": [ { "fee_type": "spread", "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0 } ], "contract_fee_amount": 6.05, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "assignment_amount": 914.3, "issue_amount": 909.75, "cet": "2,0100%", "annual_cet": "27,0481%", "base_iof": 16.259002146803677, "additional_iof": 3.45705, "total_iof": 19.72, "total_pre_fixed_amount": 108.6508885851, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 74, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 909.75, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 37.1789024864, "principal_amortization_amount": 64.6610975136, "tax_amount": 0.3923635397125248, "total_amount": 101.84, "workdays": 49.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-02-20", "calendar_days": 31, "due_date": "2025-02-20", "due_interest": 0.0, "due_principal": 845.0889024864, "fine_amount": null, "has_interest": true, "installment_number": 2, "post_fixed_amount": null, "pre_fixed_amount": 14.2997636051, "principal_amortization_amount": 87.5402363949, "tax_amount": 0.753721435360089, "total_amount": 101.84, "workdays": 23.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-03-20", "calendar_days": 28, "due_date": "2025-03-20", "due_interest": 0.0, "due_principal": 757.5486660915, "fine_amount": null, "has_interest": true, "installment_number": 3, "post_fixed_amount": null, "pre_fixed_amount": 11.5685715131, "principal_amortization_amount": 90.2714284869, "tax_amount": 0.9845001990781314, "total_amount": 101.84, "workdays": 18.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-04-22", "calendar_days": 33, "due_date": "2025-04-22", "due_interest": 0.0, "due_principal": 667.2772376046, "fine_amount": null, "has_interest": true, "installment_number": 4, "post_fixed_amount": null, "pre_fixed_amount": 12.025984633, "principal_amortization_amount": 89.814015367, "tax_amount": 1.222548377175604, "total_amount": 101.84, "workdays": 21.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-05-20", "calendar_days": 28, "due_date": "2025-05-20", "due_interest": 0.0, "due_principal": 577.4632222376, "fine_amount": null, "has_interest": true, "installment_number": 5, "post_fixed_amount": null, "pre_fixed_amount": 8.8184725787, "principal_amortization_amount": 93.0215274213, "tax_amount": 1.4797864582180404, "total_amount": 101.84, "workdays": 19.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-06-20", "calendar_days": 31, "due_date": "2025-06-20", "due_interest": 0.0, "due_principal": 484.4416948163, "fine_amount": null, "has_interest": true, "installment_number": 6, "post_fixed_amount": null, "pre_fixed_amount": 8.1972396908, "principal_amortization_amount": 93.6427603092, "tax_amount": 1.72770892770474, "total_amount": 101.84, "workdays": 22.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-07-21", "calendar_days": 31, "due_date": "2025-07-21", "due_interest": 0.0, "due_principal": 390.7989345071, "fine_amount": null, "has_interest": true, "installment_number": 7, "post_fixed_amount": null, "pre_fixed_amount": 6.6127072945, "principal_amortization_amount": 95.2272927055, "tax_amount": 1.999011328473856, "total_amount": 101.84, "workdays": 21.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-08-20", "calendar_days": 30, "due_date": "2025-08-20", "due_interest": 0.0, "due_principal": 295.5716418016, "fine_amount": null, "has_interest": true, "installment_number": 8, "post_fixed_amount": null, "pre_fixed_amount": 4.8387153664, "principal_amortization_amount": 97.0012846336, "tax_amount": 2.274874127227187, "total_amount": 101.84, "workdays": 22.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-09-22", "calendar_days": 33, "due_date": "2025-09-22", "due_interest": 0.0, "due_principal": 198.570357168, "fine_amount": null, "has_interest": true, "installment_number": 9, "post_fixed_amount": null, "pre_fixed_amount": 3.5787172455, "principal_amortization_amount": 98.2612827545, "tax_amount": 2.570318634292211, "total_amount": 101.84, "workdays": 23.0, "installment_status": null, "installment_type": null }, { "additional_costs": [], "business_due_date": "2025-10-20", "calendar_days": 28, "due_date": "2025-10-20", "due_interest": 0.0, "due_principal": 100.3090744135, "fine_amount": null, "has_interest": true, "installment_number": 10, "post_fixed_amount": null, "pre_fixed_amount": 1.5318141716, "principal_amortization_amount": 100.3081858284, "tax_amount": 2.8541691195612935, "total_amount": 101.84, "workdays": 20.0, "installment_status": null, "installment_type": null } ], "first_due_date": "2025-01-20", "prefixed_interest_rate": { "monthly_rate": 0.0166, "daily_rate": 0.00054142, "annual_rate": 0.21843191, "interest_base": "calendar_days_365" } } ] } } ``` 如果操作在最后一个放款日期选项前未签署或批注，合作方将收到有关操作取消的 webhook： WEBHOOK_TYPE debt STATUS Canceled **Webhook Body** ```json { "key": "\", "data": { "cancel_reason": "Operacao cancelada manualmente", "cancel_reason_enumerator": "manual" }, "status": "canceled", "webhook_type": "debt", "event_datetime": "2022-11-01 03:46:31" } ``` ### 在 Sandbox 中模拟批注成功与失败场景： 场景模拟基于操作中提供的 CPF 的第一位数字。 **11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。 **11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字，按照下表返回异步错误响应。 **11.3.** 操作为 "cancel" 的错误将收到包含操作最终结果的 webhook。 | CPF 首位数字 | 枚举值 | 描述 | 操作 | |--------------|------------------------------|-----------------------------------------------------------------------------------|--------| | 2 | invalid_disbursement_account | Invalid disbursemente bank account | cancel | | 3 | operation_not_allowed_IR | Operation not allowed due to operation deadline greatter than benefit termination | cancel | :::caution 注意 所有第一位数字未映射到对应场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。 | 枚举值 | 描述 | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: ## 5 - 文件提交 必须提交合同补充数据（根据 INSS 第 138 号规范性指令）。 文件应通过[文件上传端点](../upload_de_documentos)提交，并遵循以下格式规范： | 验证项 | 值 | |--------------|--------------| | 格式 | JPEG | | 最小尺寸 | 250 x 250 px | | 最大尺寸 | 2 MB | :::caution 注意 不符合最小或最大尺寸规定的关联文件的合同将被永久取消。 ::: 文件上传后，必须在操作创建的 payload 中或之后通过以下端点提供已提交文件的密钥： ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY /attached_document MÉTODO POST 在 Playground 中测试 Request Body ```json { "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41", "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431", "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c" } ``` :::info 信息 **related_party_key** 在债务创建的响应中，位于 **borrower** 对象内返回。 ::: ## 6 - 操作正式化 文件提交后，操作可以进行正式化。 若由法定代表人签署，在 "**data.contract.signers[i]**" 字段中将返回法定代表人的数据，且 "**data.contract.signers[i].signer_role**" 对象的值将为 "**issuer_legal_representative**"。 **签署 payload 中必须包含与第 5 条中提交文件相关的必填字段。必填字段如下：_ip_address_ 和 _signature_datetime_。** ### Request ENDPOINT /debt/ DEBT-KEY /signed MÉTODO POST 在 Playground 中测试 Request Body ```json { ..., "ip_address": "192.168.0.0", "signature_datetime": "2020-03-20T14:28:23.382748Z", "similarity_score": 0.98000, "biometry_analysis_reference": "serpro", "type": "data-signature" } ``` :::caution 注意 签署提交的 payload 因合作方的正式化流程而异，需与 QI Tech 集成团队对接确认。 ::: #### _Biometry Analysis Reference_ 枚举值 | 枚举值 | 描述 | |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **serpro** | 当 similarity_score 通过查询 Detran 带照片文件库（通过 Serpro 提供的服务）获得时使用 | | **tse** | 当 similarity_score 通过查询 TSE 带照片文件库获得时使用 | | **not_found** | 当面部生物识别在上述任何政府数据库（serpro 或 tse）中均未找到时填写。此时 similarity_score 应为 null 或合作方返回的自拍与带照片官方文件的相似度评分。 | :::danger QI Sign QI Tech 提供符合第 138 号规范性指令规定的签署服务，包含面部生物识别和文件提交。 如需报价，请联系我们的商务团队： comercial@qitech.com.br 或 (11) 2339-4763 ::: ### Response ENDPOINT /debt/ DEBT-KEY /signed MÉTODO POST Response Body ```json { "data": {}, "event_datetime": "2022-11-07 15:24:47", "key": "\", "status": "signature_received", "webhook_type": "debt" } ``` 收到签署后，将对已提交文件和 assistance_type 字段进行验证。 如果提交了未映射的福利类型 [(assistance_type)](#benefit_type_enumerator)，操作将被永久取消。 文件验证同样适用，如存在重复、缺失或不符合最低标准的文件，操作也将被永久取消。 在这两种情况下，都会发送包含以下 payload 的 webhook： WEBHOOK_TYPE debt STATUS Canceled Permanently Webhook Body ```json { "key": "", "data": {}, "status": "canceled_permanently", "webhook_type": "debt", "event_datetime": "2022-11-01 03:46:31" } ``` ## 7 - 批注与取消批注 :::caution 注意 要成功创建批注请求，需要**事先**对福利进行有效的数据查询。 为此，只需按照第 [2 - 查询福利数据](#consulta-de-dados) 条的步骤操作即可。 ::: ### 因超出额度导致批注失败 如果新受益人类别或薪资增长类别的预留在批注尝试时收到超额响应，批注请求的状态将变为"等待合作方操作"，并将以以下格式发送 webhook 以通知相关情况： WEBHOOK_TYPE social_security_margin_exceeded_for_new_beneficiary 或 social_security_margin_exceeded_for_minimum_wage_increase STATUS Pending requester action Webhook Body **新受益人** ```json { "webhook": { "key": "\", "data": { "enumerator": "margin_exceeded_for_new_beneficiary", "description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18", }, "status": "pending_requester_action", "webhook_type": "social_security_margin_exceeded_for_new_beneficiary", "event_datetime": "2024-10-15T15:33:59" } } ``` **薪资增长** ```json { "webhook": { "key": "\", "data": { "enumerator": "margin_exceeded_for_minimum_wage_increase", "description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18", }, "status": "pending_requester_action", "webhook_type": "social_security_margin_exceeded_for_minimum_wage_increase", "event_datetime": "2024-10-15T15:33:59" } } ``` ### 因缺少有效福利数据查询导致批注失败 如果在批注请求之前未成功完成福利数据查询，批注请求的状态将变为"等待合作方操作"，并将以以下格式发送 webhook 以通知相关情况： WEBHOOK_TYPE social_security_success_balance_request_not_found STATUS Pending requester action Webhook Body ```json { "webhook": { "key": "\", "data": { "enumerator": "success_balance_request_not_found", "description": "Success balance request not found for the specified benefit number" }, "status": "pending_requester_action", "webhook_type": "social_security_success_balance_request_not_found", "event_datetime": "2024-10-15T15:33:59" } } ``` 如需继续，应采取以下操作： 1. 按照第 2 条 - [查询福利数据](#consulta-de-dados) 的步骤查询相关福利数据； 2. 按以下格式发送请求，告知查询已完成。 ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /validate_reservation MÉTODO POST 在 Playground 中测试 :::info 重要 此请求不仅确认存在有效的福利数据查询，还会验证创建批注所发送的信息是否正确，从而允许流程继续进行。 ::: ### 请求优先级系统（插队） 由于 Dataprev 的限制，每秒最多允许 **25 个请求**，请求系统以异步方式运行，即批注尝试被组织到队列中进行处理。因此，请求将根据操作类型和成功概率进行优先排序。 在这种情况下，为了避免在批注成功概率高但下次批注尝试还需等待较长时间的情况下损失额度，开发了此系统，允许以同步方式（即无需等待队列）发出请求。 然而，为确保适当控制并防止该系统被滥用，实施了**令牌桶**机制，工作原理如下： - 每个请求消耗一个令牌； - 如果请求产生成功的批注，令牌将归还桶中； - 否则，令牌将被消耗； - 每个桶有最大令牌数量限制； - 定期启动令牌补充例程，将已消耗的令牌补充至最大限制； - 如果令牌耗尽，在例程补充新令牌之前将无法发出新请求。 令牌桶系统示例 在此示例中，桶的配置为： - **最大令牌数：** 10 - **补充时间：** 30分钟 **第 0 小时：** 桶以最大容量创建； **第 9 分钟：** 发出一个请求，但合同未批注（错误），导致消耗 1 个令牌； **第 17 分钟：** 发出一个请求，合同批注成功（成功），令牌数量不变； **第 30 分钟：** 第一次令牌补充，桶恢复至最大容量； **第 47 分钟：** 成功发出 10 个请求，无令牌消耗； **第 1 小时：** 第二次令牌补充，但由于桶已满，令牌数量保持不变； **第 1:12 小时：** 5 个请求出错，消耗 5 个令牌； **第 1:30 小时：** 第三次令牌补充，桶有 6 个令牌； **第 1:38 小时：** 6 个请求出错，耗尽所有令牌； **第 1:51 小时：** 尝试发出请求，但由于桶中没有令牌，请求被阻止； **第 2 小时：** 第四次令牌补充，桶有 1 个令牌，允许新的请求尝试； 要发出优先请求，只需使用与要批注的操作对应的 DEBT-KEY 调用以下端点： #### Request ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /priority_request MÉTODO POST 在 Playground 中测试 #### Response Response Body - 成功 ```json { "max_bucket_capacity": 10, "bucket_fill_rate_minutes": 30, "available_tokens": 7, "status": "pending_document_submission", "next_refill_at": "2025-02-04T20:28:35Z" } ``` Response Body - 错误 ```json 批注错误： { "title": "Reservation Failed", "description": "Last Response: consignable_margin_excceded, Tokens Available: 9, Next Refill At: 2025-02-04T20:18:35Z", "translation": "Ultima resposta: consignable_margin_excceded, Fichas disponiveis: 9, Proxima Recarga: 2025-02-04T20:18:35Z", "extra_fields": {}, "code": "SSC000083" } 无可用令牌错误： { "title": "Rate limit exceeded", "description": "Request limit exceeded. No tokens available, next refill in 8 minutes.", "translation": "Limite de solicitacoes excedido. Nenhuma ficha disponivel, proxima recarga em 8 minutos.", "extra_fields": {}, "code": "SSC000080" } ``` 最后，可以在无需向优先端点发出请求的情况下查询桶的当前配置。为此，我们提供了以下查询端点： #### Request ENDPOINT /social_security/bucket_configuration MÉTODO GET 在 Playground 中测试 #### Response Response Body ```json { "max_bucket_capacity": 10, "bucket_fill_rate_minutes": 30, "available_tokens": 7, "next_refill_at": "2025-02-04T20:08:35Z" } ``` ### 批注成功 批注成功时，合作方将收到以下 webhook： WEBHOOK_TYPE credit_operation.collateral STATUS Success Webhook Body ```json { "key": "\", "data": { "collateral_type": "social_security", "collateral_constituted": true }, "event_time": "2022-10-31 15:23:46", "webhook_type": "credit_operation.collateral" } ``` ### 批注失败时更正数据 可以在批注尝试中更正银行数据、福利编号和合同名称。只需使用以下调用： ENDPOINT /debt/ DEBT-KEY /collateral MÉTODO PATCH 在 Playground 中测试 Request Body **银行数据** ```json { "disbursement_bank_account": { "bank_code": "123", "account_digit": "1", "account_branch": "1234", "account_number": "5678", "document_number": "12345678901" } } ``` **福利编号** ```json { "benefit_number": 1234567890 } ``` **姓名** ```json { "name": "Nome do Beneficiário" } ``` ### 取消批注 合同的取消批注通过永久取消路由执行。该路由为合同设置最终状态，不可重试，并触发已批注额度的取消批注。 要执行永久取消，应使用以下端点： ENDPOINT /debt/ DEBT-KEY /cancel_permanently MÉTODO POST 在 Playground 中测试 #### Webhooks WEBHOOK_TYPE debt STATUS canceled_permanently Webhook Body ```json { "key": "\", "data": {}, "status": "canceled_permanently", "webhook_type": "debt", "event_datetime": "2022-11-01 03:46:31" } ``` ## 8 - 放款失败 ### TED TED 放款失败时 WEBHOOK_TYPE debt STATUS canceled Webhook Body ```json { "status": "canceled", "key": "\", "data": { "ted_refusal": { "transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9", "description": "341 0000 000000-7 12345678900 - NOME BENEFICIÁRIO", "origin": { "account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0", "account_number": "00086", "bank_code": "329", "name": "ACCOUNT TRANSITORY", "type": "payment_account", "document": "32402502000135", "branch_digit": null, "account_digit": "8", "branch": "0001" }, "fee": 0, "reason_enumerator": "agencia_conta_invalida", "timestamp": "2022-11-07T14:36:05", "amount": 483.6, "reason": "Agência ou Conta Destinatária do Crédito Inválida", "destination": { "branch": "0000", "account_number": "000000", "name": "NOME BENEFICIÁRIO", "purpose": "Crédito em Conta", "type": "checking_account", "branch_digit": null, "document": "12345678900", "bank_code": "341", "account_digit": "7" } }, "cancel_reason": "ted_refusal" } } ``` ### Pix PIX 放款失败时 WEBHOOK_TYPE debt STATUS canceled Webhook Body ```json { "webhook_type": "debt", "data": { "pix_refusal": { "reason": "Número da conta de destino é inexistente ou inválido.", "reason_enumerator": "invalid_account", "cancel_reason_enumerator": "invalid_account" }, "cancel_reason": "pix_refusal", "cancel_reason_enumerator": "pix_refusal" }, "status": "canceled", "key": "\", "event_datetime": "2025-09-04 15:29:37" } ``` ## 9 - 重新呈现付款 更改放款日期而不影响操作的财务金额。 ### Request ENDPOINT /debt/ DEBT-KEY /change_disbursement_date MÉTODO POST 在 Playground 中测试 Request Body ```json { "disbursement_date": "2022-11-04", "disbursement_bank_accounts": [ { "branch_number": "1232", "account_digit": "4", "account_number": "412412412", "account_type": "checking_account", "document_number": "14950479032", "bank_code": 184, "ispb_number": "17298092", "name": "Maria da Silva", "percentage_receivable": 100 } ] } ``` ### Response ENDPOINT /debt/ DEBT-KEY /change_disbursement_date MÉTODO POST Response Body ```json { "disbursement_accounts": [ { "account_branch": "1232", "account_digit": "4", "account_number": "412412412", "account_type": "checking_account", "amount_receivable": null, "created_at": "2022-05-24T14:51:46", "digitable_line": null, "disbursement_type": "ted", "document_number": "37197645832", "financial_institutions": { "code_number": 184, "ispb": 17298092, "name": "BCO ITAÚ BBA S.A." }, "financial_institutions_code_number": 184, "is_pix_disbursement": false, "ispb": "17298092", "name": "Márcio e Catarina Gráfica Ltda", "percentage_receivable": 50.0, "pix_key": null, "pix_transfer_key": null, "pix_type": null, "qr_code_key": null, "retry_counter": 0, "retry_vector": null, "transaction_key": null, "webhook_key": null } ], "disbursement_date": "2022-11-04" } ``` --- ![Competence Diagram](@site/static/img/imagem_manual_credito_novo_inss.webp) ## 10 - 获取最后一次请求的响应 last response 是一种简单、客观地映射 QI 与 Dataprev 之间通信响应的方式，可以知道此次请求的时间及获得的返回值（通过枚举值）。枚举值与 Dataprev 的返回代码直接相关，分为两种形式："errors"（错误）和 "success"（成功）。 每个枚举值都有详细描述和 Dataprev 的参考代码。我们可以在下面更详细地了解 last response 数据的呈现方式。 ### 成功情形 #### Request ENDPOINT /debt/DEBT-KEY/collateral MÉTODO GET 在 Playground 中测试 #### Response Response Body ```json { "collateral_constituted": true, "collateral_type": "type", "updated_at": "2023-05-24 19:13:02", "collateral_data": { "state": "SP", "benefit_number": 1976703155, "status": "reserved", "last_response": { "success": [ { "enumerator": "succesfully_included", "reservation_method" : "new_credit" } ] }, "last_response_event_datetime": "2023-05-22T19:13:02Z" } } ``` ### 请求返回字段详解 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|------------------------------------------| | enumerator | Dataprev 代码的映射返回值 | [枚举值](#dataprev_response_enumerator_success)| | reservation_method | 预留批注方式 | portability, new_credit, refinancing| ### 错误情形 #### Request ENDPOINT /debt/DEBT-KEY/collateral MÉTODO GET #### Response Response Body ```json { "collateral_constituted": false, "collateral_type": "type", "updated_at": "2023-05-24 19:13:02", "collateral_data": { "state": "SP", "benefit_number": 1976703155, "status": "pending_reservation", "last_response": { "errors": [ { "enumerator": "benefit_blocked_by_tbm", "reservation_method" : "new_credit" } ] }, "last_response_event_datetime": "2023-05-22T19:13:02Z" } } ``` ### 请求返回字段详解 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|------------------------------------------| | enumerator | Dataprev 代码的映射返回值 | [枚举值](#dataprev_response_enumerator_errors)| | reservation_method | 预留批注方式 | portability, new_credit, refinancing| ## 11 - 获取最后一次福利查询 通过此端点可以查询最后一次在 Dataprev 查询福利的时间。 #### Request ENDPOINT /social_security/benefit/BENEFIT-NUMBER MÉTODO GET 在 Playground 中测试 #### Response Response Body ```json { "last_balance_check": "2025-08-22T19:13:02Z", "status": "pending_balance_request" } ``` ## 12 - 最后一次批注尝试的响应 webhook 如果操作批注未成功，将进行重试，并发送以下 webhook，详述批注失败原因、此次尝试的时间及使用的批注方式： WEBHOOK_TYPE credit_operation.collateral *Body:* **body.json** ```json { "webhook_type": "credit_operation.collateral", "key": "\", "event_time": "2022-11-24T15:42:12", "data": { "collateral_type": "social_security", "collateral_constituted": false, "collateral_data": { "status": "pending_reservation", "last_response": { "errors": [{ "enumerator": "consignable_margin_excceded" }] }, "last_response_event_datetime": "2023-05-22T19:13:02Z", "reservation_method": "new_credit", } } } ``` ## 13. 枚举值映射 ### Dataprev 批注错误返回表 {#dataprev_response_enumerator_errors} | Dataprev 代码 | 枚举值 | 描述 | QI 操作 | |---------------|--------------------------------------------------|-------------------------------------------------------------|----------------------| | HW | consignable_margin_excceded | Exceeded consignable margin | Teimosinha | | IT | benefit_blocked_by_tbm | Benefit blocked due to benefit transfer | Teimosinha | | IE | benefit_blocked_by_beneficiary | Benefit blocked by beneficiary | Teimosinha | | AN | invalid_disbursement_account | Invalid disbursement bank account | 取消 | | HX | reservation_already_included | Reservation already included | 确认批注 | | IF | benefit_blocked_by_granting_process | Benefit blocked during granting process | Teimosinha | | AV | processing_payroll | Operation couldn`t be done during processing payroll period | Teimosinha | | OF | invalid_cbc | Invalid cbc | Teimosinha | | IA | first_name_mismatch | First name mismatch benefit owner or legal representative | Teimosinha | | OS | legal_representative_document_number_mismatch | Document number mismatch legal representative | Teimosinha | | AY | invalid_state | Invalid state | Teimosinha | | HZ | operation_not_allowed_on_this_reservation_status | Operation couldn`t be done with current reservation status | Teimosinha | | AP | invalid_contract_date | Accrual, end or start contract date is invalid | Teimosinha | | GA | required_fields_missing | Required fields are missing | Teimosinha | | BC | cbc_missing | CBC is missing | Teimosinha | | NC | contract_number_missing | Contract number is missing | Teimosinha | | NB | benefit_number_missing | Benefit number is missing | Teimosinha | | CA | invalid_bank_code | Invalid bank code | Teimosinha | | HR | exceeded_number_of_allowed_contracts | Amount of contracts is above the limit | Teimosinha | | PV | invalid_image_format | Image with wrong format | Teimosinha | | IR | operation_not_allowed_IR | Operation date is greater than benefit expiration | 取消 | | PK | wrong_bank_code_destination | Portability number was found with wrong bank code destination| Teimosinha | | PH | wrong_benefit_number_on_portability | Portability number was found with wrong benefit number | Teimosinha | | PI | invalid_contract_total_amount | Reservation contract total amount should be greater than Dataprev reference amount | Teimosinha | ### 批注成功返回表 {#dataprev_response_enumerator_success} | Dataprev 代码 | 枚举值 | 描述 | |--------|--------------------------|-----------------------------------------| | BD | successfully_included | Inclusion has been successfully done | | BF | successfully_removed | Removal has been successfully done | | BR | successfully_reactivated | Reactivation has been successfully done | | BS | successfully_suspended | Suspension has been successfully done | ### 余额查询错误返回表 {#dataprev_balance_errors_enumerators} | 代码 | 枚举值 | 描述 | |--------|---------------------------------------|---------------------------------------------------------------------------------| | CR | not_found_legal_representative | no legal representative for the beneficiary | | CD | inexistent_beneficiary | no beneficiary found | | AS | benefity_without_legal_representative | beneficiary does not have a legal representative | | BI | inexistent_benefit | no benefit found | | D1 | inconsistent_balance_benefit_data | The balance benefit data registered is either inconsistent, null or incomplete. | ### 福利查询错误返回表 {#dataprev_benefits_errors_enumerators} | 代码 | 枚举值 | 描述 | |--------|---------------------------------------|---------------------------------------------------------------------------------| | CR | not_found_legal_representative | no legal representative for the beneficiary | | CD | inexistent_beneficiary | no beneficiary found | | AS | benefity_without_legal_representative | beneficiary does not have a legal representative | ### 福利状况表 {#benefit_situation_enumerator} | 项目 | |-------| | active | | excluded | | terminated | | suspended | | suspended_by_CONPAG | | terminated_by_SISOBI | | receiving_monthly_recover_6_months | | receiving_monthly_recover_18_months | | suspended_by_name_error | | suspended_by_credentialed_payer | | suspended_by_inspection | | suspended_by_audit | | terminated_by_inspection | | terminated_by_audit | | receiving_monthly_recover_6_months_inspection | | receiving_monthly_recover_18_months_inspection | | suspended_by_SISOBI | | canceled_by_audit | ### 福利状态表 {#benefit_status_enumerator} | 枚举值 | 描述 | |------------|-----------------------------------------------------| | Elegible | 有资格申请贷款 | | Inelegible | 福利不符合贷款资格 | | Blocked | 福利符合资格，但被锁定无法申请贷款 | ### 锁定类型表 {#block_type_enumerator} | 枚举值 | 描述 | |-------------------------|-----------------------------------------------------| | not_blocked | 无锁定 | | blocked_by_benefitiary | 被受益人锁定 | | blocked_by_tbm | 因 TBM 锁定 | | blocked_in_concession | 在授予过程中锁定 | ### 政治敏感人士类型表 {#politically_exposed_enumerator} | 枚举值 | 描述 | |--------|-----------------------------------------------------| | 0 | 非政治敏感人士 | | 1 | 政治敏感人士 - 第 1 级 | ### 福利类型表 {#benefit_type_enumerator} | 代码 | 福利 | | --- | ------------------------------------------------ | | 1 | pension_by_death_rural_worker | | 2 | pension_by_death_accident_rural_worker | | 3 | pension_by_death_rural_employer | | 4 | retirement_invalidity_rural_emploee | | 5 | retirement_invalidity_accident_rural_worker | | 6 | retirement_invalidity_rural_employer | | 7 | retirement_by_eldness_rural_worker | | 8 | retirement_by_age_rural_employer | | 9 | complement_by_work_accident_rural_worker | | 11 | support_invalidity_rural_worker | | 12 | support_by_age_rural_worker | | 13 | aid_sickness_rural_worker | | 15 | aid_time_off_rural_worker | | 16 | aid_federal | | 17 | international_agreement | | 18 | inclusion_benefit | | 19 | pension_student_law7004 | | 20 | pension_by_death_diplomat | | 21 | pension_by_death | | 22 | pension_by_death_statute | | 23 | pension_by_death_veteran | | 24 | pension_special_institutional_act | | 25 | aid_time_off | | 26 | pension_by_death_special_law593 | | 27 | pension_by_death_federal_emploee | | 28 | pension_by_death_general_regime_law20465 | | 29 | pension_by_death_marine_veteran | | 30 | monthly_income_lifetime_invalidity | | 31 | aid_sickness | | 32 | retirement_invalidity_social_security | | 33 | retirement_invalidity_aeronautic | | 34 | retirement_invalidity_marine_law1756 | | 35 | aid_sickness_veteran | | 36 | aid_social_security_accident | | 37 | retirement_capin_extra_emploee | | 38 | retirement_federal_extra_emploee | | 39 | aid_invalidity_student_law7004 | | 40 | monthly_income_lifetime_by_age_upper70_law6179 | | 41 | retirement_by_age | | 42 | retirement_by_contribution_time | | 43 | retirement_by_time_of_service_veteran | | 44 | retirement_special_aeronautic | | 45 | retirement_by_time_of_service_journalist | | 46 | retirement_special | | 47 | allowance_25 | | 48 | allowance_20 | | 49 | retirement_ordinary | | 50 | aid_sickness_extinct_basic_plan | | 51 | retirement_invalidity_extinct_basic_plan | | 52 | retirement_by_age_extinct_basic_plan | | 53 | aid_time_off_extinct_basic_plan | | 54 | pension_indemnity_federal | | 55 | pension_by_death_extinct_basic_plan | | 56 | pension_lifetime_syndrome_thalidomide | | 57 | retirement_by_teacher_labor_time | | 58 | retirement_anisty | | 59 | pension_by_death_amnesty | | 60 | indemnity | | 61 | aid_birth | | 62 | aid_funeral | | 63 | aid_funeral_rural_worker | | 64 | aid_funeral_rural_employer | | 65 | savings_special_autarchy | | 67 | savings_mandatory_ipase_law5128 | | 68 | savings_special_retirement_ps_affiliated_upper60 | | 69 | savings_student_law7004 | | 70 | restitution | | 71 | monthly_income | | 72 | retirement_by_time_of_service_law1756 | | 73 | monthly_income_family_statute | | 74 | complement_pension_federal | | 75 | complement_retirement_federal | | 76 | monthly_income_statute | | 77 | monthly_income_sinpas_family_statute | | 78 | retirement_by_age_law1756 | | 79 | advantage | | 80 | monthly_income_maternity | | 81 | compulsory_retirement | | 82 | retirement_by_time_of_service_sasse | | 83 | retirement_invalidity_ex_sasse | | 84 | pension_by_death_sasse | | 85 | pension_lifetime_rubber_tapper_law7986 | | 86 | pension_lifetime_rubber_tapper_dependent_law7986 | | 87 | continuous_aid_physical_disabilities | | 88 | continuous_aid_eldness | | 89 | pension_special_hemodialysis_victim_caruaru | | 90 | medic_assistency_work_accident | | 91 | aid_sickness_by_work_accident | | 92 | retirement_invalidity_work_accident | | 93 | pension_by_death_work_accident | | 94 | aid_work_accident | | 95 | aid_additional_work_accident | | 96 | pension_special_leprosy_law11520 | | 97 | savings_by_death_work_accident | | 98 | aid_longshoreman | | 99 | time_off_15 | --- # Envio de Documentos e Formalização URL: /zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/formalizacao Envio de Documentos e Formalização Envio dos dados complementares exigidos pela IN 138 do INSS e formalização da operação (assinatura da CCB). Depois da formalização, a operação entra na fila de [averbação](/documentation/guides/INSS/reservations/averbacao-e-desaverbacao). ## Envio de documentos É obrigatório o envio (segundo IN 138 do INSS) dos dados complementares do contrato. Os documentos devem ser enviados através do [endpoint de upload de documentos](/documentation/upload_de_documentos/upload_de_documentos) e devem seguir a seguinte formatação: | Validações | Valores | |----------------|--------------| | Formato | JPEG | | Tamanho mínimo | 250 x 250 px | | Tamanho máximo | 2 MB | :::caution Atenção Contratos que tiverem documentos vinculados que não respeitam as regras de tamanho mínimo ou máximo serão cancelados permanentemente. ::: Após o upload dos documentos, as chaves dos documentos enviados devem ser informadas no payload de criação da operação ou após, através do seguinte endpoint: ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY /attached_document MÉTODO POST Testar no Playground Request Body ```json { "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41", "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431", "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c" } ``` :::info Informação A **related_party_key** é retornada na response da criação de dívida dentro do objeto **borrower** ::: ## Formalização da operação Após o input dos documentos a operação pode seguir para formalização. No caso de assinatura por parte do representante legal, no campo "**data.contract.signers[i]**" serão retornados os dados do representante legal, e o valor do objeto "**data.contract.signers[i].signer_role**" será "**issuer_legal_representative**". **No payload de assinatura devem conter os campos obrigatórios relacionados aos documentos enviados no item 5. Os campos obrigatórios são os seguintes: _ip_address_ e _signature_datetime_.** ### Request ENDPOINT /debt/ DEBT-KEY /signed MÉTODO POST Testar no Playground Request Body ```json { ..., "ip_address": "192.168.0.0", "signature_datetime": "2020-03-20T14:28:23.382748Z", "similarity_score": 0.98000, "biometry_analysis_reference": "serpro", "type": "data-signature" } ``` :::caution Atenção O payload de envio da assinatura varia de acordo com o processo de formalização do parceiro e deve ser alinhado com o time de integração da QI Tech. ::: ### Enumeradores _Biometry Analysis Reference_ | Enumerador | Descrição | |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **serpro** | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro) | | **tse** | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE | | **not_found** | Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro. | :::danger QI Sign A QI Tech oferece o serviço de assinatura que atende ao determinado pela IN 138. Com biometria facial e envio de documentos. Para receber uma cotação consulte nosso time comercial: comercial@qitech.com.br ou (11) 2339-4763 ::: ### Response ENDPOINT /debt/ DEBT-KEY /signed MÉTODO POST Response Body ```json { "data": {}, "event_datetime": "2022-11-07 15:24:47", "key": "", "status": "signature_received", "webhook_type": "debt" } ``` Após o recebimento da assinatura, uma validação dos documentos enviados e do campo assistance type será feita. Caso seja enviado um tipo de benefício [(assistance_type)](/documentation/guides/INSS/reference/enumeradores#benefit_type_enumerator) que não esteja mapeado, a operação será cancelada permanentemente. O mesmo vale para as validações de documentos, caso haja duplicidade, falta ou documentos fora dos padrões mínimos exigidos, a operação será cancelada permanente. Em ambos os casos, um webhook será enviado com o seguinte payload: WEBHOOK_TYPE debt STATUS Canceled Permanently Webhook Body ```json { "key": "", "data": {}, "status": "canceled_permanently", "webhook_type": "debt", "event_datetime": "2022-11-01 03:46:31" } ``` --- # Falha no Desembolso e Reapresentação URL: /zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/pos-desembolso Falha no Desembolso e Reapresentação O que acontece quando o desembolso falha (TED ou Pix) e como reapresentar o pagamento com novos dados bancários. ## TED Em caso de falha no desembolso via TED WEBHOOK_TYPE debt STATUS canceled Webhook Body ```json { "status": "canceled", "key": "", "data": { "ted_refusal": { "transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9", "description": "341 0000 000000-7 12345678900 - NOME BENEFICIÁRIO", "origin": { "account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0", "account_number": "00086", "bank_code": "329", "name": "ACCOUNT TRANSITORY", "type": "payment_account", "document": "32402502000135", "branch_digit": null, "account_digit": "8", "branch": "0001" }, "fee": 0, "reason_enumerator": "agencia_conta_invalida", "timestamp": "2022-11-07T14:36:05", "amount": 483.6, "reason": "Agência ou Conta Destinatária do Crédito Inválida", "destination": { "branch": "0000", "account_number": "000000", "name": "NOME BENEFICIÁRIO", "purpose": "Crédito em Conta", "type": "checking_account", "branch_digit": null, "document": "12345678900", "bank_code": "341", "account_digit": "7" } }, "cancel_reason": "ted_refusal" } } ``` ## Pix Em caso de falha no desembolso via Pix WEBHOOK_TYPE debt STATUS canceled Webhook Body ```json { "webhook_type": "debt", "data": { "pix_refusal": { "reason": "Número da conta de destino é inexistente ou inválido.", "reason_enumerator": "invalid_account", "cancel_reason_enumerator": "invalid_account" }, "cancel_reason": "pix_refusal", "cancel_reason_enumerator": "pix_refusal" }, "status": "canceled", "key": "", "event_datetime": "2025-09-04 15:29:37" } ``` ## Reapresentação de Pagamento Altera a data de desembolso sem afetar os valores financeiros da operação. ### Request ENDPOINT /debt/ DEBT-KEY /change_disbursement_date MÉTODO POST Testar no Playground Request Body ```json { "disbursement_date": "2022-11-04", "disbursement_bank_accounts": [ { "branch_number": "1232", "account_digit": "4", "account_number": "412412412", "account_type": "checking_account", "document_number": "14950479032", "bank_code": 184, "ispb_number": "17298092", "name": "Maria da Silva", "percentage_receivable": 100 } ] } ``` ### Response ENDPOINT /debt/ DEBT-KEY /change_disbursement_date MÉTODO POST Response Body ```json { "disbursement_accounts": [ { "account_branch": "1232", "account_digit": "4", "account_number": "412412412", "account_type": "checking_account", "amount_receivable": null, "created_at": "2022-05-24T14:51:46", "digitable_line": null, "disbursement_type": "ted", "document_number": "37197645832", "financial_institutions": { "code_number": 184, "ispb": 17298092, "name": "BCO ITAÚ BBA S.A." }, "financial_institutions_code_number": 184, "is_pix_disbursement": false, "ispb": "17298092", "name": "Márcio e Catarina Gráfica Ltda", "percentage_receivable": 50.0, "pix_key": null, "pix_transfer_key": null, "pix_type": null, "qr_code_key": null, "retry_counter": 0, "retry_vector": null, "transaction_key": null, "webhook_key": null } ], "disbursement_date": "2022-11-04" } ``` --- ![Competence Diagram](@site/static/img/imagem_manual_credito_novo_inss.webp) --- # 重新计算信贷操作 URL: /zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/recalculate 重新计算信贷操作 根据**新的分期付款面值**重新计算现有信贷操作的财务条款。适用于受益人的可扣除额度发生变化，需要调整分期付款金额的情况。 :::tip 优势 - **保留原始条款** — 利率、期限和操作结构保持不变，仅分期付款金额发生变化 - **即时响应** — 操作在同一调用中重新计算并返回，无需异步处理 - **自动验证** — 端点在应用前验证前置条件、利率限制和 INSS 规则 ::: ## 请求 端点 /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate 方法 POST ### 路径参数 credit_operation_key string (UUID) 必填 要重新计算的信贷操作的唯一标识。 ### 请求体参数 installment_face_value number 必填 新的分期付款面值。必须小于或等于原始值，且高于最低允许值。 ```python { "installment_face_value": 180.50 } ``` :::caution 注意 新的 `installment_face_value` 只能从原始值**降低**。端点会拒绝超过原始值或超出允许变化范围的值。 ::: ### 前置条件 操作必须满足以下**所有**条件才能被重新计算： | 条件 | 不满足时的错误 | |------|----------------| | 操作存在 | [`COP000027`](#COP000027) (404) | | 请求方拥有该操作 | [`QIT000005`](#QIT000005) (403) | | 担保类型为 `social_security` | [`COP000276`](#COP000276) | | 状态：`waiting_signature`、`issued` 或 `canceled` | [`COP000489`](#COP000489) | | 担保尚未设立 | [`COP000489`](#COP000489) | | 操作类型：`structured_operation` | [`COP000489`](#COP000489) | | 放款截止日期未过期 | [`COP000489`](#COP000489) | | 原始操作包含 `installment_face_value` | [`COP000489`](#COP000489) | | 新值在允许范围内 | [`COP000490`](#COP000490) | ## 响应 状态 200 返回完整的重新计算后的信贷操作对象 — 与[按 credit_operation_key 查询](/documentation/emissao_de_divida/consulta_por_credit_operation_key)的结构相同。 ## 错误 | HTTP 状态码 | QI 错误码 | 描述 | 翻译 | |-------------|-----------|------|------| | 404 | `COP000027` | Credit Operation not found | 未找到信贷操作 | | 403 | `QIT000005` | Selected agent does not own this item | 所选代理不拥有此项目 | | 400 | `COP000276` | Collateral type doesn't allow recalculation | 担保类型不允许重新计算操作 | | 400 | `COP000335` | Assignment amount exceeds operation final amount | 转让金额超过操作最终金额 | | 400 | `COP000339` | Final disbursement amount cannot be negative | 最终放款金额不能为负数 | | 400 | `COP000489` | Operation not allowed to be recalculated | 信贷操作不允许被重新计算 | | 400 | `COP000490` | Installment face value variance not allowed | 分期付款面值变化不在允许范围内 | COP000489 错误的详细原因 `COP000489` 代码用于不同的未满足前置条件。响应中的 `reason` 字段指示具体原因： | 原因 | 描述 | |------|------| | 状态无效 | 信贷操作状态不允许重新计算 | | 担保已设立 | 信贷操作的担保已经设立 | | 操作类型无效 | 信贷操作类型不允许重新计算 | | 放款日期已过期 | 信贷操作的放款截止日期已过 | | 缺少分期付款值 | 原始操作中未提供分期付款面值 | --- # Simulação da Dívida URL: /zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/simulacao Simulação da Dívida Simula os valores da operação antes da emissão — crédito novo ou refinanciamento puro — sem criar reserva de margem nem exigir os dados cadastrais completos do beneficiário. Próximo passo: [Emissão da Operação](/documentation/guides/INSS/new-credit-and-refinancing/emissao). ## Request crédito novo ENDPOINT /debt_simulation MÉTODO POST Testar no Playground **Valor de parcela** ```json title='Request Body' { "borrower": { "person_type": "natural" }, "financial": { "first_due_date": "2024-12-07", "installment_face_value": 100, "disbursement_date": "2024-11-05", "limit_days_to_disburse": 3, "number_of_installments": 4, "monthly_interest_rate": 0.018, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0 }, "collaterals": [ { "collateral_type": "social_security" } ] } ``` **Valor desembolsado** ```json title='Request Body' { "borrower": { "person_type": "natural" }, "financial": { "first_due_date": "2024-12-07", "disbursed_amount": 1000, "disbursement_date": "2024-11-05", "limit_days_to_disburse": 3, "number_of_installments": 4, "monthly_interest_rate": 0.018, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0 }, "collaterals": [ { "collateral_type": "social_security" } ] } ``` ## Request refinanciamento ENDPOINT /debt_simulation MÉTODO POST **Valor de Parcela** ```json { "borrower": { "person_type": "natural" }, "financial": { "first_due_date": "2024-12-07", "installment_face_value": 100, "disbursement_date": "2024-11-05", "limit_days_to_disburse": 3, "number_of_installments": 4, "monthly_interest_rate": 0.018, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0 }, "collaterals": [ { "collateral_type": "social_security" } ], "refinanced_credit_operations": [ { "operation_key": "324caa35-ba10-4590-ae2b-5efef71709c3" } ] } ``` **Valor desembolsado** ```json { "borrower": { "person_type": "natural" }, "financial": { "first_due_date": "2024-12-07", "disbursed_amount": 1000, "disbursement_date": "2024-11-05", "limit_days_to_disburse": 3, "number_of_installments": 4, "monthly_interest_rate": 0.018, "interest_type": "pre_price_days", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0 }, "collaterals": [ { "collateral_type": "social_security" } ], "refinanced_credit_operations": [ { "operation_key": "324caa35-ba10-4590-ae2b-5efef71709c3" } ] } ``` :::info Na request acima existem 2 simulações sendo realizadas. A primeira está fixando o valor de parcela ao cliente (varia o valor desembolsado) e a segunda, esta fixando o valor desembolsado (varia o valor desembolsado). ::: ## Response ENDPOINT /debt_simulation MÉTODO POST Response Body ```json { "type": "debt", "key": "8f01672d-9910-43a6-9e7d-07c031bc6fed", "status": "finished", "event_datetime": "2024-11-05 16:50:00", "data": { "interest_type": "pre_price_days", "credit_operation_type": "ccb", "interest_grace_period": 0, "interest_payment_month_period": 1, "principal_grace_period": 0, "principal_amortization_month_period": 1, "operation_type": "structured_operation", "post_fixed_interest_base": "workdays", "post_fixed_interest_rate": null, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 }, "issue_date": "2024-11-05", "number_of_installments": 4, "requester_key": "e5eb6a0a-e003-4cbd-b702-5a25bf71af0a", "final_disbursement_amount": 0.0, "disbursement_options": [ { "iof_amount": 3.93, "total_pre_fixed_amount": 17.8715883143, "cet": 0.0257, "annual_cet": 0.355163, "contract_fees": [ { "fee_type": "tac", "amount_type": "percentage", "amount": 0.6, "fee_amount": 2.29 }, { "fee_type": "ted_fee", "amount_type": "absolute", "amount": 1.0, "fee_amount": 1.0 } ], "external_contract_fees": [ { "fee_type": "spread", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "insurance_premium", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "tac", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null } ], "contract_fee_amount": 2.29, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "disbursement_date": "2024-11-05", "first_due_date": "2024-12-09", "installments": [ { "calendar_days": 34, "workdays": 23.0, "business_due_date": "2024-12-09", "due_date": "2024-12-09", "due_principal": 382.13, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 7.6967422515, "tax_amount": 0.257341482602818, "total_amount": 100, "principal_amortization_amount": 92.3032577485, "installment_number": 1 }, { "calendar_days": 29, "workdays": 19.0, "business_due_date": "2025-01-07", "due_date": "2025-01-07", "due_principal": 289.8267422515, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 4.9718040699, "tax_amount": 0.4909156601748966, "total_amount": 100, "principal_amortization_amount": 95.0281959301, "installment_number": 2 }, { "calendar_days": 31, "workdays": 23.0, "business_due_date": "2025-02-07", "due_date": "2025-02-07", "due_principal": 194.7985463214, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 3.5742034136, "tax_amount": 0.7432500400879712, "total_amount": 100, "principal_amortization_amount": 96.4257965864, "installment_number": 3 }, { "calendar_days": 28, "workdays": 18.0, "business_due_date": "2025-03-07", "due_date": "2025-03-07", "due_principal": 98.372749735, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 1.6288385793, "tax_amount": 0.9841050988526828, "total_amount": 100, "principal_amortization_amount": 98.3711614207, "installment_number": 4 } ], "issue_amount": 382.13, "disbursed_issue_amount": 374.91, "assignment_amount": 382.13, "final_disbursement_amount": 374.91, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 } }, { "iof_amount": 4.77, "total_pre_fixed_amount": 24.2597288075, "cet": 0.0243, "annual_cet": 0.334037, "contract_fees": [ { "fee_type": "tac", "amount_type": "percentage", "amount": 0.6, "fee_amount": 2.25 }, { "fee_type": "ted_fee", "amount_type": "absolute", "amount": 1.0, "fee_amount": 1.0 } ], "external_contract_fees": [ { "fee_type": "spread", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "insurance_premium", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "tac", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null } ], "contract_fee_amount": 2.25, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "disbursement_date": "2024-11-06", "first_due_date": "2025-01-07", "installments": [ { "calendar_days": 62, "workdays": 41.0, "business_due_date": "2025-01-07", "due_date": "2025-01-07", "due_principal": 375.74, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 13.9149280115, "tax_amount": 0.437656505989534, "total_amount": 100, "principal_amortization_amount": 86.0850719885, "installment_number": 1 }, { "calendar_days": 31, "workdays": 23.0, "business_due_date": "2025-02-07", "due_date": "2025-02-07", "due_principal": 289.6549280115, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 5.3146959395, "tax_amount": 0.722070128765373, "total_amount": 100, "principal_amortization_amount": 94.6853040605, "installment_number": 2 }, { "calendar_days": 28, "workdays": 18.0, "business_due_date": "2025-03-07", "due_date": "2025-03-07", "due_principal": 194.969623951, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 3.2283291407, "tax_amount": 0.9601685182659746, "total_amount": 100, "principal_amortization_amount": 96.7716708593, "installment_number": 3 }, { "calendar_days": 31, "workdays": 21.0, "business_due_date": "2025-04-07", "due_date": "2025-04-07", "due_principal": 98.1979530917, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 1.8017757158, "tax_amount": 1.2239426674782687, "total_amount": 100, "principal_amortization_amount": 98.1982242842, "installment_number": 4 } ], "issue_amount": 375.74, "disbursed_issue_amount": 367.72, "assignment_amount": 375.74, "final_disbursement_amount": 367.72, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 } }, { "iof_amount": 4.74, "total_pre_fixed_amount": 24.0392857898, "cet": 0.0243, "annual_cet": 0.334673, "contract_fees": [ { "fee_type": "tac", "amount_type": "percentage", "amount": 0.6, "fee_amount": 2.26 }, { "fee_type": "ted_fee", "amount_type": "absolute", "amount": 1.0, "fee_amount": 1.0 } ], "external_contract_fees": [ { "fee_type": "spread", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "insurance_premium", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "tac", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null } ], "contract_fee_amount": 2.26, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "disbursement_date": "2024-11-07", "first_due_date": "2025-01-07", "installments": [ { "calendar_days": 61, "workdays": 40.0, "business_due_date": "2025-01-07", "due_date": "2025-01-07", "due_principal": 375.96, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 13.6944849939, "tax_amount": 0.4317001860605122, "total_amount": 100, "principal_amortization_amount": 86.3055150061, "installment_number": 1 }, { "calendar_days": 31, "workdays": 23.0, "business_due_date": "2025-02-07", "due_date": "2025-02-07", "due_principal": 289.6544849939, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 5.3146959395, "tax_amount": 0.714305933832412, "total_amount": 100, "principal_amortization_amount": 94.6853040605, "installment_number": 2 }, { "calendar_days": 28, "workdays": 18.0, "business_due_date": "2025-03-07", "due_date": "2025-03-07", "due_principal": 194.9691809334, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 3.2283291407, "tax_amount": 0.952233241255512, "total_amount": 100, "principal_amortization_amount": 96.7716708593, "installment_number": 3 }, { "calendar_days": 31, "workdays": 21.0, "business_due_date": "2025-04-07", "due_date": "2025-04-07", "due_principal": 98.1975100741, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 1.8017757157, "tax_amount": 1.2158904130882027, "total_amount": 100, "principal_amortization_amount": 98.1982242843, "installment_number": 4 } ], "issue_amount": 375.96, "disbursed_issue_amount": 367.96, "assignment_amount": 375.96, "final_disbursement_amount": 367.96, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 } }, { "iof_amount": 4.71, "total_pre_fixed_amount": 23.8187134405, "cet": 0.0244, "annual_cet": 0.335196, "contract_fees": [ { "fee_type": "tac", "amount_type": "percentage", "amount": 0.6, "fee_amount": 2.26 }, { "fee_type": "ted_fee", "amount_type": "absolute", "amount": 1.0, "fee_amount": 1.0 } ], "external_contract_fees": [ { "fee_type": "spread", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "insurance_premium", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null }, { "fee_type": "tac", "amount_type": "absolute", "amount": 0.0, "fee_amount": 0.0, "tax_amount": 0.0, "net_fee_amount": 0.0, "csll_amount": 0, "irrf_amount": 0, "pis_amount": 0, "cofins_amount": 0, "amount_released": 0, "description": null } ], "contract_fee_amount": 2.26, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "disbursement_date": "2024-11-08", "first_due_date": "2025-01-07", "installments": [ { "calendar_days": 60, "workdays": 39.0, "business_due_date": "2025-01-07", "due_date": "2025-01-07", "due_principal": 376.18, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 13.4739126445, "tax_amount": 0.42570834978906, "total_amount": 100, "principal_amortization_amount": 86.5260873555, "installment_number": 1 }, { "calendar_days": 31, "workdays": 23.0, "business_due_date": "2025-02-07", "due_date": "2025-02-07", "due_principal": 289.6539126445, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 5.3146959395, "tax_amount": 0.706541738899451, "total_amount": 100, "principal_amortization_amount": 94.6853040605, "installment_number": 2 }, { "calendar_days": 28, "workdays": 18.0, "business_due_date": "2025-03-07", "due_date": "2025-03-07", "due_principal": 194.968608584, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 3.2283291407, "tax_amount": 0.9442979642450494, "total_amount": 100, "principal_amortization_amount": 96.7716708593, "installment_number": 3 }, { "calendar_days": 31, "workdays": 21.0, "business_due_date": "2025-04-07", "due_date": "2025-04-07", "due_principal": 98.1969377247, "has_interest": true, "post_fixed_amount": null, "pre_fixed_amount": 1.8017757158, "tax_amount": 1.20783815869566, "total_amount": 100, "principal_amortization_amount": 98.1982242842, "installment_number": 4 } ], "issue_amount": 376.18, "disbursed_issue_amount": 368.21, "assignment_amount": 376.18, "final_disbursement_amount": 368.21, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 0.23872053, "monthly_rate": 0.018, "daily_rate": 0.00058669 } } ] } } ``` --- # Anuência (pending confirmation) URL: /zh-Hans/documentation/guides/INSS/pending_confirmation Anuência (pending confirmation) Após a averbação, a reserva entra em **`pending_confirmation`** aguardando a confirmação do beneficiário no INSS. A QI Tech notifica o parceiro via webhook e segue consultando a Dataprev até a confirmação, recusa ou expiração do prazo. :::info Escopo Aplica-se a **crédito novo** e **refinanciamento**. **Portabilidade não exige anuência.** ::: :::tip Vigência **19/05/2026 às 06:00.** Mapeie o novo webhook para acionar o beneficiário com agilidade. ::: ## Fluxo - Averbação bem-sucedida → reserva entra em `pending_confirmation`. - QI Tech envia o webhook `laas.social_security.reservation.status_change` e dispara SMS ao beneficiário. - Consulta à Dataprev **a cada 3 horas**; **cada consulta redispara o webhook**. - SMS adicional ao beneficiário **uma vez por dia** enquanto a operação estiver pendente. - **Prazo máximo:** 5 dias corridos. Se expirar ou for recusada, ocorre **desaverbação** automática. | Desfecho | Webhook | |---|---| | Beneficiário confirma | `credit_operation.collateral` com `collateral_constituted: true` | | Beneficiário recusa | `debt` / `canceled` — `social_security_confirmation_denied_by_beneficiary` | | Prazo expira | `debt` / `canceled` — `social_security_confirmation_expired` | ## Webhook — anuência pendente WEBHOOK_TYPE laas.social_security.reservation.status_change STATUS pending_confirmation ```json { "key": "", "webhook_type": "laas.social_security.reservation.status_change", "status": "pending_confirmation", "event_datetime": "2026-05-19 06:15:00", "data": { "confirmation_deadline": "2026-05-20T14:25:03Z" } } ``` ## Webhook — anuência concluída Mesmo webhook de averbação já existente. Veja [Sucesso na averbação](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end#sucesso-na-averbação). WEBHOOK_TYPE credit_operation.collateral ```json { "key": "", "data": { "collateral_type": "social_security", "collateral_constituted": true }, "event_time": "2026-05-19 12:42:00", "webhook_type": "credit_operation.collateral" } ``` ## Webhook — recusa ou expiração Mesmo webhook de cancelamento já existente, distinguindo o motivo via `cancel_reason_enumerator`: | Enumerador | Quando | |---|---| | `social_security_confirmation_denied_by_beneficiary` | Beneficiário recusou a confirmação | | `social_security_confirmation_expired` | Prazo de 5 dias expirou | WEBHOOK_TYPE debt STATUS canceled ```json { "key": "", "status": "canceled", "data": { "cancel_reason": "Beneficiário recusou a confirmação da reserva", "cancel_reason_enumerator": "social_security_confirmation_denied_by_beneficiary" }, "webhook_type": "debt", "event_datetime": "2026-05-21 09:10:00" } ``` ## Testando em sandbox Em sandbox o desfecho da anuência é simulado pelo **último dígito do número do benefício** — terminados em `0`, `1`, `3`, `5` ou `6` confirmam automaticamente; `9` recusa; `7` expira; `8`, `2` e `4` permanecem pendentes. Tabela completa em [Mocks (Sandbox)](/documentation/guides/INSS/mocks-sandbox#anuencia). ## Forçar consulta imediata (Fura-fila) O [Fura-fila](/documentation/guides/INSS/reservations/priority-request) passa a aceitar reservas em `pending_confirmation`, forçando uma consulta imediata à Dataprev. :::warning Consumo de ficha Se a reserva **ainda não tiver sido confirmada**, retorna `ReservationFailed` com `last_response = confirmation_still_pending` e **consome uma ficha** do balde. Ajuste sua lógica de retentativas. ::: --- # Alterando o Cessionário URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/alterando-cessionario Alterando o Cessionário Em uma operação de Portabilidade + Refinanciamento, é possível definir um cessionário diferente do padrão no momento de aceite do refinanciamento. Isso é feito por meio do campo `purchaser_document_number` no corpo da requisição de aceite. ## Endpoint de Aceite O cessionário é configurado ao aceitar a operação de refinanciamento (Troco) via: - MÉTODO POST - ENDPOINT /v2/credit_transfer/proposal/**\{proposal_key\}**/refinancing_credit_operation/acceptance Consulte o [Fluxo Completo](./end-to-end) para o contexto completo da chamada de aceite, incluindo os demais campos obrigatórios. ## Campo `purchaser_document_number` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `purchaser_document_number` | string | Opcional | CNPJ (14 dígitos) do cessionário a ser utilizado nesta operação. Sobrescreve o cessionário padrão do parceiro. | :::info Se o campo `purchaser_document_number` for omitido, a operação utilizará o cessionário padrão configurado para o parceiro na QI Tech. ::: :::caution O campo `purchaser_document_number` só pode ser definido no momento do aceite (POST). Não é possível alterá-lo posteriormente via endpoints de correção (PUT). ::: ## Exemplo de Request Body O exemplo abaixo destaca o uso do campo `purchaser_document_number` junto aos campos `financial` e `disbursement_bank_accounts`: ```json { "financial": { "installment_face_value": 379.87, "monthly_interest_rate": 0.0166, "number_of_installments": 84, "limit_days_to_disburse": 7, "disbursement_date": "2024-07-02", "rebates": [] }, "disbursement_bank_accounts": [ { "document_number": "92093764000197", "branch_number": "0001", "name": "TESTE LTDA", "percentage_receivable": 100, "account_number": "120012", "account_digit": "3", "bank_code": "329" } ], "purchaser_document_number": "28534595027164" } ``` O campo `purchaser_document_number` deve conter o CNPJ do cessionário desejado, com 14 dígitos numéricos sem formatação. --- # Consultas e Enumeradores URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/consultas-e-enumeradores Consultas e Enumeradores Os endpoints auxiliares e as tabelas de referência desta página foram reorganizados por família, para que a mesma consulta não seja documentada duas vezes — uma por jornada. | O que estava aqui | Onde está agora | |---|---| | Consulta de Lista de Participantes do CTC - CIP | [Lista de participantes do CTC](/documentation/guides/INSS/inquiries/participantes-ctc) | | Recuperar resposta da última request | [Última resposta da averbação](/documentation/guides/INSS/inquiries/ultima-resposta) | | Webhook de resposta da última tentativa de averbação | [Última resposta da averbação](/documentation/guides/INSS/inquiries/ultima-resposta#webhook-da-ultima-tentativa-de-averbacao) | | Consulta de portabilidade de origem | [Consulta de portabilidade de origem](/documentation/guides/INSS/inquiries/portabilidade-de-origem) | | Diminuir o valor das parcelas | [Diminuir o valor das parcelas](/documentation/guides/INSS/portability+refinancing/diminuir-parcela) | | Mapeamento de enumeradores | [Enumeradores](/documentation/guides/INSS/reference/enumeradores) | --- # Correção de Dados da Proposta URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/correcao-de-dados Correção de Dados da Proposta Corrige os dados de uma proposta de portabilidade e/ou refinanciamento já criada, antes da averbação — com nova assinatura da CCB quando a correção altera as condições do refinanciamento, e sem nova assinatura quando não altera. Para reduzir apenas o **valor da parcela**, veja [Diminuir o Valor das Parcelas](/documentation/guides/INSS/portability+refinancing/diminuir-parcela). Para o recálculo do saldo devedor da portabilidade, veja [Recálculo da Portabilidade](/documentation/guides/INSS/portability+refinancing/recalculate-portability). ## Correção de dados para refinanciamento com nova assinatura da CCB: É possível corrigir os dados financeiros e os bancários da operação de refinanciamento enquanto o refinanciamento original não for averbado. ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation MÉTODO PUT Testar no Playground Request Body ```json { "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-06-10", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "monthly_interest_rate": 0.0167, "installment_face_value": 410, "limit_days_to_disburse": 7, "number_of_installments": 84 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" } } ``` *Response:* **response.json** ```json { "credit_operation_key": "", "contract_number": "00000002", "document_key": "", "document_url": "", "credit_operation_status": "issued", "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-08-09", "calendar_days": 53, "digitable_line": null, "due_date": "2021-08-08", "due_interest": 0, "due_principal": 997.87, "fine_amount": null, "has_interest": true, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-09-08", "calendar_days": 31, "digitable_line": null, "due_date": "2021-09-08", "due_interest": 0, "due_principal": 690.8886500498395, "fine_amount": null, "has_interest": true, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "tax_amount": 0, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 50, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 997.87, "final_disbursement_amount": 100, "issue_amount": 1147.87, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }], "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "ispb": "00000000", "branch_number": "0001" } } ``` :::caution A key da operação de refinanciamento, a document key, a document url, a related_party_key e a borrower related_party_key mudarão após essa ação, sendo necessário a reassinatura da CCB. ::: ## Correção de dados para refinanciamento: É possível recalcular o valor da parcela da operação de refinanciamento sem gerar uma nova CCB. O novo valor de parcela deve ser menor que o valor original. ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/recalculate MÉTODO PUT Testar no Playground Request Body ```json { "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-06-10", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "monthly_interest_rate": 0.0167, "installment_face_value": 410, "limit_days_to_disburse": 7, "number_of_installments": 84 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" } } ``` *Response:* **response.json** ```json { "credit_operation_key": "", "contract_number": "00000002", "document_key": "", "document_url": "", "credit_operation_status": "issued", "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-08-09", "calendar_days": 53, "digitable_line": null, "due_date": "2021-08-08", "due_interest": 0, "due_principal": 997.87, "fine_amount": null, "has_interest": true, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-09-08", "calendar_days": 31, "digitable_line": null, "due_date": "2021-09-08", "due_interest": 0, "due_principal": 690.8886500498395, "fine_amount": null, "has_interest": true, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "tax_amount": 0, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 50, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 997.87, "final_disbursement_amount": 100, "issue_amount": 1147.87, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }], "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "ispb": "00000000", "branch_number": "0001" } } ``` ## Correção de dados para portabilidade e refin: É possível corrigir os dados bancários, número do benefício e nome até que o contrato de portabilidade seja averbado. Tanto os dados do operação de portabilidade quanto do refinanciamento serão ajustados. Para isso basta utilizar a seguinte chamada: ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /collateral MÉTODO PATCH Testar no Playground Request Body **Dados Bancários** ```json { "disbursement_bank_account": { "bank_code": "123", "account_digit": "1", "account_branch": "1234", "account_number": "5678", "document_number": "12345678901" } } ``` **Número do Benefício** ```json { "benefit_number": 1234567890 } ``` **Nome** ```json { "name": "Nome do Beneficiário" } ``` **Nome da Mãe** ```json { "mother_name": "Nome da Mãe do Beneficiário" } ``` --- # Diminuir o Valor das Parcelas URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/diminuir-parcela Diminuir o Valor das Parcelas Reduz o valor da parcela de uma proposta já criada, antes da averbação. Este endpoint permite a redução do valor das parcelas de um contrato de portabilidade de crédito. Esta funcionalidade é especialmente útil em casos onde a margem consignável é excedida devido ao banco de origem desaverbar uma quantia menor do que a esperada. **Request** - MÉTODO PUT - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation *Payload:* **payload.json** ```json { "installment_face_value": 382.18 } ``` **Response sucesso - HTTP 200** **body.json** ```json { "credit_operation_key": "7aa77bca-c724-4c1a-bfae-9b1b7bd81ab2", "contract_number": "0000000007/WO", "document_key": "045a8f35-6170-4112-8d83-29a753d0c78e", "document_url": "http://teste.com", "signed_url": "signed_url_test", "credit_operation_status": "waiting_signature", "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_accounts": [ { "account_digit": "3", "account_branch": "0001", "account_number": "94134", "ispb": "32402502", "name": "Wilker Teste", "document_number": "37197645832" } ], "disbursement_options": [ { "prefixed_interest_rate": { "annual_rate": 3.0, "daily_rate": 0.00385824, "interest_base": "calendar_days", "monthly_rate": 0.12246205 }, "total_iof": 7.03, "external_contract_fee_amount": 0.0, "external_contract_fees": [], "contract_fee_amount": 0.0, "number_of_installments": 3, "contract_fees": [], "disbursed_issue_amount": 1000.0, "issue_amount": 1007.03, "disbursement_date": "2022-08-24", "cet": 12.6, "annual_cet": 315.3944, "installments": [ { "business_due_date": "2022-08-30", "calendar_days": 5, "due_date": "2022-08-29", "due_principal": 1007.03, "installment_number": 1, "pre_fixed_amount": 84.43554587915118, "principal_amortization_amount": 297.73445412084885, "total_amount": 382.17, "workdays": 3 }, { "business_due_date": "2022-09-30", "calendar_days": 31, "due_date": "2022-09-29", "due_principal": 709.2955458791512, "installment_number": 2, "pre_fixed_amount": 47.97894031795043, "principal_amortization_amount": 334.19105968204957, "total_amount": 382.17, "workdays": 22 }, { "business_due_date": "2022-11-01", "calendar_days": 32, "due_date": "2022-10-31", "due_principal": 375.1044861971016, "installment_number": 3, "pre_fixed_amount": 7.055513802898396, "principal_amortization_amount": 375.1044861971016, "total_amount": 382.16, "workdays": 21 } ], "final_disbursement_amount": 997.87 } ], "final_disbursement_amount": 997.87, "collateral_is_constituted": false } ``` --- # INSS 贷款转移 + 再融资手册 URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/end-to-end :::info 另请参阅 - [新贷款或再融资](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end) ::: :::danger 注意！ QI Tech 的 webhooks 不应以严格方式进行映射。 我们 API 返回的 webhook payload 中可能会包含额外字段。 ::: :::info 重新发送 Webhooks 您可以按照以下文档中的详细说明查询并重新发送 webhooks：[重新发送 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。 ::: 要启动 INSS 贷款转移 + 再融资流程，首先需要收集福利数据以检查资格，以及福利支付账户数据。第 1 和第 2 条描述了查询特定受益人福利列表的程序以及查询福利数据的程序。 ## 1 - 通过合作方正式授权书查询福利列表： **1.1.** 福利持有人是授权书的签署人。 **请求** - ENDPOINT /social_security/benefits_request - MÉTODO POST Testar no Playground *Payload：* **payload.json** ```json { "document_number": "16514548091", "authorization_term": { "document_number": "16514548091", "signature": { "signer": { "name": "Nome Devedor", "phone": { "number": "887577622", "area_code": "19", "country_code": "55" }, "document_number": "16514548091" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2023-12-05T21:04:06", "ip_address": "200.223.171.82", "fingerprint": { "lat": "-44.00524157713981", "long": "-19.807649431219804", "name": "Nome Cliente", "model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1", "localeHashValue": "hash cliente" }, "third_party_additional_data": {}, "session_id": "3571e292-3a83-4011-904d-20ee963022ef" }, "signed_object": { "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b" } } } } ``` **1.2.** 福利持有人**不是**授权书的签署人（有法定代理人）。 :::caution 注意 由于本例中授权书的签署人是法定代理人，填写 **signer** 对象的数据为法定代理人的数据。 ::: **请求** - ENDPOINT /social_security/benefits_request - MÉTODO POST *Payload：* **payload.json** ```json { "document_number": "16514548091", "authorization_term": { "document_number": "16514548091", "legal_representative_document_number": "70957091060", "signature": { "signer": { "name": "Nome Representante legal", "phone": { "number": "887577622", "area_code": "19", "country_code": "55" }, "document_number": "70957091060" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2023-12-05T21:04:06", "ip_address": "200.223.171.82", "fingerprint": { "lat": "-44.00524157713981", "long": "-19.807649431219804", "name": "Nome Cliente", "model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1", "localeHashValue": "hash cliente" }, "third_party_additional_data": {}, "session_id": "3571e292-3a83-4011-904d-20ee963022ef" }, "signed_object": { "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b" } } } } ``` :::caution 注意 在有法定代理人的情况下，需要在 **"legal_representative_document_number"** 字段中填写法定代理人的 CPF，且 **"signer"** 对象中的数据应填写法定代理人的数据。 ::: --- "**document_key**"：使用 /upload 端点返回的 GUID :::info **除了**在 **"authorization_term.signed_object.document_key"** 对象中提供签名 PDF 文档的键之外，也可以通过 **"authorization_term.signed_object.raw_text"** 对象发送授权书的纯文本内容。 ::: **响应** - MÉTODO POST - ENDPOINT social_security/benefits_request **body.json** ```json { "benefits_request_key": "c9d2aa83-006b-4753-92ad-64411a7aa700", "document_number": "18028522041", "status": "pending_authorization", "authorization_term": { "authorization_term_key": "5a7b6489-8a47-4b61-a85a-6986b058fda6", "status": "signed" }, "status_events": [ { "status": "pending_authorization", "event_date": "2023-12-22T16:12:50" } ] } ``` 福利列表查询成功时： **Webhook** - WEBHOOK_TYPE social_security_benefits_request - STATUS Success *Body：* **body.json** ```json { "webhook": { "key": "54cddd0f-b976-4266-91ea-90279bfb49a1", "data": [ { "grant_date": [ "2010-10-18" ], "benefit_number": 2052711150, "benefit_status": "elegible" } ], "status": "success", "webhook_type": "social_security_benefits_request", "event_datetime": "2023-12-22T13:20:44" } } ``` | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|----------------------------------| | benefit_number | 福利编号 | - | | benefit_status | 福利状态 | [枚举值](#benefit_status_enumerator) | 福利列表查询失败时： **Webhook** - WEBHOOK_TYPE social_security_benefits_request - STATUS Failure *Body：* **body.json** ```json { "webhook": { "key": "0020653e-c3b0-4606-af31-2ea4a577a5ce", "data": { "enumerator": "inexistent_beneficiary", "description": "no beneficiary found" }, "status": "failure", "webhook_type": "social_security_benefits_request", "event_datetime": "2023-12-22T15:46:31" } } ``` ### 失败 Webhook 中的字段详情 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Dataprev 代码的映射返回值 | [枚举值](#dataprev_benefits_errors_enumerators) | ### 在 Sandbox 中模拟福利查询的成功和失败场景： 场景模拟基于操作中填写的 CPF 的第一位数字。 **11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。 **11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字返回异步错误响应，如下表所示。 | CPF 开头 | 枚举值 | 描述 | |---------------|------------------------|----------------------| | 2 | inexistent_beneficiary | no beneficiary found | :::caution 注意 所有第一位数字没有映射场景的 CPF 将收到一个包含未映射测试场景标准错误的 webhook。 | 枚举值 | 描述 | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: --- ## 2 - 查询福利数据 {#consulta-de-dados} **2.1.** 使用之前提交的授权书查询福利数据。 **请求** - MÉTODO POST - ENDPOINT /social_security/balance_request Testar no Playground *Payload：* **payload.json** ```json { "document_number": "16514548091", "benefit_number": 2052711150 } ``` **响应** - MÉTODO POST - ENDPOINT /social_security/balance_request *Body：* **body.json** ```json { "balance_request_key": "ffda1935-9cad-47df-b848-cd33c96024e4", "document_number": "16514548091", "status": "pending_authorization", "authorization_term": { "authorization_term_key": "19196811-366f-4422-a729-4d0aa552449b", "status": "allowed" }, "status_events": [ { "status": "pending_authorization", "event_date": "2023-12-22T16:18:18" } ] } ``` **2.2.** 随授权书一同提交进行福利数据查询。 **请求** - MÉTODO POST - ENDPOINT /social_security/balance_request *Payload：* **payload.json** ```json { "document_number": "14950479032", "benefit_number": 22255220, "authorization_term": { "document_number": "14950479032", "legal_representative_document_number": "32866210050", // CPF do representante legal (caso aplicável) "signature": { "signer": { "name": "Nome Cliente", "phone": { "number": "887577622", "area_code": "19", "country_code": "55" }, "document_number": "14950479032" }, "authentication_type": "opt_in", "authenticity": { "timestamp": "2023-12-05T21:04:06", "ip_address": "200.223.171.82", "fingerprint": { "lat": "-44.00524157713981", "long": "-19.807649431219804", "name": "Nome Cliente", "model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1", "localeHashValue": "hash cliente" }, "third_party_additional_data": {}, "session_id": "b75c7ac2-3be3-41b6-b769-4d982a5824a2" }, "signed_object": { "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b" } } } } ``` :::caution 注意 在有法定代理人的情况下，需要在 **"legal_representative_document_number"** 字段中填写法定代理人的 CPF，且 **"signer"** 对象中的数据应填写法定代理人的数据。 ::: --- **响应** - MÉTODO POST - ENDPOINT /social_security/balance_request - Body： **body.json** ```json { "balance_request_key": "ffda1935-9cad-47df-b848-cd33c96024e4", "document_number": "14950479032", "status": "pending_authorization", "authorization_term": { "authorization_term_key": "19196811-366f-4422-a729-4d0aa552449b", "status": "signed" }, "status_events": [ { "status": "pending_authorization", "event_date": "2023-12-22T16:18:18" } ] } ``` 福利数据查询成功时 **Webhook** - WEBHOOK_TYPE /social_security/balance_request - STATUS Success *Body：* **body.json** ```json { "webhook": { "key": "ffda1935-9cad-47df-b848-cd33c96024e4", "data": { "name": "IVOLANDO MIRANDA", "state": "SP", "alimony": "not_payer", "birth_date": "07021961", "grant_date": "2022-09-02", "credit_type": "checking_account", "block_type": "not_blocked", "benefit_card": { "limit": 2083.2, "balance": 0 }, "benefit_number": "22255220", "benefit_status": "elegible", "payroll_card": { "limit": 2083.2, "balance": 0 }, "assistance_type": "retirement_by_age", "document_number": "14950479032", "benefit_end_date": "2020-12-01", "consigned_credit": { "balance": 1000 }, "benefit_situation": "active", "max_total_balance": 2000, "used_total_balance": 1000, "politically_exposed": { "type": "politically_exposed_level_1", "is_politically_exposed": true }, "has_power_of_attorney": false, "available_total_balance": 1000, "has_judicial_concession": false, "number_of_portabilities": 0, "disbursement_bank_account": { "bank_code": "341", "account_digit": "6", "account_branch": "0155", "account_number": "000059923" }, "has_entity_representation": false, "social_benefit_max_balance": 2000, "social_benefit_used_balance": 1000, "benefit_quota_expiration_date": null, "number_of_active_reservations": 0, "number_of_suspended_reservations": 0, "number_of_refinanced_reservations": 0, "number_of_active_suspended_reservations": 3 }, "status": "success", "webhook_type": "social_security_balance_request", "event_datetime": "2023-12-22T16:18:21" } } ``` ### 成功 Webhook 中的字段详情 | 字段 | 描述 | 值 | |---------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| | assistance_type | 福利类型 | [枚举值](#benefit_type_enumerator) | | benefit_status | 福利状态 | [枚举值](#benefit_status_enumerator) | | has_entity_representation | 是否有代理实体（不允许背书） | True 或 False | | alimony_code | 赡养费分类器 | not_payer, payer, benefit | | has_judicial_concession | 通过临时禁令批准的福利 | True 或 False | | has_power_of_attorney | 是否有代理人？ | True 或 False | | credit_type | 信贷类型 - 福利领取方式 | Magnetic_card, checking_account | | benefit_situation | 福利状态 | [枚举值](#benefit_situation_enumerator) | | used_total_balance | 用于贷款背书、转移预留、再融资、变更、RMC 和 RCC 的已占用总金额 | 数值 | | max_total_balance | 相应福利类型可占用的金额上限 | 数值 | | available_total_balance | 可用于贷款的总金额（所有模式之和，即 max_total_balance 与 used_total_balance 之差） | 数值 | | benefit_quota_expiration_date | 福利终止日期。该信息仅适用于部分死亡养恤金。 | 字符串或空值 | block_type | 福利锁定类型 | [枚举值](#block_type_enumerator) | politically_exposed.type | 政治敏感人士 | [枚举值](#politically_exposed_enumerator) | is_politically_exposed | 政治敏感人士 | True 或 False 福利列表查询失败时 **Webhook** - WEBHOOK_TYPE /social_security/balance_request - STATUS Failure *Body:* **body.json** ```json { "webhook": { "key": "37a14593-b934-457c-8cf6-e51f184b1f1c", "data": { "enumerator": "inexistent_beneficiary", "description": "no beneficiary found" }, "status": "failure", "webhook_type": "social_security_balance_request", "event_datetime": "2023-12-22T16:22:29" } } ``` ### 失败 Webhook 中的字段详情 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Dataprev 代码的映射返回值 | [枚举值](#dataprev_balance_errors_enumerators) | ### 在 Sandbox 中模拟福利数据查询的成功和失败场景： 场景模拟基于操作中填写的 CPF 的第一位数字。 **11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。 **11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字返回异步错误响应，如下表所示。 | CPF 开头 | 枚举值 | 描述 | |---------------|------------------------|----------------------| | 2 | inexistent_beneficiary | no beneficiary found | :::caution Atenção 所有未映射到第一位数字场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。 | Enumerador | Descrição | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: --- ## 3 - 录入提案： :::caution 注意 要使转移和再融资的背书申请成功创建，需要**事先**对福利进行有效的数据查询。 为此，只需按照 [2 - 查询福利数据](#consulta-de-dados) 中的步骤操作。 ::: ### 因缺乏有效福利数据查询导致的背书失败 如果在发出背书请求之前未成功进行福利数据查询，背书请求的状态将变为等待合作方操作，并以以下格式发送 webhook 以通知此事： WEBHOOK_TYPE social_security_success_balance_request_not_found STATUS Pending requester action Webhook Body ```json { "webhook": { "key": "\", "data": { "enumerator": "success_balance_request_not_found", "description": "Success balance request not found for the specified benefit number" }, "status": "pending_requester_action", "webhook_type": "social_security_success_balance_request_not_found", "event_datetime": "2024-02-26T21:36:22" } } ``` 要继续操作，需执行以下步骤： 1. 按照第 2 条 - [查询福利数据](#consulta-de-dados) 中的步骤查询相关福利数据； 2. 按以下格式发送请求以告知查询已完成。 ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /validate_reservation MÉTODO POST Testar no Playground :::info 重要 此请求不仅确认存在有效的福利数据查询，还验证用于创建背书的信息是否正确，从而允许流程继续。 ::: **3.1. 录入含再融资的转移提案：** 此录入方式用于执行信贷合同的转移，最终向债务人释放更多资金。转移后释放的金额称为"找零"。转移提案和再融资提案可以在同一个请求中生成。 提案录入时需发送以下信息： - 信贷借款人的注册数据。 - 法定代理人的注册数据（如适用）。 - 转移操作的财务数据，始终需提供期数以及利率或分期面值之一。 - 再融资操作的财务数据（用于结清转移操作并释放找零的操作），以及用于支付找零的银行账户数据（如福利数据查询中返回的账户）。 - 负责提案发起的信贷代理，也称为'pastinha'。 - 未偿余额、原始合同编号和原始债权人的 ISPB。由于再融资操作没有固定的放款日期，放款日期的变化会影响操作金额，因此需要说明是利率（"**monthly_interest_rate**"）固定还是向客户释放的金额（"**disbursed_amount**"）固定。 **如果提案针对文盲客户，委托人和证人的数据必须在提案创建 payload 的 additional_data 字段中发送。但需要事先与 QI Tech 确认将使用哪些信息和格式** **3.1.1. 录入固定利率的含再融资转移提案：** 以下是固定操作利率的提案录入示例： **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal 在 Playground 中测试 *Payload：* **Sem Registro na C3** ```json title='Request Body' { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Marilene da Silva", "mother_name": "Maria Mariane", "birth_date": "1990-05-06", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "20676928013", "document_identification_number": "381803326", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "912828135" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Águas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [ { "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "20676928013", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" } ], "collaterals": [ { "collateral_type": "social_security", "collateral_data": { "benefit_number": "22255220", "state": "SP", "subcorban_document_number": "12123456000101" } } ], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "300523588BF" }, "refinancing_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "installment_face_value": 100, "number_of_installments": 10 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "000059923", "ispb": "341", "bank_code": "341", "branch_number": "0155" }, "contract_number": "200523588BF" }, "origin_contract": { "ispb": "60746948", "contract_number": "558472", "last_due_balance": 997.87 }, "additional_data": {} } ``` **Com Registro na C3** ```json title='Request Body' { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Marilene da Silva", "mother_name": "Maria Mariane", "gender": "female", "birth_date": "1990-05-06", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "20676928013", "document_identification_number": "381803326", "document_identification_date": "2019-01-28", "document_identification_type": "rg", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "912828135" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Águas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [ { "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "20676928013", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" } ], "collaterals": [ { "collateral_type": "social_security", "collateral_data": { "benefit_number": "22255220", "state": "SP", "subcorban_document_number": "12123456000101" } } ], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "300523588PF" }, "refinancing_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "installment_face_value": 100, "number_of_installments": 10 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "000059923", "ispb": "341", "bank_code": "341", "branch_number": "0155" }, "contract_number": "200523588PK" }, "origin_contract": { "ispb": "60746948", "contract_number": "558472", "last_due_balance": 997.87 }, "additional_data": {} } ``` :::info 里约格兰德州的宽限期 根据 DATAPREV 通知，来自里约格兰德州的福利在 2024 年 6 月 28 日之后生成的新再融资合同中可有最多 **6 个月**的宽限期。 为此，需要在上述 payload 的 "**collateral_data**" 中添加一个名为 "**number_of_grace_periods**" 的字段。该字段将包含所需宽限月数的值，如以下示例所示： ```json "collaterals": [ { "collateral_type": "social_security", "collateral_data": { "benefit_number": "22255220", "state": "RS", "number_of_grace_periods": 3, "subcorban_document_number": "12123456000101" } } ] ``` ::: :::caution Atenção "**related_parties**" 列表仅应在有法定代理人的操作时发送。 发送时，必须包含法定代理人的注册数据，且 "**role_type**" 字段应发送值："**issuer_legal_representative**"。 ::: :::info 在 "**origin_contract.ispb**" 字段中填写原始债权机构的 **ISPB**。 **ISPB** 是机构 CNPJ 的基础部分。要获取 CTC - CIP（信贷转移中心）每个参与机构的完整 **ISPB** 列表，只需使用 CTC 参与者查询端点（索引）： ::: **3.1.2. 录入固定释放金额的含再融资转移提案：** 以下是固定向客户释放金额的提案录入示例： **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal *Payload：* **Sem Registro na C3** ```json title='Request Body' { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Elaine Isadora da Cruz", "mother_name": "Maria Mariane", "birth_date": "1990-05-06", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "90406718261", "document_identification_number": "381803326", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "996363253" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Aguas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [{ "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "45102538004", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" }], "collaterals": [{ "collateral_type": "social_security", "collateral_data": { "benefit_number": "12345678", "state": "SP", "subcorban_document_number": "12123456000101" } }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "3635259610" }, "refinancing_credit_operation": { "financial": { "disbursed_amount": 1000, "installment_face_value": 110, "number_of_installments": 10 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" }, "contract_number": "3635259632" }, "origin_contract": { "ispb": "60746948", "contract_number": "5584745", "last_due_balance": 800 }, "additional_data": {} } ``` **Com Registro na C3** ```json title='Request Body' { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Elaine Isadora da Cruz", "mother_name": "Maria Mariane", "birth_date": "1990-05-06", "gender": "female", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "90406718261", "document_identification_number": "381803326", "document_identification_type": "rg", "document_identification_date": "2019-01-28", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "996363253" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Aguas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [{ "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "45102538004", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" }], "collaterals": [{ "collateral_type": "social_security", "collateral_data": { "benefit_number": "12345678", "state": "SP", "subcorban_document_number": "12123456000101" } }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "3635259611" }, "refinancing_credit_operation": { "financial": { "disbursed_amount": 1000, "installment_face_value": 110, "number_of_installments": 10 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" }, "contract_number": "3635259663" }, "origin_contract": { "ispb": "60746948", "contract_number": "5584745", "last_due_balance": 800 }, "additional_data": {} } ``` **3.1.3. 响应** - MÉTODO POST - STATUS /v2/credit_transfer/proposal *Body：* **body.json** ```json { "borrower": { "individual_document_number": "90406718261", "name": "Elaine Isadora da Cruz", "related_party_key": "d7f84a9d-28ba-4355-8e5e-a436ff4c3c2d", "role_type": "issuer" }, "portability_credit_operation": { "collateral_is_constituted": false, "contract_number": "3635259611", "credit_operation_key": "235ce3a5-eea1-4b13-9335-3de577318f8b", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.17295, "cet": 0.0134, "contract_fee_amount": 0.0, "contract_fees": [ { "amount": 0.5, "amount_type": "percentage", "fee_amount": 0.0, "fee_type": "tac" } ], "disbursed_issue_amount": 800.0, "disbursement_date": "2023-12-22", "external_contract_fee_amount": 0.0, "external_contract_fees": [ { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "spread", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "tac", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "insurance_premium", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 } ], "installments": [ { "business_due_date": "2024-02-22", "calendar_days": 62, "due_date": "2024-02-22", "due_principal": 800.0, "installment_number": 1, "pre_fixed_amount": 21.977846031814607, "principal_amortization_amount": 65.21215396818539, "total_amount": 87.19, "workdays": 40 }, { "business_due_date": "2024-03-22", "calendar_days": 29, "due_date": "2024-03-22", "due_principal": 734.7878460318146, "installment_number": 2, "pre_fixed_amount": 9.373907348762184, "principal_amortization_amount": 77.81609265123781, "total_amount": 87.19, "workdays": 21 }, { "business_due_date": "2024-04-22", "calendar_days": 31, "due_date": "2024-04-22", "due_principal": 656.9717533805768, "installment_number": 3, "pre_fixed_amount": 8.963122696164149, "principal_amortization_amount": 78.22687730383585, "total_amount": 87.19, "workdays": 20 }, { "business_due_date": "2024-05-22", "calendar_days": 30, "due_date": "2024-05-22", "due_principal": 578.744876076741, "installment_number": 4, "pre_fixed_amount": 7.639487642788938, "principal_amortization_amount": 79.55051235721106, "total_amount": 87.19, "workdays": 21 }, { "business_due_date": "2024-06-24", "calendar_days": 33, "due_date": "2024-06-24", "due_principal": 499.19436371952986, "installment_number": 5, "pre_fixed_amount": 7.253119731550034, "principal_amortization_amount": 79.93688026844997, "total_amount": 87.19, "workdays": 22 }, { "business_due_date": "2024-07-22", "calendar_days": 28, "due_date": "2024-07-22", "due_principal": 419.2574834510799, "installment_number": 6, "pre_fixed_amount": 5.163027422441386, "principal_amortization_amount": 82.02697257755861, "total_amount": 87.19, "workdays": 20 }, { "business_due_date": "2024-08-22", "calendar_days": 31, "due_date": "2024-08-22", "due_principal": 337.2305108735213, "installment_number": 7, "pre_fixed_amount": 4.600865151805861, "principal_amortization_amount": 82.58913484819413, "total_amount": 87.19, "workdays": 23 }, { "business_due_date": "2024-09-23", "calendar_days": 32, "due_date": "2024-09-23", "due_principal": 254.64137602532716, "installment_number": 8, "pre_fixed_amount": 3.586947657335553, "principal_amortization_amount": 83.60305234266444, "total_amount": 87.19, "workdays": 22 }, { "business_due_date": "2024-10-22", "calendar_days": 29, "due_date": "2024-10-22", "due_principal": 171.0383236826627, "installment_number": 9, "pre_fixed_amount": 2.18198682510524, "principal_amortization_amount": 85.00801317489476, "total_amount": 87.19, "workdays": 21 }, { "business_due_date": "2024-11-22", "calendar_days": 31, "due_date": "2024-11-22", "due_principal": 86.03031050776795, "installment_number": 10, "pre_fixed_amount": 1.1637189988799015, "principal_amortization_amount": 86.0262810011201, "total_amount": 87.19, "workdays": 22 } ], "issue_amount": 800.0, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17042118, "daily_rate": 0.00043722, "interest_base": "calendar_days", "monthly_rate": 0.0132 }, "total_iof": 0.0 } ], "document_key": "c4cedeaf-23bf-450d-9fba-5ec6b5d45afb", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c4cedeaf-23bf-450d-9fba-5ec6b5d45afb/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-3635259611.pdf", "final_disbursement_amount": 0.0 }, "proposal_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497", "proposal_number": "17032782193414588", "proposal_status": "pending_submission", "refinancing_credit_operation": { "collateral_is_constituted": false, "contract_number": "3635259663", "credit_operation_key": "f73ba4d2-cd0a-4405-a47e-a51f325a9756", "credit_operation_status": "waiting_signature", "disbursement_accounts": [ { "account_branch": "0001", "account_digit": "1", "account_number": "00001", "bank_code": "033" } ], "disbursement_options": [ { "annual_cet": 0.193423, "cet": 0.0148, "contract_fee_amount": 1.03, "contract_fees": [ { "amount": 0.5, "amount_type": "percentage", "fee_amount": 1.03, "fee_type": "tac" } ], "disbursed_issue_amount": 1000.0, "disbursement_date": "2023-12-22", "external_contract_fee_amount": 0.0, "external_contract_fees": [ { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "spread", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "tac", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "insurance_premium", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 } ], "installments": [ { "business_due_date": "2024-02-22", "calendar_days": 62, "due_date": "2024-02-22", "due_principal": 1005.24, "installment_number": 1, "pre_fixed_amount": 28.92478321729087, "principal_amortization_amount": 81.07521678270913, "total_amount": 110.0, "workdays": 40 }, { "business_due_date": "2024-03-22", "calendar_days": 29, "due_date": "2024-03-22", "due_principal": 924.1647832172908, "installment_number": 2, "pre_fixed_amount": 12.344286518064438, "principal_amortization_amount": 97.65571348193556, "total_amount": 110.0, "workdays": 21 }, { "business_due_date": "2024-04-22", "calendar_days": 31, "due_date": "2024-04-22", "due_principal": 826.5090697353553, "installment_number": 3, "pre_fixed_amount": 11.806660138520433, "principal_amortization_amount": 98.19333986147957, "total_amount": 110.0, "workdays": 20 }, { "business_due_date": "2024-05-22", "calendar_days": 30, "due_date": "2024-05-22", "due_principal": 728.3157298738757, "installment_number": 4, "pre_fixed_amount": 10.06605046134725, "principal_amortization_amount": 99.93394953865275, "total_amount": 110.0, "workdays": 21 }, { "business_due_date": "2024-06-24", "calendar_days": 33, "due_date": "2024-06-24", "due_principal": 628.381780335223, "installment_number": 5, "pre_fixed_amount": 9.559924513271145, "principal_amortization_amount": 100.44007548672886, "total_amount": 110.0, "workdays": 22 }, { "business_due_date": "2024-07-22", "calendar_days": 28, "due_date": "2024-07-22", "due_principal": 527.9417048484942, "installment_number": 6, "pre_fixed_amount": 6.807113809566991, "principal_amortization_amount": 103.19288619043301, "total_amount": 110.0, "workdays": 20 }, { "business_due_date": "2024-08-22", "calendar_days": 31, "due_date": "2024-08-22", "due_principal": 424.7488186580611, "installment_number": 7, "pre_fixed_amount": 6.067525608326975, "principal_amortization_amount": 103.93247439167303, "total_amount": 110.0, "workdays": 23 }, { "business_due_date": "2024-09-23", "calendar_days": 32, "due_date": "2024-09-23", "due_principal": 320.8163442663881, "installment_number": 8, "pre_fixed_amount": 4.731771911001933, "principal_amortization_amount": 105.26822808899807, "total_amount": 110.0, "workdays": 22 }, { "business_due_date": "2024-10-22", "calendar_days": 29, "due_date": "2024-10-22", "due_principal": 215.54811617739003, "installment_number": 9, "pre_fixed_amount": 2.87912691853476, "principal_amortization_amount": 107.12087308146523, "total_amount": 110.0, "workdays": 21 }, { "business_due_date": "2024-11-22", "calendar_days": 31, "due_date": "2024-11-22", "due_principal": 108.4272430959248, "installment_number": 10, "pre_fixed_amount": 1.5688802916587754, "principal_amortization_amount": 108.43111970834123, "total_amount": 110.0, "workdays": 22 } ], "issue_amount": 1005.24, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17905959, "daily_rate": 0.00045765, "interest_base": "calendar_days", "monthly_rate": 0.01382107 }, "total_iof": 4.21 } ], "document_key": "f4dfb505-3cec-4a97-9b16-dadc39bb4c7e", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/f4dfb505-3cec-4a97-9b16-dadc39bb4c7e/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-3635259663.pdf", "final_disbursement_amount": 200.0 }, "related_party_list": [ { "individual_document_number": "45102538004", "name": "Nome Representante Legal", "related_party_key": "632fa6c5-40e8-4e76-862e-e10951ed8bff", "role_type": "issuer_legal_representative" } ] } ``` 以下是提案录入响应中返回的部分字段的定义和描述： **[A]**: ***“portability_credit_operation.disbursement_options.iof_amount”***：在转移操作中，IOF 始终为零。 **[B]**: ***“portability_credit_operation.disbursement_options.disbursed_issue_amount”***：等于原始合同的未偿余额。 **[C]**: ***“portability_credit_operation.disbursement_options.issue_amount”***：为转移操作的金额。 :::tip Relação [C] = [A] + [B] ::: **[D]**: ***“refinancing_credit_operation.disbursement_options.iof_amount”***：再融资操作（找零）的 IOF 金额。 **[E]**: ***“refinancing_credit_operation.disbursement_options.disbursed_issue_amount”***：用于结清转移操作未偿余额的金额。 :::tip Relação [E] = [C] ::: **[F]**: **"refinancing_credit_operation.disbursement_options.final_disbursement_amount"**：释放给客户（找零）的金额，发送至在提案录入时指定的放款账户（应为福利数据查询时返回的账户信息）。 **[G]**: **“refinancing_credit_operation.disbursement_options.issue_amount”**：再融资金额。 :::tip Relação {"\n"} [G] = [F] + [E] + [D] {"\n"} ::: “**portability_credit_operation.disbursement_options.collateral_constituted**“ 和 “**refinancing_credit_operation.disbursement_options.collateral_constituted**“ 字段表示客户的边际额度是否已在 Dataprev 中背书。转移的背书流程将在原始合同结清资金发送至原始债权机构后启动（第 **6.4.** 条）。再融资的背书流程在合作方决定继续再融资操作时启动（第 **7.1.1.** 和 **7.2.** 条）。 **3.2. 录入转移提案：** 转移提案（纯转移）的录入方式与第 3.1.1 条所述类似，但发送时不含 **"refinancing_credit_operation"** 对象。 **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal *Body:* **body.json** ```json { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Elaine Isadora da Cruz", "mother_name": "Maria Mariane", "birth_date": "1990-05-06", "gender": "female", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "90406718261", "document_identification_number": "381803326", "document_identification_type": "rg", "document_identification_date": "2019-01-28", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "996363253" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Aguas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [{ "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "45102538004", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" }], "collaterals": [{ "collateral_type": "social_security", "collateral_data": { "benefit_number": "12345678", "state": "SP", "subcorban_document_number": "12123456000101" } }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "1020252636" }, "origin_contract": { "ispb": "60746948", "contract_number": "558474520", "last_due_balance": 800 }, "additional_data": {} } ``` **Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal *Payload：* **payload.json** ```json { "borrower": { "individual_document_number": "90406718261", "name": "Elaine Isadora da Cruz", "related_party_key": "f9fbaa93-4d57-494f-b60f-dcba8cb64a45", "role_type": "issuer" }, "portability_credit_operation": { "collateral_is_constituted": false, "contract_number": "1020252636", "credit_operation_key": "1cd34a63-5a61-49a3-90a5-7a515ee98932", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.17295, "cet": 0.0134, "contract_fee_amount": 0.0, "contract_fees": [ { "amount": 0.5, "amount_type": "percentage", "fee_amount": 0.0, "fee_type": "tac" } ], "disbursed_issue_amount": 800.0, "disbursement_date": "2023-12-22", "external_contract_fee_amount": 0.0, "external_contract_fees": [ { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "spread", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "tac", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "insurance_premium", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 } ], "installments": [ { "business_due_date": "2024-02-22", "calendar_days": 62, "due_date": "2024-02-22", "due_principal": 800.0, "installment_number": 1, "pre_fixed_amount": 21.977846031814607, "principal_amortization_amount": 65.21215396818539, "total_amount": 87.19, "workdays": 40 }, { "business_due_date": "2024-03-22", "calendar_days": 29, "due_date": "2024-03-22", "due_principal": 734.7878460318146, "installment_number": 2, "pre_fixed_amount": 9.373907348762184, "principal_amortization_amount": 77.81609265123781, "total_amount": 87.19, "workdays": 21 }, { "business_due_date": "2024-04-22", "calendar_days": 31, "due_date": "2024-04-22", "due_principal": 656.9717533805768, "installment_number": 3, "pre_fixed_amount": 8.963122696164149, "principal_amortization_amount": 78.22687730383585, "total_amount": 87.19, "workdays": 20 }, { "business_due_date": "2024-05-22", "calendar_days": 30, "due_date": "2024-05-22", "due_principal": 578.744876076741, "installment_number": 4, "pre_fixed_amount": 7.639487642788938, "principal_amortization_amount": 79.55051235721106, "total_amount": 87.19, "workdays": 21 }, { "business_due_date": "2024-06-24", "calendar_days": 33, "due_date": "2024-06-24", "due_principal": 499.19436371952986, "installment_number": 5, "pre_fixed_amount": 7.253119731550034, "principal_amortization_amount": 79.93688026844997, "total_amount": 87.19, "workdays": 22 }, { "business_due_date": "2024-07-22", "calendar_days": 28, "due_date": "2024-07-22", "due_principal": 419.2574834510799, "installment_number": 6, "pre_fixed_amount": 5.163027422441386, "principal_amortization_amount": 82.02697257755861, "total_amount": 87.19, "workdays": 20 }, { "business_due_date": "2024-08-22", "calendar_days": 31, "due_date": "2024-08-22", "due_principal": 337.2305108735213, "installment_number": 7, "pre_fixed_amount": 4.600865151805861, "principal_amortization_amount": 82.58913484819413, "total_amount": 87.19, "workdays": 23 }, { "business_due_date": "2024-09-23", "calendar_days": 32, "due_date": "2024-09-23", "due_principal": 254.64137602532716, "installment_number": 8, "pre_fixed_amount": 3.586947657335553, "principal_amortization_amount": 83.60305234266444, "total_amount": 87.19, "workdays": 22 }, { "business_due_date": "2024-10-22", "calendar_days": 29, "due_date": "2024-10-22", "due_principal": 171.0383236826627, "installment_number": 9, "pre_fixed_amount": 2.18198682510524, "principal_amortization_amount": 85.00801317489476, "total_amount": 87.19, "workdays": 21 }, { "business_due_date": "2024-11-22", "calendar_days": 31, "due_date": "2024-11-22", "due_principal": 86.03031050776795, "installment_number": 10, "pre_fixed_amount": 1.1637189988799015, "principal_amortization_amount": 86.0262810011201, "total_amount": 87.19, "workdays": 22 } ], "issue_amount": 800.0, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17042118, "daily_rate": 0.00043722, "interest_base": "calendar_days", "monthly_rate": 0.0132 }, "total_iof": 0.0 } ], "document_key": "2f9ac920-a5e8-4386-b049-dc971e1fc20b", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/2f9ac920-a5e8-4386-b049-dc971e1fc20b/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-1020252636.pdf", "final_disbursement_amount": 0.0 }, "proposal_key": "9661aef8-e897-4405-a44f-ca8a43d9cee3", "proposal_number": "17032785232138245", "proposal_status": "pending_submission", "related_party_list": [ { "individual_document_number": "45102538004", "name": "Nome Representante Legal", "related_party_key": "c8166f37-b496-455a-96e7-f75e24f084a1", "role_type": "issuer_legal_representative" } ] } ``` **3.3. 恢复提案数据：** - MÉTODO GET - STATUS /v2/credit_transfer/proposal/PROPOSAL-KEY ou REQUESTER_CONTROL_KEY ## Path Params | Campo | Tipo | Descrição | Caracteres | |---|---| ---| ---| | `proposal_key` | string | 提案标识键 | - | | `requester_control_key` | string | 客户标识键，用于在超时或重复操作时检索提案数据，替代 proposal_key 发送 | - | *Response:* **response.json** ```json { "borrower": { "address": { "city": "SAO PAULO", "complement": "Moradia", "neighborhood": "CENTRO", "number": "10", "postal_code": "01153000", "state": "SP", "street": "RUA CENTRAL" }, "birth_date": "1976-05-25", "document_identification_number": "306385466", "email": "ivanete@windowslive.com", "individual_document_number": "25500337874", "is_pep": false, "marital_status": "single", "mother_name": "EDITE MARIA DANTAS", "name": "IVANETE SATURNINO DE SOUZA", "nationality": "Brasleira", "person_type": "natural", "phone": { "area_code": "11", "country_code": "055", "number": "985814768" }, "profession": "Aposentado", "related_party_key": "511d7186-3c17-4f35-8887-c4aefaf270be", "role_type": "issuer" }, "collaterals": [ { "collateral_data": { "benefit_number": 2045043317, "state": "SP" }, "collateral_type": "social_security" } ], "origin_operation": { "contract_date": "2025-06-02", "contract_number": "0123489618691", "financial_institution_code_number": "237", "installment_number": 84, "ispb_number": "60746948", "last_due_balance": 17879.22, "opened_installment_number": 67, "overdue_installment_number": 0 }, "portability_credit_operation": { "collateral_is_constituted": false, "contract_number": "CTC0000024971", "credit_operation_key": "e5bfbd28-0144-4eaa-b7f1-d0efb0b6b155", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.2321, "cet": 0.0175, "contract_fee_amount": 0, "contract_fees": [], "disbursed_issue_amount": 17879.22, "disbursement_date": "2025-06-02", "external_contract_fee_amount": 0, "external_contract_fees": [], "final_disbursement_amount": 17879.22, "installments": [ { "business_due_date": "2025-07-03", "calendar_days": 30, "due_date": "2025-07-02", "due_principal": 17879.22, "installment_number": 1, "pre_fixed_amount": 309.31052471, "principal_amortization_amount": 146.66947529, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2025-08-05", "calendar_days": 31, "due_date": "2025-08-02", "due_principal": 17732.55052471, "installment_number": 2, "pre_fixed_amount": 317.08981019, "principal_amortization_amount": 138.89018981, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2025-09-03", "calendar_days": 31, "due_date": "2025-09-02", "due_principal": 17593.6603349, "installment_number": 3, "pre_fixed_amount": 314.60620447, "principal_amortization_amount": 141.37379553, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2025-10-03", "calendar_days": 30, "due_date": "2025-10-02", "due_principal": 17452.28653937, "installment_number": 4, "pre_fixed_amount": 301.92457539, "principal_amortization_amount": 154.05542461, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2025-11-04", "calendar_days": 31, "due_date": "2025-11-02", "due_principal": 17298.23111476, "installment_number": 5, "pre_fixed_amount": 309.3234001, "principal_amortization_amount": 146.6565999, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2025-12-03", "calendar_days": 30, "due_date": "2025-12-02", "due_principal": 17151.57451486, "installment_number": 6, "pre_fixed_amount": 296.72225705, "principal_amortization_amount": 159.25774295, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2026-01-05", "calendar_days": 31, "due_date": "2026-01-02", "due_principal": 16992.31677191, "installment_number": 7, "pre_fixed_amount": 303.85310294, "principal_amortization_amount": 152.12689706, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2026-02-03", "calendar_days": 31, "due_date": "2026-02-02", "due_principal": 16840.18987485, "installment_number": 8, "pre_fixed_amount": 301.13280115, "principal_amortization_amount": 154.84719885, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2026-03-03", "calendar_days": 28, "due_date": "2026-03-02", "due_principal": 16685.342676, "installment_number": 9, "pre_fixed_amount": 269.25826857, "principal_amortization_amount": 186.72173143, "total_amount": 455.98, "workdays": 18 }, { "business_due_date": "2026-04-06", "calendar_days": 31, "due_date": "2026-04-02", "due_principal": 16498.62094457, "installment_number": 10, "pre_fixed_amount": 295.024936, "principal_amortization_amount": 160.955064, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2026-05-05", "calendar_days": 30, "due_date": "2026-05-02", "due_principal": 16337.66588057, "installment_number": 11, "pre_fixed_amount": 282.64163683, "principal_amortization_amount": 173.33836317, "total_amount": 455.98, "workdays": 18 }, { "business_due_date": "2026-06-03", "calendar_days": 31, "due_date": "2026-06-02", "due_principal": 16164.3275174, "installment_number": 12, "pre_fixed_amount": 289.0471699, "principal_amortization_amount": 166.9328301, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2026-07-03", "calendar_days": 30, "due_date": "2026-07-02", "due_principal": 15997.3946873, "installment_number": 13, "pre_fixed_amount": 276.75494483, "principal_amortization_amount": 179.22505517, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2026-08-04", "calendar_days": 31, "due_date": "2026-08-02", "due_principal": 15818.16963213, "installment_number": 14, "pre_fixed_amount": 282.85724601, "principal_amortization_amount": 173.12275399, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2026-09-03", "calendar_days": 31, "due_date": "2026-09-02", "due_principal": 15645.04687814, "installment_number": 15, "pre_fixed_amount": 279.76150064, "principal_amortization_amount": 176.21849936, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2026-10-05", "calendar_days": 30, "due_date": "2026-10-02", "due_principal": 15468.82837878, "installment_number": 16, "pre_fixed_amount": 267.61074714, "principal_amortization_amount": 188.36925286, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2026-11-04", "calendar_days": 31, "due_date": "2026-11-02", "due_principal": 15280.45912592, "installment_number": 17, "pre_fixed_amount": 273.24201767, "principal_amortization_amount": 182.73798233, "total_amount": 455.98, "workdays": 19 }, { "business_due_date": "2026-12-03", "calendar_days": 30, "due_date": "2026-12-02", "due_principal": 15097.72114359, "installment_number": 18, "pre_fixed_amount": 261.19059158, "principal_amortization_amount": 194.78940842, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2027-01-05", "calendar_days": 31, "due_date": "2027-01-02", "due_principal": 14902.93173517, "installment_number": 19, "pre_fixed_amount": 266.49115076, "principal_amortization_amount": 189.48884924, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2027-02-03", "calendar_days": 31, "due_date": "2027-02-02", "due_principal": 14713.44288593, "installment_number": 20, "pre_fixed_amount": 263.10275025, "principal_amortization_amount": 192.87724975, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2027-03-03", "calendar_days": 28, "due_date": "2027-03-02", "due_principal": 14520.56563618, "installment_number": 21, "pre_fixed_amount": 234.32436707, "principal_amortization_amount": 221.65563293, "total_amount": 455.98, "workdays": 18 }, { "business_due_date": "2027-04-05", "calendar_days": 31, "due_date": "2027-04-02", "due_principal": 14298.91000325, "installment_number": 22, "pre_fixed_amount": 255.69015876, "principal_amortization_amount": 200.28984124, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2027-05-04", "calendar_days": 30, "due_date": "2027-05-02", "due_principal": 14098.62016201, "installment_number": 23, "pre_fixed_amount": 243.90614356, "principal_amortization_amount": 212.07385644, "total_amount": 455.98, "workdays": 19 }, { "business_due_date": "2027-06-03", "calendar_days": 31, "due_date": "2027-06-02", "due_principal": 13886.54630557, "installment_number": 24, "pre_fixed_amount": 248.31635619, "principal_amortization_amount": 207.66364381, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2027-07-05", "calendar_days": 30, "due_date": "2027-07-02", "due_principal": 13678.88266176, "installment_number": 25, "pre_fixed_amount": 236.64468436, "principal_amortization_amount": 219.33531564, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2027-08-03", "calendar_days": 31, "due_date": "2027-08-02", "due_principal": 13459.54734612, "installment_number": 26, "pre_fixed_amount": 240.68084889, "principal_amortization_amount": 215.29915111, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2027-09-03", "calendar_days": 31, "due_date": "2027-09-02", "due_principal": 13244.24819501, "installment_number": 27, "pre_fixed_amount": 236.83091388, "principal_amortization_amount": 219.14908612, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2027-10-05", "calendar_days": 30, "due_date": "2027-10-02", "due_principal": 13025.09910889, "installment_number": 28, "pre_fixed_amount": 225.33422821, "principal_amortization_amount": 230.64577179, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2027-11-04", "calendar_days": 31, "due_date": "2027-11-02", "due_principal": 12794.4533371, "installment_number": 29, "pre_fixed_amount": 228.78777503, "principal_amortization_amount": 227.19222497, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2027-12-03", "calendar_days": 30, "due_date": "2027-12-02", "due_principal": 12567.26111213, "installment_number": 30, "pre_fixed_amount": 217.41363039, "principal_amortization_amount": 238.56636961, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2028-01-04", "calendar_days": 31, "due_date": "2028-01-02", "due_principal": 12328.69474252, "installment_number": 31, "pre_fixed_amount": 220.45917593, "principal_amortization_amount": 235.52082407, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2028-02-03", "calendar_days": 31, "due_date": "2028-02-02", "due_principal": 12093.17391845, "installment_number": 32, "pre_fixed_amount": 216.24764114, "principal_amortization_amount": 239.73235886, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2028-03-03", "calendar_days": 29, "due_date": "2028-03-02", "due_principal": 11853.44155959, "installment_number": 33, "pre_fixed_amount": 198.17224791, "principal_amortization_amount": 257.80775209, "total_amount": 455.98, "workdays": 19 }, { "business_due_date": "2028-04-04", "calendar_days": 31, "due_date": "2028-04-02", "due_principal": 11595.6338075, "installment_number": 34, "pre_fixed_amount": 207.35073152, "principal_amortization_amount": 248.62926848, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2028-05-03", "calendar_days": 30, "due_date": "2028-05-02", "due_principal": 11347.00453902, "installment_number": 35, "pre_fixed_amount": 196.3031904, "principal_amortization_amount": 259.6768096, "total_amount": 455.98, "workdays": 19 }, { "business_due_date": "2028-06-05", "calendar_days": 31, "due_date": "2028-06-02", "due_principal": 11087.32772942, "installment_number": 36, "pre_fixed_amount": 198.2613071, "principal_amortization_amount": 257.7186929, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2028-07-04", "calendar_days": 30, "due_date": "2028-07-02", "due_principal": 10829.60903652, "installment_number": 37, "pre_fixed_amount": 187.35224766, "principal_amortization_amount": 268.62775234, "total_amount": 455.98, "workdays": 19 }, { "business_due_date": "2028-08-03", "calendar_days": 31, "due_date": "2028-08-02", "due_principal": 10560.98128418, "installment_number": 38, "pre_fixed_amount": 188.84928855, "principal_amortization_amount": 267.13071145, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2028-09-05", "calendar_days": 31, "due_date": "2028-09-02", "due_principal": 10293.85057273, "installment_number": 39, "pre_fixed_amount": 184.07251228, "principal_amortization_amount": 271.90748772, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2028-10-03", "calendar_days": 30, "due_date": "2028-10-02", "due_principal": 10021.94308501, "installment_number": 40, "pre_fixed_amount": 173.37962586, "principal_amortization_amount": 282.60037414, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2028-11-06", "calendar_days": 31, "due_date": "2028-11-02", "due_principal": 9739.34271087, "installment_number": 41, "pre_fixed_amount": 174.15691709, "principal_amortization_amount": 281.82308291, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2028-12-05", "calendar_days": 30, "due_date": "2028-12-02", "due_principal": 9457.51962796, "installment_number": 42, "pre_fixed_amount": 163.61509946, "principal_amortization_amount": 292.36490054, "total_amount": 455.98, "workdays": 19 }, { "business_due_date": "2029-01-03", "calendar_days": 31, "due_date": "2029-01-02", "due_principal": 9165.15472742, "installment_number": 43, "pre_fixed_amount": 163.88940603, "principal_amortization_amount": 292.09059397, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2029-02-05", "calendar_days": 31, "due_date": "2029-02-02", "due_principal": 8873.06413345, "installment_number": 44, "pre_fixed_amount": 158.66630229, "principal_amortization_amount": 297.31369771, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2029-03-05", "calendar_days": 28, "due_date": "2029-03-02", "due_principal": 8575.75043574, "installment_number": 45, "pre_fixed_amount": 138.39042799, "principal_amortization_amount": 317.58957201, "total_amount": 455.98, "workdays": 18 }, { "business_due_date": "2029-04-03", "calendar_days": 31, "due_date": "2029-04-02", "due_principal": 8258.16086373, "installment_number": 46, "pre_fixed_amount": 147.67072888, "principal_amortization_amount": 308.30927112, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2029-05-03", "calendar_days": 30, "due_date": "2029-05-02", "due_principal": 7949.85159261, "installment_number": 47, "pre_fixed_amount": 137.53244087, "principal_amortization_amount": 318.44755913, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2029-06-05", "calendar_days": 31, "due_date": "2029-06-02", "due_principal": 7631.40403348, "installment_number": 48, "pre_fixed_amount": 136.46319254, "principal_amortization_amount": 319.51680746, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2029-07-03", "calendar_days": 30, "due_date": "2029-07-02", "due_principal": 7311.88722602, "installment_number": 49, "pre_fixed_amount": 126.49565666, "principal_amortization_amount": 329.48434334, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2029-08-03", "calendar_days": 31, "due_date": "2029-08-02", "due_principal": 6982.40288268, "installment_number": 50, "pre_fixed_amount": 124.85788785, "principal_amortization_amount": 331.12211215, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2029-09-04", "calendar_days": 31, "due_date": "2029-09-02", "due_principal": 6651.28077053, "installment_number": 51, "pre_fixed_amount": 118.93683055, "principal_amortization_amount": 337.04316945, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2029-10-03", "calendar_days": 30, "due_date": "2029-10-02", "due_principal": 6314.23760108, "installment_number": 52, "pre_fixed_amount": 109.23631711, "principal_amortization_amount": 346.74368289, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2029-11-06", "calendar_days": 31, "due_date": "2029-11-02", "due_principal": 5967.49391819, "installment_number": 53, "pre_fixed_amount": 106.70949513, "principal_amortization_amount": 349.27050487, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2029-12-04", "calendar_days": 30, "due_date": "2029-12-02", "due_principal": 5618.22341332, "installment_number": 54, "pre_fixed_amount": 97.19527093, "principal_amortization_amount": 358.78472907, "total_amount": 455.98, "workdays": 18 }, { "business_due_date": "2030-01-03", "calendar_days": 31, "due_date": "2030-01-02", "due_principal": 5259.43868425, "installment_number": 55, "pre_fixed_amount": 94.04819751, "principal_amortization_amount": 361.93180249, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2030-02-05", "calendar_days": 31, "due_date": "2030-02-02", "due_principal": 4897.50688176, "installment_number": 56, "pre_fixed_amount": 87.57620769, "principal_amortization_amount": 368.40379231, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2030-03-07", "calendar_days": 28, "due_date": "2030-03-02", "due_principal": 4529.10308945, "installment_number": 57, "pre_fixed_amount": 73.08800782, "principal_amortization_amount": 382.89199218, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2030-04-03", "calendar_days": 31, "due_date": "2030-04-02", "due_principal": 4146.21109727, "installment_number": 58, "pre_fixed_amount": 74.14169146, "principal_amortization_amount": 381.83830854, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2030-05-03", "calendar_days": 30, "due_date": "2030-05-02", "due_principal": 3764.37278873, "installment_number": 59, "pre_fixed_amount": 65.12365318, "principal_amortization_amount": 390.85634682, "total_amount": 455.98, "workdays": 20 }, { "business_due_date": "2030-06-04", "calendar_days": 31, "due_date": "2030-06-02", "due_principal": 3373.51644191, "installment_number": 60, "pre_fixed_amount": 60.32452504, "principal_amortization_amount": 395.65547496, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2030-07-03", "calendar_days": 30, "due_date": "2030-07-02", "due_principal": 2977.86096695, "installment_number": 61, "pre_fixed_amount": 51.51699784, "principal_amortization_amount": 404.46300216, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2030-08-05", "calendar_days": 31, "due_date": "2030-08-02", "due_principal": 2573.39796479, "installment_number": 62, "pre_fixed_amount": 46.0169715, "principal_amortization_amount": 409.9630285, "total_amount": 455.98, "workdays": 23 }, { "business_due_date": "2030-09-03", "calendar_days": 31, "due_date": "2030-09-02", "due_principal": 2163.43493629, "installment_number": 63, "pre_fixed_amount": 38.68609721, "principal_amortization_amount": 417.29390279, "total_amount": 455.98, "workdays": 21 }, { "business_due_date": "2030-10-03", "calendar_days": 30, "due_date": "2030-10-02", "due_principal": 1746.1410335, "installment_number": 64, "pre_fixed_amount": 30.20824171, "principal_amortization_amount": 425.77175829, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2030-11-05", "calendar_days": 31, "due_date": "2030-11-02", "due_principal": 1320.36927521, "installment_number": 65, "pre_fixed_amount": 23.61057098, "principal_amortization_amount": 432.36942902, "total_amount": 455.98, "workdays": 22 }, { "business_due_date": "2030-12-03", "calendar_days": 30, "due_date": "2030-12-02", "due_principal": 887.99984619, "installment_number": 66, "pre_fixed_amount": 15.36239827, "principal_amortization_amount": 440.61760173, "total_amount": 455.98, "workdays": 19 }, { "business_due_date": "2031-01-03", "calendar_days": 31, "due_date": "2031-01-02", "due_principal": 447.38224446, "installment_number": 67, "pre_fixed_amount": 8.59775554, "principal_amortization_amount": 447.38224446, "total_amount": 455.98, "workdays": 21 } ], "issue_amount": 17879.22, "number_of_installments": 67, "prefixed_interest_rate": { "annual_rate": 0.2285378296, "daily_rate": 0.0005718988, "interest_base": "calendar_days", "monthly_rate": 0.0173 }, "total_iof": 0 } ], "document_key": "f85d9799-e29f-4133-80c3-3e95f16f2a54", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/f85d9799-e29f-4133-80c3-3e95f16f2a54/MMRIOLTDA-IVANETESATURNINODESOUZA-CCB-CTC0000024971.pdf", "final_disbursement_amount": 17879.22 }, "proposal_key": "1e1d3f4d-21aa-4b6f-8515-6d978dc2afa5", "proposal_number": "17488903030996687", "proposal_status": "pending_submission", "refinancing_credit_operation": { "collateral_is_constituted": false, "contract_number": "CTC0000024972", "credit_operation_key": "7cc4d931-34d5-4b03-b04b-9ae4b6721f45", "credit_operation_status": "waiting_signature", "disbursement_accounts": [ { "account_branch": "1261", "account_digit": "1", "account_number": "000062293", "bank_code": "237" } ], "disbursement_options": [ { "annual_cet": 0.2517, "cet": 0.0189, "contract_fee_amount": 0, "contract_fees": [], "disbursed_issue_amount": 20373.27, "disbursement_date": "2025-06-02", "external_contract_fee_amount": 0, "external_contract_fees": [], "final_disbursement_amount": 2494.05, "installments": [ { "business_due_date": "2025-07-03", "calendar_days": 30, "due_date": "2025-07-02", "due_principal": 20458.57, "installment_number": 1, "pre_fixed_amount": 378.48354031, "principal_amortization_amount": 82.99645969, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2025-08-05", "calendar_days": 31, "due_date": "2025-08-02", "due_principal": 20375.57354031, "installment_number": 2, "pre_fixed_amount": 389.63243305, "principal_amortization_amount": 71.84756695, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2025-09-03", "calendar_days": 31, "due_date": "2025-09-02", "due_principal": 20303.72597336, "installment_number": 3, "pre_fixed_amount": 388.25852609, "principal_amortization_amount": 73.22147391, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2025-10-03", "calendar_days": 30, "due_date": "2025-10-02", "due_principal": 20230.50449945, "installment_number": 4, "pre_fixed_amount": 374.2643286, "principal_amortization_amount": 87.2156714, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2025-11-04", "calendar_days": 31, "due_date": "2025-11-02", "due_principal": 20143.28882805, "installment_number": 5, "pre_fixed_amount": 385.19056262, "principal_amortization_amount": 76.28943738, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2025-12-03", "calendar_days": 30, "due_date": "2025-12-02", "due_principal": 20066.99939067, "installment_number": 6, "pre_fixed_amount": 371.23948413, "principal_amortization_amount": 90.24051587, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2026-01-05", "calendar_days": 31, "due_date": "2026-01-02", "due_principal": 19976.7588748, "installment_number": 7, "pre_fixed_amount": 382.00608928, "principal_amortization_amount": 79.47391072, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2026-02-03", "calendar_days": 31, "due_date": "2026-02-02", "due_principal": 19897.28496408, "installment_number": 8, "pre_fixed_amount": 380.48634736, "principal_amortization_amount": 80.99365264, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2026-03-03", "calendar_days": 28, "due_date": "2026-03-02", "due_principal": 19816.29131144, "installment_number": 9, "pre_fixed_amount": 341.95166774, "principal_amortization_amount": 119.52833226, "total_amount": 461.48, "workdays": 18 }, { "business_due_date": "2026-04-06", "calendar_days": 31, "due_date": "2026-04-02", "due_principal": 19696.76297918, "installment_number": 10, "pre_fixed_amount": 376.65186051, "principal_amortization_amount": 84.82813949, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2026-05-05", "calendar_days": 30, "due_date": "2026-05-02", "due_principal": 19611.93483969, "installment_number": 11, "pre_fixed_amount": 362.82079004, "principal_amortization_amount": 98.65920996, "total_amount": 461.48, "workdays": 18 }, { "business_due_date": "2026-06-03", "calendar_days": 31, "due_date": "2026-06-02", "due_principal": 19513.27562973, "installment_number": 12, "pre_fixed_amount": 373.14311891, "principal_amortization_amount": 88.33688109, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2026-07-03", "calendar_days": 30, "due_date": "2026-07-02", "due_principal": 19424.93874864, "installment_number": 13, "pre_fixed_amount": 359.3613624, "principal_amortization_amount": 102.1186376, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2026-08-04", "calendar_days": 31, "due_date": "2026-08-02", "due_principal": 19322.82011104, "installment_number": 14, "pre_fixed_amount": 369.50112832, "principal_amortization_amount": 91.97887168, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2026-09-03", "calendar_days": 31, "due_date": "2026-09-02", "due_principal": 19230.84123936, "installment_number": 15, "pre_fixed_amount": 367.74225996, "principal_amortization_amount": 93.73774004, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2026-10-05", "calendar_days": 30, "due_date": "2026-10-02", "due_principal": 19137.10349932, "installment_number": 16, "pre_fixed_amount": 354.03641035, "principal_amortization_amount": 107.44358965, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2026-11-04", "calendar_days": 31, "due_date": "2026-11-02", "due_principal": 19029.65990967, "installment_number": 17, "pre_fixed_amount": 363.89516477, "principal_amortization_amount": 97.58483523, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2026-12-03", "calendar_days": 30, "due_date": "2026-12-02", "due_principal": 18932.07507444, "installment_number": 18, "pre_fixed_amount": 350.24338454, "principal_amortization_amount": 111.23661546, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2027-01-05", "calendar_days": 31, "due_date": "2027-01-02", "due_principal": 18820.83845898, "installment_number": 19, "pre_fixed_amount": 359.90197117, "principal_amortization_amount": 101.57802883, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2027-02-03", "calendar_days": 31, "due_date": "2027-02-02", "due_principal": 18719.26043015, "installment_number": 20, "pre_fixed_amount": 357.95954268, "principal_amortization_amount": 103.52045732, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2027-03-03", "calendar_days": 28, "due_date": "2027-03-02", "due_principal": 18615.73997283, "installment_number": 21, "pre_fixed_amount": 321.23484813, "principal_amortization_amount": 140.24515187, "total_amount": 461.48, "workdays": 18 }, { "business_due_date": "2027-04-05", "calendar_days": 31, "due_date": "2027-04-02", "due_principal": 18475.49482096, "installment_number": 22, "pre_fixed_amount": 353.2981285, "principal_amortization_amount": 108.1818715, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2027-05-04", "calendar_days": 30, "due_date": "2027-05-02", "due_principal": 18367.31294946, "installment_number": 23, "pre_fixed_amount": 339.79528536, "principal_amortization_amount": 121.68471464, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2027-06-03", "calendar_days": 31, "due_date": "2027-06-02", "due_principal": 18245.62823482, "installment_number": 24, "pre_fixed_amount": 348.90249875, "principal_amortization_amount": 112.57750125, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2027-07-05", "calendar_days": 30, "due_date": "2027-07-02", "due_principal": 18133.05073357, "installment_number": 25, "pre_fixed_amount": 335.46143442, "principal_amortization_amount": 126.01856558, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2027-08-03", "calendar_days": 31, "due_date": "2027-08-02", "due_principal": 18007.03216799, "installment_number": 26, "pre_fixed_amount": 344.33993928, "principal_amortization_amount": 117.14006072, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2027-09-03", "calendar_days": 31, "due_date": "2027-09-02", "due_principal": 17889.89210727, "installment_number": 27, "pre_fixed_amount": 342.09992543, "principal_amortization_amount": 119.38007457, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2027-10-05", "calendar_days": 30, "due_date": "2027-10-02", "due_principal": 17770.5120327, "installment_number": 28, "pre_fixed_amount": 328.75446853, "principal_amortization_amount": 132.72553147, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2027-11-04", "calendar_days": 31, "due_date": "2027-11-02", "due_principal": 17637.78650123, "installment_number": 29, "pre_fixed_amount": 337.27902945, "principal_amortization_amount": 124.20097055, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2027-12-03", "calendar_days": 30, "due_date": "2027-12-02", "due_principal": 17513.58553068, "installment_number": 30, "pre_fixed_amount": 324.0013283, "principal_amortization_amount": 137.4786717, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2028-01-04", "calendar_days": 31, "due_date": "2028-01-02", "due_principal": 17376.10685898, "installment_number": 31, "pre_fixed_amount": 332.27505371, "principal_amortization_amount": 129.20494629, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2028-02-03", "calendar_days": 31, "due_date": "2028-02-02", "due_principal": 17246.90191269, "installment_number": 32, "pre_fixed_amount": 329.80432878, "principal_amortization_amount": 131.67567122, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2028-03-03", "calendar_days": 29, "due_date": "2028-03-02", "due_principal": 17115.22624147, "installment_number": 33, "pre_fixed_amount": 305.98351411, "principal_amortization_amount": 155.49648589, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2028-04-04", "calendar_days": 31, "due_date": "2028-04-02", "due_principal": 16959.72975558, "installment_number": 34, "pre_fixed_amount": 324.31287176, "principal_amortization_amount": 137.16712824, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2028-05-03", "calendar_days": 30, "due_date": "2028-05-02", "due_principal": 16822.56262734, "installment_number": 35, "pre_fixed_amount": 311.21740475, "principal_amortization_amount": 150.26259525, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2028-06-05", "calendar_days": 31, "due_date": "2028-06-02", "due_principal": 16672.30003209, "installment_number": 36, "pre_fixed_amount": 318.81648942, "principal_amortization_amount": 142.66351058, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2028-07-04", "calendar_days": 30, "due_date": "2028-07-02", "due_principal": 16529.63652151, "installment_number": 37, "pre_fixed_amount": 305.79827186, "principal_amortization_amount": 155.68172814, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2028-08-03", "calendar_days": 31, "due_date": "2028-08-02", "due_principal": 16373.95479337, "installment_number": 38, "pre_fixed_amount": 313.11137486, "principal_amortization_amount": 148.36862514, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2028-09-05", "calendar_days": 31, "due_date": "2028-09-02", "due_principal": 16225.58616823, "installment_number": 39, "pre_fixed_amount": 310.27419199, "principal_amortization_amount": 151.20580801, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2028-10-03", "calendar_days": 30, "due_date": "2028-10-02", "due_principal": 16074.38036022, "installment_number": 40, "pre_fixed_amount": 297.37603298, "principal_amortization_amount": 164.10396702, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2028-11-06", "calendar_days": 31, "due_date": "2028-11-02", "due_principal": 15910.2763932, "installment_number": 41, "pre_fixed_amount": 304.24467264, "principal_amortization_amount": 157.23532736, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2028-12-05", "calendar_days": 30, "due_date": "2028-12-02", "due_principal": 15753.04106584, "installment_number": 42, "pre_fixed_amount": 291.43125611, "principal_amortization_amount": 170.04874389, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2029-01-03", "calendar_days": 31, "due_date": "2029-01-02", "due_principal": 15582.99232195, "installment_number": 43, "pre_fixed_amount": 297.98617451, "principal_amortization_amount": 163.49382549, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2029-02-05", "calendar_days": 31, "due_date": "2029-02-02", "due_principal": 15419.49849646, "installment_number": 44, "pre_fixed_amount": 294.85975959, "principal_amortization_amount": 166.62024041, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2029-03-05", "calendar_days": 28, "due_date": "2029-03-02", "due_principal": 15252.87825605, "installment_number": 45, "pre_fixed_amount": 263.20501023, "principal_amortization_amount": 198.27498977, "total_amount": 461.48, "workdays": 18 }, { "business_due_date": "2029-04-03", "calendar_days": 31, "due_date": "2029-04-02", "due_principal": 15054.60326628, "installment_number": 46, "pre_fixed_amount": 287.8820411, "principal_amortization_amount": 173.5979589, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2029-05-03", "calendar_days": 30, "due_date": "2029-05-02", "due_principal": 14881.00530738, "installment_number": 47, "pre_fixed_amount": 275.29859478, "principal_amortization_amount": 186.18140522, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2029-06-05", "calendar_days": 31, "due_date": "2029-06-02", "due_principal": 14694.82390216, "installment_number": 48, "pre_fixed_amount": 281.00215088, "principal_amortization_amount": 180.47784912, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2029-07-03", "calendar_days": 30, "due_date": "2029-07-02", "due_principal": 14514.34605304, "installment_number": 49, "pre_fixed_amount": 268.51539866, "principal_amortization_amount": 192.96460134, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2029-08-03", "calendar_days": 31, "due_date": "2029-08-02", "due_principal": 14321.3814517, "installment_number": 50, "pre_fixed_amount": 273.86098795, "principal_amortization_amount": 187.61901205, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2029-09-04", "calendar_days": 31, "due_date": "2029-09-02", "due_principal": 14133.76243965, "installment_number": 51, "pre_fixed_amount": 270.27323853, "principal_amortization_amount": 191.20676147, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2029-10-03", "calendar_days": 30, "due_date": "2029-10-02", "due_principal": 13942.55567818, "installment_number": 52, "pre_fixed_amount": 257.93727685, "principal_amortization_amount": 203.54272315, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2029-11-06", "calendar_days": 31, "due_date": "2029-11-02", "due_principal": 13739.01295503, "installment_number": 53, "pre_fixed_amount": 262.72463128, "principal_amortization_amount": 198.75536872, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2029-12-04", "calendar_days": 30, "due_date": "2029-12-02", "due_principal": 13540.25758631, "installment_number": 54, "pre_fixed_amount": 250.49476224, "principal_amortization_amount": 210.98523776, "total_amount": 461.48, "workdays": 18 }, { "business_due_date": "2030-01-03", "calendar_days": 31, "due_date": "2030-01-02", "due_principal": 13329.27234855, "installment_number": 55, "pre_fixed_amount": 254.88935591, "principal_amortization_amount": 206.59064409, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2030-02-05", "calendar_days": 31, "due_date": "2030-02-02", "due_principal": 13122.68170446, "installment_number": 56, "pre_fixed_amount": 250.93882097, "principal_amortization_amount": 210.54117903, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2030-03-07", "calendar_days": 28, "due_date": "2030-03-02", "due_principal": 12912.14052543, "installment_number": 57, "pre_fixed_amount": 222.81303385, "principal_amortization_amount": 238.66696615, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2030-04-03", "calendar_days": 31, "due_date": "2030-04-02", "due_principal": 12673.47355928, "installment_number": 58, "pre_fixed_amount": 242.34882657, "principal_amortization_amount": 219.13117343, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2030-05-03", "calendar_days": 30, "due_date": "2030-05-02", "due_principal": 12454.34238585, "installment_number": 59, "pre_fixed_amount": 230.40533128, "principal_amortization_amount": 231.07466872, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2030-06-04", "calendar_days": 31, "due_date": "2030-06-02", "due_principal": 12223.26771713, "installment_number": 60, "pre_fixed_amount": 233.73975368, "principal_amortization_amount": 227.74024632, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2030-07-03", "calendar_days": 30, "due_date": "2030-07-02", "due_principal": 11995.52747081, "installment_number": 61, "pre_fixed_amount": 221.91725546, "principal_amortization_amount": 239.56274454, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2030-08-05", "calendar_days": 31, "due_date": "2030-08-02", "due_principal": 11755.96472627, "installment_number": 62, "pre_fixed_amount": 224.80374013, "principal_amortization_amount": 236.67625987, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2030-09-03", "calendar_days": 31, "due_date": "2030-09-02", "due_principal": 11519.2884664, "installment_number": 63, "pre_fixed_amount": 220.27789222, "principal_amortization_amount": 241.20210778, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2030-10-03", "calendar_days": 30, "due_date": "2030-10-02", "due_principal": 11278.08635862, "installment_number": 64, "pre_fixed_amount": 208.64459505, "principal_amortization_amount": 252.83540495, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2030-11-05", "calendar_days": 31, "due_date": "2030-11-02", "due_principal": 11025.25095367, "installment_number": 65, "pre_fixed_amount": 210.83064708, "principal_amortization_amount": 250.64935292, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2030-12-03", "calendar_days": 30, "due_date": "2030-12-02", "due_principal": 10774.60160075, "installment_number": 66, "pre_fixed_amount": 199.33012714, "principal_amortization_amount": 262.14987286, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2031-01-03", "calendar_days": 31, "due_date": "2031-01-02", "due_principal": 10512.45172789, "installment_number": 67, "pre_fixed_amount": 201.02463059, "principal_amortization_amount": 260.45536941, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2031-02-04", "calendar_days": 31, "due_date": "2031-02-02", "due_principal": 10251.99635848, "installment_number": 68, "pre_fixed_amount": 196.04406604, "principal_amortization_amount": 265.43593396, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2031-03-04", "calendar_days": 28, "due_date": "2031-03-02", "due_principal": 9986.56042452, "installment_number": 69, "pre_fixed_amount": 172.32896602, "principal_amortization_amount": 289.15103398, "total_amount": 461.48, "workdays": 18 }, { "business_due_date": "2031-04-03", "calendar_days": 31, "due_date": "2031-04-02", "due_principal": 9697.40939054, "installment_number": 70, "pre_fixed_amount": 185.43896238, "principal_amortization_amount": 276.04103762, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2031-05-05", "calendar_days": 30, "due_date": "2031-05-02", "due_principal": 9421.36835292, "installment_number": 71, "pre_fixed_amount": 174.29531237, "principal_amortization_amount": 287.18468763, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2031-06-03", "calendar_days": 31, "due_date": "2031-06-02", "due_principal": 9134.18366529, "installment_number": 72, "pre_fixed_amount": 174.66866385, "principal_amortization_amount": 286.81133615, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2031-07-03", "calendar_days": 30, "due_date": "2031-07-02", "due_principal": 8847.37232914, "installment_number": 73, "pre_fixed_amount": 163.67638606, "principal_amortization_amount": 297.80361394, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2031-08-05", "calendar_days": 31, "due_date": "2031-08-02", "due_principal": 8549.5687152, "installment_number": 74, "pre_fixed_amount": 163.48934932, "principal_amortization_amount": 297.99065068, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2031-09-03", "calendar_days": 31, "due_date": "2031-09-02", "due_principal": 8251.57806452, "installment_number": 75, "pre_fixed_amount": 157.79101538, "principal_amortization_amount": 303.68898462, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2031-10-03", "calendar_days": 30, "due_date": "2031-10-02", "due_principal": 7947.8890799, "installment_number": 76, "pre_fixed_amount": 147.03594616, "principal_amortization_amount": 314.44405384, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2031-11-04", "calendar_days": 31, "due_date": "2031-11-02", "due_principal": 7633.44502606, "installment_number": 77, "pre_fixed_amount": 145.97075033, "principal_amortization_amount": 315.50924967, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2031-12-03", "calendar_days": 30, "due_date": "2031-12-02", "due_principal": 7317.93577639, "installment_number": 78, "pre_fixed_amount": 135.38181019, "principal_amortization_amount": 326.09818981, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2032-01-05", "calendar_days": 31, "due_date": "2032-01-02", "due_principal": 6991.83758658, "installment_number": 79, "pre_fixed_amount": 133.70159544, "principal_amortization_amount": 327.77840456, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2032-02-03", "calendar_days": 31, "due_date": "2032-02-02", "due_principal": 6664.05918202, "installment_number": 80, "pre_fixed_amount": 127.43364441, "principal_amortization_amount": 334.04635559, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2032-03-03", "calendar_days": 29, "due_date": "2032-03-02", "due_principal": 6330.01282643, "installment_number": 81, "pre_fixed_amount": 113.16704446, "principal_amortization_amount": 348.31295554, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2032-04-05", "calendar_days": 31, "due_date": "2032-04-02", "due_principal": 5981.69987089, "installment_number": 82, "pre_fixed_amount": 114.3852108, "principal_amortization_amount": 347.0947892, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2032-05-04", "calendar_days": 30, "due_date": "2032-05-02", "due_principal": 5634.60508169, "installment_number": 83, "pre_fixed_amount": 104.24019272, "principal_amortization_amount": 357.23980728, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2032-06-03", "calendar_days": 31, "due_date": "2032-06-02", "due_principal": 5277.36527441, "installment_number": 84, "pre_fixed_amount": 100.91655422, "principal_amortization_amount": 360.56344578, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2032-07-05", "calendar_days": 30, "due_date": "2032-07-02", "due_principal": 4916.80182863, "installment_number": 85, "pre_fixed_amount": 90.9608327, "principal_amortization_amount": 370.5191673, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2032-08-03", "calendar_days": 31, "due_date": "2032-08-02", "due_principal": 4546.28266133, "installment_number": 86, "pre_fixed_amount": 86.93640801, "principal_amortization_amount": 374.54359199, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2032-09-03", "calendar_days": 31, "due_date": "2032-09-02", "due_principal": 4171.73906934, "installment_number": 87, "pre_fixed_amount": 79.77418846, "principal_amortization_amount": 381.70581154, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2032-10-05", "calendar_days": 30, "due_date": "2032-10-02", "due_principal": 3790.0332578, "installment_number": 88, "pre_fixed_amount": 70.1156144, "principal_amortization_amount": 391.3643856, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2032-11-04", "calendar_days": 31, "due_date": "2032-11-02", "due_principal": 3398.6688722, "installment_number": 89, "pre_fixed_amount": 64.99113358, "principal_amortization_amount": 396.48886642, "total_amount": 461.48, "workdays": 20 }, { "business_due_date": "2032-12-03", "calendar_days": 30, "due_date": "2032-12-02", "due_principal": 3002.18000578, "installment_number": 90, "pre_fixed_amount": 55.54032942, "principal_amortization_amount": 405.93967058, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2033-01-04", "calendar_days": 31, "due_date": "2033-01-02", "due_principal": 2596.2403352, "installment_number": 91, "pre_fixed_amount": 49.64667309, "principal_amortization_amount": 411.83332691, "total_amount": 461.48, "workdays": 21 }, { "business_due_date": "2033-02-03", "calendar_days": 31, "due_date": "2033-02-02", "due_principal": 2184.40700829, "installment_number": 92, "pre_fixed_amount": 41.77137962, "principal_amortization_amount": 419.70862038, "total_amount": 461.48, "workdays": 23 }, { "business_due_date": "2033-03-03", "calendar_days": 28, "due_date": "2033-03-02", "due_principal": 1764.69838791, "installment_number": 93, "pre_fixed_amount": 30.45179077, "principal_amortization_amount": 431.02820923, "total_amount": 461.48, "workdays": 18 }, { "business_due_date": "2033-04-05", "calendar_days": 31, "due_date": "2033-04-02", "due_principal": 1333.67017868, "installment_number": 94, "pre_fixed_amount": 25.50314255, "principal_amortization_amount": 435.97685745, "total_amount": 461.48, "workdays": 22 }, { "business_due_date": "2033-05-03", "calendar_days": 30, "due_date": "2033-05-02", "due_principal": 897.69332123, "installment_number": 95, "pre_fixed_amount": 16.60732624, "principal_amortization_amount": 444.87267376, "total_amount": 461.48, "workdays": 19 }, { "business_due_date": "2033-06-03", "calendar_days": 31, "due_date": "2033-06-02", "due_principal": 452.82064747, "installment_number": 96, "pre_fixed_amount": 8.65935253, "principal_amortization_amount": 452.82064747, "total_amount": 461.48, "workdays": 23 } ], "issue_amount": 20458.57, "number_of_installments": 96, "prefixed_interest_rate": { "annual_rate": 0.2460411933, "daily_rate": 0.0006112186, "interest_base": "calendar_days", "monthly_rate": 0.0185 }, "total_iof": 85.3 } ], "document_key": "60763cba-da54-4826-bf76-b8f3d26c6326", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/60763cba-da54-4826-bf76-b8f3d26c6326/MMRIOLTDA-A-CCB-CTC0000024972.pdf", "final_disbursement_amount": 2494.05 }, "requester_control_key": "0e856d23-0746-4444-a71a-2957a64c869a" } ``` :::info 对于纯转移提案数据的恢复，"refinancing_credit_operation" 对象将不会被返回。 ::: ### 带新 CCB 签名的再融资数据更正： 在再融资尚未被接受之前，可以更正再融资操作的财务数据和银行数据。 ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation MÉTODO PUT Testar no Playground Request Body ```json { "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-06-10", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "monthly_interest_rate": 0.0167, "installment_face_value": 410, "limit_days_to_disburse": 7, "number_of_installments": 84 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" } } ``` *Response:* **response.json** ```json { "credit_operation_key": "\", "contract_number": "00000002", "document_key": "\", "document_url": "\", "credit_operation_status": "issued", "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-08-09", "calendar_days": 53, "digitable_line": null, "due_date": "2021-08-08", "due_interest": 0, "due_principal": 997.87, "fine_amount": null, "has_interest": true, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-09-08", "calendar_days": 31, "digitable_line": null, "due_date": "2021-09-08", "due_interest": 0, "due_principal": 690.8886500498395, "fine_amount": null, "has_interest": true, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "tax_amount": 0, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 50, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 997.87, "final_disbursement_amount": 100, "issue_amount": 1147.87, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }], "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "ispb": "00000000", "branch_number": "0001" } } ``` :::caution 再融资操作键、文档键、文档 URL、related_party_key 和借款人 related_party_key 将在此操作后更改，需要重新签署 CCB。 ::: ### 再融资数据更正： 可以重新计算再融资操作的分期金额而无需生成新的 CCB。新金额将根据录入时提供的利率，应用于当前未偿余额来计算。 ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/recalculate MÉTODO PUT Testar no Playground Request Body ```json { "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-06-10", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "monthly_interest_rate": 0.0167, "installment_face_value": 410, "limit_days_to_disburse": 7, "number_of_installments": 84 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" } } ``` *Response:* **response.json** ```json { "credit_operation_key": "\", "contract_number": "00000002", "document_key": "\", "document_url": "\", "credit_operation_status": "issued", "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-08-09", "calendar_days": 53, "digitable_line": null, "due_date": "2021-08-08", "due_interest": 0, "due_principal": 997.87, "fine_amount": null, "has_interest": true, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-09-08", "calendar_days": 31, "digitable_line": null, "due_date": "2021-09-08", "due_interest": 0, "due_principal": 690.8886500498395, "fine_amount": null, "has_interest": true, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "tax_amount": 0, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 50, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 997.87, "final_disbursement_amount": 100, "issue_amount": 1147.87, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }], "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "ispb": "00000000", "branch_number": "0001" } } ``` ### 转移和再融资数据更正： 可以更正银行数据、福利编号和姓名，直到转移合同状态变为 "pending_response" 之前。 ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /collateral MÉTODO PATCH Testar no Playground Request Body **Dados Bancários** ```json { "disbursement_bank_account": { "bank_code": "123", "account_digit": "1", "account_branch": "1234", "account_number": "5678", "document_number": "12345678901" } } ``` **Número do Benefício** ```json { "benefit_number": 1234567890 } ``` **Nome** ```json { "name": "Nome do Beneficiário" } ``` **Nome da Mãe** ```json { "mother_name": "Nome da Mãe do Beneficiário" } ``` ### 在沙盒中模拟背书的成功和失败场景： 场景模拟基于操作中提供的 CPF 第一位数字。 **11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。 **11.2.** 对于其他 CPF，将根据输入的 CPF 第一位数字，按照下表返回异步错误响应。 **11.3.** 操作为 "cancel" 的错误将收到包含操作最终结果的 webhook。 | Início do cpf | Enumerador | Descrição | Ação | |---------------|------------------------------|-----------------------------------------------------------------------------------|--------| | 2 | invalid_disbursement_account | Invalid disbursemente bank account | cancel | | 3 | operation_not_allowed_IR | Operation not allowed due to operation deadline greatter than benefit termination | cancel | :::caution Atenção 所有未映射到第一位数字场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。 | Enumerador | Descrição | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: --- ## 4 - 文件上传 根据 INSS 第 138 号规范性指令，必须发送合同的补充数据。 文件必须通过[文件上传端点](../upload_de_documentos)发送。 | Validações | Valores | |----------------|--------------| | Formato | JPEG | | Tamanho mínimo | 250 x 250 px | | Tamanho máximo | 2 MB | :::caution Atenção 不符合最小或最大文件大小规则的合同，将无法背书，相应的错误信息将通过 webhook 发送。 如果验证未通过，当合作方在收到未偿余额后继续处理提案时，将返回以下错误： **Formato inválido** ```json { "title": "Invalid document format", "description": "The document: document_identification_back should be in JPEG format.", "translation": "O documento: document_identification_back deve estar no formato JPEG.", "code": "SSC000061" } ``` **Tamanho inválido** ```json { "title": "Invalid document size", "description": "The document: document_identification_back should have at least 250x250px.", "translation": "O documento: document_identification_back deve ter no mínimo 250x250px.", "code": "SSC000060" } ``` 文件上传后，所上传文件的键值必须在创建提案的 payload 中（在 *borrower* 字段内）或在对应法定代理人的 *related_parties** 对象内（*"role_type": "issuer_legal_representative"*）填写： ```json { "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41", "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431", "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c" } ``` 或者，在提案创建后，可通过以下端点告知： ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /related_party/ RELATED-PARTY-KEY /attached_document MÉTODO POST Testar no Playground Request Body ```json { "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41", "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431", "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c" } ``` :::info Informação **related_party_key** 在债务创建响应的 **borrower** 对象中返回，用于将文件关联到相关人员（借款人或法定代理人）。 --- ## 5 - 模拟转移和/或再融资提案： :::caution Atenção 对于涉及再融资后找零的提案，需要预先计算找零金额，该金额至少应为所有分期金额现值之和与原始债务余额之差的 5%。可以通过使用第 **5** 条中描述的模拟路由来确定找零金额。 STATUS 400 **Response Body** ```json { "title": "Bad Request", "code": "CT000118", "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00." } ``` ::: **5.1. 带再融资的转移模拟：** 在录入带再融资的转移提案之前，可以模拟操作的财务条件。 **5.1.1. 带再融资的转移模拟 - 固定利率：** 与提案录入（3.1.1）类似，可以通过固定转移合同利率进行模拟。 **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Request:* **body.json** ```json { "borrower": { "person_type": "natural" }, "collaterals": [{ "collateral_type": "social_security" }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 } }, "refinancing_credit_operation": { "financial": { "days_to_accrual": 0, "monthly_interest_rate": 0.0132, "installment_face_value": 100, "number_of_installments": 10 } }, "origin_contract": { "last_due_balance": 997.87 } } ``` :::info 上述 payload 描述了执行模拟所需的最低数据。 ::: **Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload：* **response.json** ```json { "borrower": { "individual_document_number": "98765432100", "related_party_key": "fa55dca3-3147-45d2-bb8d-941f2d7191da", "role_type": "issuer" }, "portability_credit_operation": { "credit_operation_key": "a66675e6-bdc2-4468-8420-2889d5cec0a8", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.173044, "cet": 0.0134, "contract_fee_amount": 0.0, "contract_fees": [ { "amount": 0.5, "amount_type": "percentage", "fee_amount": 0.0, "fee_type": "tac" } ], "disbursed_issue_amount": 997.87, "disbursement_date": "2023-12-22", "external_contract_fee_amount": 0.0, "external_contract_fees": [ { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "spread", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "tac", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "insurance_premium", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 } ], "installments": [ { "business_due_date": "2024-02-22", "calendar_days": 62, "due_date": "2024-02-22", "due_principal": 997.87, "installment_number": 1, "pre_fixed_amount": 27.413791524708554, "principal_amortization_amount": 81.34620847529145, "total_amount": 108.76, "workdays": 40 }, { "business_due_date": "2024-03-22", "calendar_days": 29, "due_date": "2024-03-22", "due_principal": 916.5237915247086, "installment_number": 2, "pre_fixed_amount": 11.692366920719124, "principal_amortization_amount": 97.06763307928088, "total_amount": 108.76, "workdays": 21 }, { "business_due_date": "2024-04-22", "calendar_days": 31, "due_date": "2024-04-22", "due_principal": 819.4561584454277, "installment_number": 3, "pre_fixed_amount": 11.179911547915339, "principal_amortization_amount": 97.58008845208467, "total_amount": 108.76, "workdays": 20 }, { "business_due_date": "2024-05-22", "calendar_days": 30, "due_date": "2024-05-22", "due_principal": 721.876069993343, "installment_number": 4, "pre_fixed_amount": 9.5288330736045, "principal_amortization_amount": 99.2311669263955, "total_amount": 108.76, "workdays": 21 }, { "business_due_date": "2024-06-24", "calendar_days": 33, "due_date": "2024-06-24", "due_principal": 622.6449030669476, "installment_number": 5, "pre_fixed_amount": 9.046812945831448, "principal_amortization_amount": 99.71318705416856, "total_amount": 108.76, "workdays": 22 }, { "business_due_date": "2024-07-22", "calendar_days": 28, "due_date": "2024-07-22", "due_principal": 522.9317160127789, "installment_number": 6, "pre_fixed_amount": 6.439743824282488, "principal_amortization_amount": 102.32025617571752, "total_amount": 108.76, "workdays": 20 }, { "business_due_date": "2024-08-22", "calendar_days": 31, "due_date": "2024-08-22", "due_principal": 420.61145983706143, "installment_number": 7, "pre_fixed_amount": 5.738438681013405, "principal_amortization_amount": 103.0215613189866, "total_amount": 108.76, "workdays": 23 }, { "business_due_date": "2024-09-23", "calendar_days": 32, "due_date": "2024-09-23", "due_principal": 317.58989851807485, "installment_number": 8, "pre_fixed_amount": 4.473657660291388, "principal_amortization_amount": 104.28634233970861, "total_amount": 108.76, "workdays": 22 }, { "business_due_date": "2024-10-22", "calendar_days": 29, "due_date": "2024-10-22", "due_principal": 213.30355617836625, "installment_number": 9, "pre_fixed_amount": 2.721176981322744, "principal_amortization_amount": 106.03882301867725, "total_amount": 108.76, "workdays": 21 }, { "business_due_date": "2024-11-22", "calendar_days": 31, "due_date": "2024-11-22", "due_principal": 107.26473315968899, "installment_number": 10, "pre_fixed_amount": 1.4934220715493307, "principal_amortization_amount": 107.26657792845067, "total_amount": 108.76, "workdays": 22 } ], "issue_amount": 997.87, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17042118, "daily_rate": 0.00043722, "interest_base": "calendar_days", "monthly_rate": 0.0132 }, "total_iof": 0.0 } ], "final_disbursement_amount": 0.0 }, "proposal_key": "28a925f6-570e-4724-9132-3bd42f267c4f", "proposal_number": "17032788499215403", "proposal_status": "pending_submission", "refinancing_credit_operation": { "credit_operation_key": "aaf9abe0-2b8a-4688-8e09-413e1bd5285e", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.172031, "cet": 0.0133, "contract_fee_amount": -0.4, "contract_fees": [ { "amount": 0.5, "amount_type": "percentage", "fee_amount": -0.4, "fee_type": "tac" } ], "disbursed_issue_amount": 918.04, "disbursement_date": "2023-12-22", "external_contract_fee_amount": 0.0, "external_contract_fees": [ { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "spread", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "tac", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "insurance_premium", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 } ], "installments": [ { "business_due_date": "2024-02-22", "calendar_days": 62, "due_date": "2024-02-22", "due_principal": 917.64, "installment_number": 1, "pre_fixed_amount": 25.2095730147, "principal_amortization_amount": 74.7904269853, "total_amount": 100.0, "workdays": 40 }, { "business_due_date": "2024-03-22", "calendar_days": 29, "due_date": "2024-03-22", "due_principal": 842.8495730147, "installment_number": 2, "pre_fixed_amount": 10.7524369787, "principal_amortization_amount": 89.2475630213, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-04-22", "calendar_days": 31, "due_date": "2024-04-22", "due_principal": 753.6020099934, "installment_number": 3, "pre_fixed_amount": 10.2814172859, "principal_amortization_amount": 89.7185827141, "total_amount": 100.0, "workdays": 20 }, { "business_due_date": "2024-05-22", "calendar_days": 30, "due_date": "2024-05-22", "due_principal": 663.8834272793, "installment_number": 4, "pre_fixed_amount": 8.7632941742, "principal_amortization_amount": 91.2367058258, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-06-24", "calendar_days": 31, "due_date": "2024-06-22", "due_principal": 572.6467214535, "installment_number": 5, "pre_fixed_amount": 7.8126464787, "principal_amortization_amount": 92.1873535213, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-07-22", "calendar_days": 30, "due_date": "2024-07-22", "due_principal": 480.4593679322, "installment_number": 6, "pre_fixed_amount": 6.3420966342, "principal_amortization_amount": 93.6579033658, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-08-22", "calendar_days": 31, "due_date": "2024-08-22", "due_principal": 386.8014645664, "installment_number": 7, "pre_fixed_amount": 5.2771618926, "principal_amortization_amount": 94.7228381074, "total_amount": 100.0, "workdays": 23 }, { "business_due_date": "2024-09-23", "calendar_days": 31, "due_date": "2024-09-22", "due_principal": 292.078626459, "installment_number": 8, "pre_fixed_amount": 3.9848593609, "principal_amortization_amount": 96.0151406391, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-10-22", "calendar_days": 30, "due_date": "2024-10-22", "due_principal": 196.0634858199, "installment_number": 9, "pre_fixed_amount": 2.5880710578, "principal_amortization_amount": 97.4119289422, "total_amount": 100.0, "workdays": 22 }, { "business_due_date": "2024-11-22", "calendar_days": 31, "due_date": "2024-11-22", "due_principal": 98.6515568777, "installment_number": 10, "pre_fixed_amount": 1.3459361963, "principal_amortization_amount": 98.6540638037, "total_amount": 100.0, "workdays": 22 } ], "issue_amount": 917.64, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17042118, "daily_rate": 0.00043722, "interest_base": "calendar_days", "monthly_rate": 0.0132 }, "total_iof": 0.0 } ], "final_disbursement_amount": -79.83 } } ``` **5.1.2. 带再融资的转移模拟 - 固定释放金额：** 与提案录入（**3.1.2**）类似，可以通过固定向客户释放的金额进行模拟： **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload：* **payload.json** ```json { "borrower": { "person_type": "natural" }, "collaterals": [{ "collateral_type": "social_security" }], "portability_credit_operation": { "financial": { "installment_face_value": 100, "number_of_installments": 10 } }, "refinancing_credit_operation": { "financial": { "days_to_accrual": 0, "disbursed_amount": 1000, "installment_face_value": 100, "number_of_installments": 10 } }, "origin_contract": { "last_due_balance": 997.87 } } ``` **Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload：* **payload.json** ```json { "portability_credit_operation": { "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-08-09", "calendar_days": 53, "due_date": "2021-08-08", "due_principal": 997.87, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-09-08", "calendar_days": 31, "due_date": "2021-09-08", "due_principal": 690.89, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 0, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 1000, "issue_amount": 1000, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }] }, "refinancing_credit_operation": { "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-08-09", "calendar_days": 53, "due_date": "2021-08-08", "due_principal": 997.87, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-09-08", "calendar_days": 31, "due_date": "2021-09-08", "due_principal": 690.89, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 0, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 1000, "issue_amount": 1000, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }] } } ``` **5.2. 转移模拟：** 也可以模拟无再融资的转移提案（纯转移）的财务条件，无需采集客户注册数据。 **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload：* **payload.json** ```json { "borrower": { "person_type": "natural" }, "collaterals": [{ "collateral_type": "social_security" }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "installment_face_value": 100, "number_of_installments": 10 } }, "origin_contract": { "last_due_balance": 997.87 } } ``` **Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload：* **payload.json** ```json { "portability_credit_operation": { "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-08-09", "calendar_days": 53, "due_date": "2021-08-08", "due_principal": 997.87, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-09-08", "calendar_days": 31, "due_date": "2021-09-08", "due_principal": 690.89, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 0, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 1000, "issue_amount": 1000, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }] } } ``` --- ## 6 - 提案正式化： :::caution 注意 对于涉及再融资后找零的提案，需要预先计算找零金额，根据合同条件，该金额至少应为所有再融资分期金额之和减去所有转移分期金额之和的 5%。否则，请求将收到以下错误： STATUS 400 **Response Body** ```json { "title": "Bad Request", "code": "CT000118", "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00." } ``` ::: 要正式化转移和/或再融资（找零）操作，必须发送提案录入时生成的合同签署证明。 **签署 payload 中必须包含第 4 条中发送的文件相关必填字段。必填字段如下：_ip_address_ 和 _signature_datetime_。** **6.1.** 合作方需发起以下调用以签署转移操作： **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation/signature Testar no Playground *Payload：* **payload.json** ```json { "type": "pdf-signature", "biometry_analysis_reference": "SERPRO", "signature_datetime": "2023-12-22T15:01:32.482Z", "signed_pdf_path": "https://termos-originacao.s3.amazonaws.com/5cd2a7f9", "ip_address": "179.145.48.219", "similarity_score": "0.9750000000000001" } ``` ### Enumeradores _Biometry Analysis Reference_ | Enumerador | Descrição | |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **serpro** | 当 similarity_score 通过查询 SERPRO 数据库返回时使用。 | | **tse** | 当 similarity_score 通过查询 TSE 数据库返回时使用。 | | **not_found** | 当面部生物识别在任何数据库（SERPRO 或 TSE）中均未找到时使用。 | 签署完成将以异步方式通知： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal.credit_operation", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "portability", "credit_operation_key": "\", "document_key": "\", "signed_document_url": "\", "credit_operation_status": "signed" } } ``` **6.2.** 合作方需发起以下调用以签署再融资操作（找零）： **Request** - MÉTODO POST - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/signature Testar no Playground *Payload：* **payload.json** ```json { "type": "pdf-signature", "signed_pdf_path": "https://termos-originacao.s3.amazonaws.com/5cd2a7f9", "ip_address": "192.168.0.0", "signature_datetime": "2020-03-20T14:28:23.382748Z", "similarity_score": "0.98", "biometry_analysis_reference": "serpro" } ``` 签署完成将以异步方式通知： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal.credit_operation", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "refinancing", "credit_operation_key": "\", "document_key": "\", "signed_document_url": "\", "credit_operation_status": "signed" } } ``` --- ## 7 - 转移提案状态机： 转移提案的状态反映了 CIP 信贷转移中心（CTC）内信贷转移流程所涉及的各个阶段。 以下是转移提案中每个状态的流程说明： **7.1. pending_response:** 录入后的提案状态。在此状态下，提案已被 QI 成功接收并发送至 CTC - CIP。 **6.1.1 rejected:** 如果提案录入被 CTC - CIP 拒绝，将发送包含拒绝原因的 webhook： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS rejected *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "rejected", "event_datetime": "2022-11-24T15:42:12", "data": { "error": { "code": "ECTC0023", "reason": "Contrato com portabilidade em andamento" } } } ``` **7.1.1 rejected reasons:** 如果提案录入被 CTC - CIP 拒绝，将发送包含拒绝原因的 webhook： | reason | description | external_code | |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------| | portability_in_progress | 转移进行中的合同 | ECTC0023 | | portability_finished | 所指定合同的转移已完成 | ECTC0028 | | portability_in_expiration_progress | 不允许转移。合同转移因未完成转移而处于"到期流程"状态 | ECTC0085 | | unexpected_error | Erro inesperado | ECTC9999 | | portability_payment_rejected | Pagamento de portabilidade rejeitado. | | | divergent_due_balance | Saldo devedor final deve ser menor que saldo devedor devolvido pela cip. |               | **7.2. pending_acceptance：** CTC - CIP 发送/接受后的提案状态。提案此时正在等待原始债权银行的未偿余额响应。此时将发送包含 CTC - CIP 转移编号的 webhook： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS pending_acceptance *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "pending_acceptance", "event_datetime": "2022-11-24T15:42:12", "data": { "portability_number": "202211230000246536429", "inclusion_date": "2022-11-24", "due_balance_expected_return_date": "2022-12-01" } } ``` :::info **"portability_number"** 是 CTC - CIP 内的转移编号，是提案机构和原始债权机构用于识别转移操作的编号。 ::: 一旦原始债权银行响应转移申请，将发送以下 webhook 并通知未偿余额。 **7.2.1. accepted：** 当原始债权银行返回未偿余额且不保留信贷时的提案状态。将发送包含未偿余额信息的 webhook。 原始债权银行在收到转移提案后，有最多 5 个工作日向承接银行（QI Tech）发送响应。 **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS accepted *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "accepted", "event_datetime": "2022-11-24T15:42:12", "data": { "final_due_balance": 1000, "portability_number": "202211230000246536429", "original_contract": { "origin_contract_number": "5584745", "origin_ispb_number": "60746948", "origin_document_number": "90406718261", "origin_operation_type": "0202", "installment_face_value": 1000, "total_iof": 1, "first_due_date": "2021-05-31", "last_due_date": "2022-05-31", "interest": 1, "cet": 1, "installment_number": 12, "amortization": 1, "final_due_balance": 1000, "final_due_date": "2021-08-31", "contract_date": "2021-04-31" } } } ``` 收到原始债权机构返回的未偿余额信息后，合作方必须在 **5** 个工作日内明确表示是否接受该余额。如果合作方选择接受，则进行如下调用： :::info 原始债权机构发送未偿余额的截止时间为 10:00。 ::: 收到未偿余额后，如果合作方决定继续推进提案，必须在 **5** 个工作日内接受该余额。接受时，合作方必须在 payload 中提供财务条件和放款账户。 **Request** - MÉTODO PATCH - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY Testar no Playground *Payload：* **payload.json** ```json { "status":"accepted_by_requester" } ``` :::caution Atenção 对于涉及再融资后找零的提案，根据合同的新条件，找零金额至少应为所有再融资分期金额之和减去所有转移分期金额之和的 5%。 STATUS 400 **Response Body** ```json { "title": "Bad Request", "code": "CT000118", "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00." } ``` ::: 合作方可以在此调用中添加新的分期金额或新利率数据（如需更改）： **Request** - MÉTODO PATCH - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY *Payload：* **payload.json** ```json { "status":"accepted_by_requester", "financial": { "installment_face_value": 100 } } ``` **Request** - MÉTODO PATCH - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY *Payload：* **payload.json** ```json { "status":"accepted_by_requester", "financial": { "monthly_interest_rate": 0.01 } } ``` :::info 附加可选字段 除 `status` 和 `financial` 字段外，提案接受端点还接受以下可选字段： - **`borrower.document_identification_type`** (string 或 null)：身份证件类型 - **`borrower.document_identification_number`** (string，最多 16 个字符)：身份证件号码 - **`borrower.gender`** (string 或 null)：借款人性别。可接受值：`"male"`、`"female"` 或 `null` - **`credit_agent`** (对象)：信贷代理人，含 `name`（string，最多 100 个字符）和 `document_number`（string，11 或 14 位数字） ::: :::danger Atenção! 如果分期金额超过总可用金额（原始合同分期金额 + 福利总可用边际）， 将返回以下错误： ```json { "title": "Reservation amount greater than available total balance", "description": "The installment face value: 54.4 is greater than the available total balance (origin installment face value + available total balance):30.4. Available total balance: -20.0.", "translation": "O valor da parcela: 54.4 é maior que o valor total disponível (valor da parcela do contrato de origem + margem total disponível) : 30.4. Margem total diponível: -20.0.", "code": "SSC000059" } ``` 收到此错误后，可以重新调用接口，修改分期金额以适配总可用金额。 如果在未偿余额接受截止时间前未调整分期金额，则需要重新录入提案。 ::: 如果合作方决定不继续推进转移提案，则**必须**发起以下调用以告知放弃转移： **Request** - MÉTODO DELETE - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY Testar no Playground 向 CTC - CIP 发送转移提案取消后，将发送提案取消 webhook： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS canceled *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_status": "canceled", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12" } ``` :::info 未偿余额接受截止时间为 16:30。 无法恢复状态为 "canceled" 的提案。如果提案处于此状态，需要重新录入。 ::: **7.2.2. retained：** 当原始债权银行保留信贷时的提案状态，将发送包含保留信息的 webhook。原始债权银行在收到转移提案后，有最多 2 个工作日发送信贷保留响应。 **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS retained *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "retained", "event_datetime": "2022-11-24T15:42:12", "data": { "retained_reason": { "reason": "issuer_retention", "description": "Retenção do Cliente" } } } ``` ### 提案 webhook 字段详情 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|----------------------------------| | reason | 提案保留原因列表 | [枚举值](#retention_reason_enumerator) | **7.3. accepted_by_requester：** 经合作方批准后，提案进入 QI 内部结算流程。 **7.4. settlement_sent：** 完成 QI 内部转移提案结算流程后，用于支付未偿余额的资金将发送至原始债权方，并向合作方触发以下 webhook： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS settlement_sent *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "settlement_sent", "event_datetime": "2022-11-24T15:42:12", "data": { "receipt": { "amount": 1000, "timestamp": "2022-09-14 11:55:31", "description": "237 0001 1000093 1000093-3 59588111000103 - BCO BRADESCO S.A.", "ted_receipt_document_key": "a34e84a2-1628-4f23-8c11-2b2f4656ced1", "ted_receipt_url": "https://qitech.com.br/", "transaction_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf", "origin": { "account_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf", "bank_code": "329", "branch": "0001", "branch_digit": null, "account_number": "1000361", "account_digit": "3", "type": "checking_account", "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.", "document": "32402502000135" }, "destination": { "bank_code": "237", "branch": "0001", "branch_digit": null, "account_number": "1000093", "account_digit": "3", "type": "checking_account", "name": "BCO BRADESCO S.A.", "document": "59588111000103", "purpose": "Saída Liquidação de Portabilidade" } } } } ``` 此时将在 Dataprev 中启动转移操作的背书流程。背书流程将与以下步骤并行进行（第 7.5.、7.5.1. 和 7.5.2. 条）。 **7.5. pending_settlement_confirmation：** 在 QI 收到 CTC - CIP 的资金转移确认信息后，将触发此 webhook，提案将转为此状态。 **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS pending_settlement_confirmation *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "pending_settlement_confirmation", "event_datetime": "2022-11-24T15:42:12" } ``` :::info 原始债权机构将合同结清确认发送至 CTC - CIP，随后由 CTC - CIP 转发至 QI Tech。 O SLA 转移结清确认的 SLA 为 **2 个工作日**，从发送合同未偿余额支付资金起算。 ::: **7.5.1. paid：** 一旦 QI 收到 CTC - CIP 的合同结清确认，提案将转为 "paid" 状态，并向合作方发送 webhook。 **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS paid *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "paid", "event_datetime": "2022-11-24T15:42:12" } ``` 在此阶段，如果转移操作的背书已完成，合同将以 "paid" 状态结束；否则，合同将先转为 "pending_collateral_averbation" 状态，等待背书完成后再变为 "paid"。 **7.5.1.1.** 转移操作背书通知将通过以下 webhook 发送： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.collateral *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal.collateral", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "portability", "credit_operation_key": "\", "collateral_type": "social_security", "collateral_constituted": true, "collateral_data": { "reservation_method": "portability", } } } ``` data.collateral_data.reservation_method: [portability, new_credit ] **7.5.2. rejected:** 如果原始债权银行拒绝接受合同结清，发送用于结清合同未偿余额的资金将被退还给 QI Tech，提案将转为 "rejected" 状态。 **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS rejected *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "rejected", "event_datetime": "2022-11-24T15:42:12", "data": { "error": { "code": "QCTC0001", "reason": "Pagamento de portabilidade rejeitado." } } } ``` 如果在此阶段转移操作已在 Dataprev 中背书，再融资操作（找零）将可以启动（第 8 条中描述的流程）。 :::info 无法恢复状态为 "**rejected**" 的提案。始终需要重新录入。 ::: --- ## 8 - 再融资操作（找零）状态机： **8.1** 当转移操作付款完成时，合作方可以选择是否继续推进再融资操作（找零）。 #### Enumeradores credit_operation_status | Enumerador | Descrição | |-------------------------------------------|---------------------------------------| | waiting_signature | Operação aguardando assinatura | | signed | Operação assinada | | issued | Operação emitida | | disbursed | Operação desembolsada | | settled | Operação liquidada | | canceled | Operação cancelada | | canceled_permanently | Operação cancelada permanentemente | **8.1.1.** 要继续推进再融资（找零），合作方需发起以下调用并传递 'Financial' 和 'Disbursement Bank Accounts' 字段： *此外，可以传递 'purchaser_document_number' 字段以更改操作的受让方。 **Request** - MÉTODO POST - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/acceptance Testar no Playground **Request Body** ```json { "financial": { "installment_face_value": 379.87, "monthly_interest_rate": 0.0166, "number_of_installments": 84, "limit_days_to_disburse": 7, "disbursement_date": "2024-07-02", "rebates": [ { "rebate_bank_account": { "bank_code": "329", "account_digit": "9", "document_number": "18533555000164", "name": "Teste Ltda", "account_number": "4290002", "branch_number": "0001" }, "amount_type": "percentage", "fee_type": "spread", "amount": 9.5 }, { "amount": 20, "rebate_bank_account": { "name": "Teste Ltda", "document_number": "18533555000164", "account_digit": "0", "account_number": "4290001", "branch_number": "0001", "bank_code": "329" }, "amount_type": "percentage", "fee_type": "insurance_premium" } ] }, "disbursement_bank_accounts": [ { "document_number": "92093764000197", "branch_number": "0001", "name": "TESTE LTDA", "percentage_receivable": 100, "account_number": "120012", "account_digit": "3", "bank_code": "329" } ], "purchaser_document_number": "28534595027164" } ``` **Response:** **Response** ```json { "credit_operation_key": "\", "contract_number": "00000002", "document_key": "\", "document_url": "\", "credit_operation_status": "issued", "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-08-09", "calendar_days": 53, "digitable_line": null, "due_date": "2021-08-08", "due_interest": 0, "due_principal": 997.87, "fine_amount": null, "has_interest": true, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-09-08", "calendar_days": 31, "digitable_line": null, "due_date": "2021-09-08", "due_interest": 0, "due_principal": 690.8886500498395, "fine_amount": null, "has_interest": true, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "tax_amount": 0, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 50, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 997.87, "final_disbursement_amount": 100, "issue_amount": 1147.87, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }], "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "ispb": "00000000", "branch_number": "0001" } } ``` **8.1.2.** 如果合作方选择不继续推进再融资操作（找零），需发起以下调用以拒绝再融资提案： **Request** - MÉTODO DELETE - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation **8.2. 再融资背书（找零）：** 一旦合作方选择继续推进再融资操作，可分配边际背书流程将启动。一旦 INSS 可分配边际背书完成，合作方将收到以下 webhook： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.collateral **Body** ```json { "webhook_type": "credit_transfer.proposal.collateral", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "refinancing", "credit_operation_key": "\", "collateral_type": "social_security", "collateral_constituted": true } } ``` **8.3. 再融资放款（找零）：** 一旦 INSS 可分配边际完成背书，再融资操作将自动放款。 **8.3.1.** 如果找零放款成功，将向合作方发送以下 webhook： **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal.credit_operation", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_status": "disbursed", "credit_operation_type": "refinancing", "credit_operation_key": "\", "ted_receipt_list": [{ "fee": 0, "url": "https://qitech.com.br/", "amount": 500, "origin": { "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.", "type": "payment_account", "branch": "0001", "document": "32402502000135", "bank_code": "329", "account_key": "871059bd-4014-41ad-82b4-28275ff0e67b", "branch_digit": null, "account_digit": "5", "account_branch": "0001", "account_number": "00002" }, "timestamp": "2022-09-28T13:00:47", "description": "DESCRIPTION", "destination": { "name": "Elaine Isadora da Cruz", "type": "checking_account", "bank_code": "033", "branch": "0001", "purpose": "Crédito PIX em Conta", "document_number": "90406718261", "bank_ispb": "90400888", "branch_digit": null, "account_digit": "1", "account_number": "00001" }, "end_to_end_id": null, "transaction_key": "871059bd-4014-41ad-82b4-28275ff0e67b", "origin_transaction_key": null }] } } ``` **8.3.2.** 如果放款失败，合作方将收到以下 webhook： **7.3.2.1.** 放款账户失败 webhook **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation *Body:* **body.json** ```json { "webhook_type": "credit_transfer.proposal.credit_operation", "proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_status": "canceled", "credit_operation_type": "refinancing", "credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333", "pix_refusal": { "reason_enumerator": "invalid_document_number", "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino." }, "cancel_reason": "pix_refusal" } } ``` **7.3.2.2.** 再融资操作放款失败 webhook **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation *Body:* **body.json** ```json { "webhook": { "data": { "cancel_reason": "Agência ou Conta Destinatária do Crédito Inválida", "credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333", "credit_operation_type": "refinancing", "credit_operation_status": "canceled", "cancel_reason_enumerator": "agencia_conta_invalida" }, "proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999", "webhook_type": "credit_transfer.proposal.credit_operation", "event_datetime": "2023-12-22T10:15:25"     } } ``` **8.3.3.** 操作放款失败时，可以更改银行数据后重新尝试放款： **Request** - MÉTODO PATCH - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation Testar no Playground *Payload：* **payload.json** ```json { "disbursement_date": "2022-11-04", "disbursement_bank_account": { "account_branch": "1232", "account_digit": "4", "account_number": "412412412", "account_type": "checking_account", "document_number": "14950479032", "ispb": "17298092", "name": "Maria da Silva" } } ``` ## 9 - 查询 CTC - CIP 参与者列表： **Request** - MÉTODO GET - ENDPOINT /v2/credit_transfer/participants Testar no Playground *Response:* **response.json** ```json [ { "name": "\", "bank_code": "\", "ispb": "\" } ] ``` ## 10 - 获取最后一次请求的响应 last response 是一种简单直观的方式，用于映射 QI 与 Dataprev 之间通信的响应，可以了解该请求的发送时间及获得的返回结果（通过已列举的枚举值）。 每个枚举值都有详细描述和 Dataprev 参考代码。以下是此端点枚举值的详细信息。 ### 成功情况 #### Request - Credit Transfer ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral MÉTODO GET #### PATH PARAMETERS credit-operation-type | Enumerador | Descrição | |-------------------------------------------|--------------------------------| | refinancing_credit_operation | 再融资操作 | | portability_credit_operation | 转移操作 | #### Response Response Body ```json { "collateral_data":{ "benefit_number":1976703155, "state":"PI", "last_response":{ "success":[ { "enumerator":"succesfully_included", "reservation_method":"portability" } ] }, "last_response_event_datetime":"2023-05-22T19:13:02Z", "status":"reserved" }, "collateral_constituted":true, "collateral_type":"social_security" } ``` ### 请求返回字段详情 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](#dataprev_response_enumerator_success)| | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ### 错误情况 #### Request ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral MÉTODO GET #### Response Response Body ```json { "collateral_constituted": false, "collateral_type": "type", "updated_at": "2023-05-24 19:13:02", "collateral_data": { "state": "SP", "benefit_number": 1976703155, "status": "pending_reservation", "last_response": { "errors": [ { "enumerator": "benefit_blocked_by_tbm", "reservation_method" : "portability" }, { "enumerator": "benefit_blocked_by_tbm", "reservation_method" : "new_credit" } ] }, "last_response_event_datetime": "2023-05-22T19:13:02Z" } } ``` ### 失败 webhook 字段详情 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](#dataprev_response_enumerator_errors) | | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ## 11 - 最后一次背书尝试的响应 Webhook 如果操作背书失败，将进入重试流程，并发送以下 webhook（详细说明了 Dataprev 返回的错误）。 **Webhook 转移** WEBHOOK_TYPE credit_transfer.proposal.credit_operation ```json { "webhook_type": "credit_transfer.proposal.collateral", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "portability", "credit_operation_key": "\", "collateral_type": "social_security", "collateral_constituted": false, "collateral_data": { "status": "pending_reservation", "last_response": { "errors": [{ "enumerator": "consignable_margin_excceded" }] }, "last_response_event_datetime": "2023-05-22T19:13:02Z", "reservation_method": "new_credit", } } } ``` **Webhook refinanciamento** WEBHOOK_TYPE credit_operation.collateral ```json { "webhook_type": "credit_operation.collateral", "key": "\", "event_time": "2022-11-24T15:42:12", "data": { "collateral_type": "social_security", "collateral_constituted": false, "collateral_data": { "status": "pending_reservation", "last_response": { "errors": [{ "enumerator": "consignable_margin_excceded" }] }, "last_response_event_datetime": "2023-05-22T19:13:02Z", "reservation_method": "refinancing", } } } ``` ### 失败 webhook 字段详情 | 字段 | 描述 | 值 | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](#dataprev_response_enumerator_errors) | | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ## 12 - 查询原始转移数据 可以查询原始银行的转移数据，例如福利编号、开始日期、合同 CET（有效总成本）等信息。 **Request** - MÉTODO POST - ENDPOINT /social_security/reservation/external_key/CREDIT-OPERATION-KEY/portability_origin_contract *Payload：* **payload.json** ```json { "request_type":"portability_number", "portability_number": "202402070000298096242" } ``` **Response** - MÉTODO POST - ENDPOINT /social_security/reservation/external_key/CREDIT-OPERATION-KEY/portability_origin_contract *Body:* **body.json** ```json { "origin_contract_request_key": "9bb68c89-4b88-400d-9359-99ad8d42a69e", "status": "pending_search", "status_events": [ { "status": "pending_search" } ] } ``` 福利编号查询成功时 **Webhook** - WEBHOOK_TYPE social_security_portability_origin_contract_request - STATUS Success *Body:* **body.json** ```json { "webhook": { "key": "25e93655-4713-488b-8800-7ac4fddf745f", "data": { "portability_number": 9223372036854776000, "portability_status": "open", "benefit_number": 1544326820, "portability_start_date": "2024-02-22", "deleted_contracts": [ { "origin_bank": { "bank_code": 752, "name": "CETELEM-BNP" }, "contract_number": "22-844817807/20", "last_installment_paid": 84, "exclusion_date": "22022024", "period_amount": 165.73 } ] }, "status": "success", "webhook_type": "social_security_portability_origin_contract_request", "event_datetime": "2024-02-26T21:36:22" } } ``` 福利编号查询失败时 **Webhook** - WEBHOOK_TYPE social_security_portability_origin_contract_request - STATUS Failure *Body:* **body.json** ```json { "webhook": { "key": "522b5d7d-2dfc-4e92-99b7-d4df3d97edb2", "data": { "enumerator": "invalid_bank_code", "description": "Invalid bank code" }, "status": "failure", "webhook_type": "social_security_portability_origin_contract_request", "event_datetime": "2024-02-26T21:36:22" } } ``` ## 13. 降低分期金额 此端点允许 降低 信贷转移合同的分期金额。仅当原始合同中还有剩余分期且合同状态为 "disbursed" 时才有效。 **Request** - MÉTODO PUT - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation *Payload：* **payload.json** ```json { "installment_face_value": 382.18 } ``` **Response sucesso - HTTP 200** *Body:* **body.json** ```json { "credit_operation_key": "7aa77bca-c724-4c1a-bfae-9b1b7bd81ab2", "contract_number": "0000000007/WO", "document_key": "045a8f35-6170-4112-8d83-29a753d0c78e", "document_url": "http://teste.com", "signed_url": "signed_url_test", "credit_operation_status": "waiting_signature", "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_accounts": [ { "account_digit": "3", "account_branch": "0001", "account_number": "94134", "ispb": "32402502", "name": "Wilker Teste", "document_number": "37197645832" } ], "disbursement_options": [ { "prefixed_interest_rate": { "annual_rate": 3.0, "daily_rate": 0.00385824, "interest_base": "calendar_days", "monthly_rate": 0.12246205 }, "total_iof": 7.03, "external_contract_fee_amount": 0.0, "external_contract_fees": [], "contract_fee_amount": 0.0, "number_of_installments": 3, "contract_fees": [], "disbursed_issue_amount": 1000.0, "issue_amount": 1007.03, "disbursement_date": "2022-08-24", "cet": 12.6, "annual_cet": 315.3944, "installments": [ { "business_due_date": "2022-08-30", "calendar_days": 5, "due_date": "2022-08-29", "due_principal": 1007.03, "installment_number": 1, "pre_fixed_amount": 84.43554587915118, "principal_amortization_amount": 297.73445412084885, "total_amount": 382.17, "workdays": 3 }, { "business_due_date": "2022-09-30", "calendar_days": 31, "due_date": "2022-09-29", "due_principal": 709.2955458791512, "installment_number": 2, "pre_fixed_amount": 47.97894031795043, "principal_amortization_amount": 334.19105968204957, "total_amount": 382.17, "workdays": 22 }, { "business_due_date": "2022-11-01", "calendar_days": 32, "due_date": "2022-10-31", "due_principal": 375.1044861971016, "installment_number": 3, "pre_fixed_amount": 7.055513802898396, "principal_amortization_amount": 375.1044861971016, "total_amount": 382.16, "workdays": 21 } ], "final_disbursement_amount": 997.87 } ], "final_disbursement_amount": 997.87, "collateral_is_constituted": false } ``` ## 14. 枚举值映射 ### Enumeradores Retention Reason {#retention_reason_enumerator} | Enumerador | Descrição | |------------------------------------------|--------------------------------------------------------| | **issuer_retention** | 客户保留 | | **different_from_original** | 提案条件与原始合同不符 | | **issuer_lawsuit** | 客户存在诉讼 | | **insurance_in_progress** | 保险理赔进行中 | | **collateral_in_execution** | 担保执行中 | | **contract_not_found** | 合同未找到 | | **invalid_contract_type** | 合同类型无效 | | **portability_in_progress** | 转移进行中 | | **assigned_contract** | 已转让合同 | | **issuer_document_number_invalid** | CPF 不属于该合同 | | **unrelated_issuer_document_number** | 提供的 CPF 不是持有人的 | | **different_from_original** | Condições da proposta divergentes do contrato original | | **issuer_lawsuit** | Cliente com ação judicial | | **assigned_without_co_obligation** | 无共同义务的转让合同 | | **insurance_in_progress** | Indenização de seguro em andamento | | **collateral_in_execution** | Garantia em Execução | | **fgts_in_use** | FGTS AMORTIZAR 使用中 | | **fgts_funding** | FGTS funding | | **portability_not_requested** | 客户未申请转移 | | **wrong_original_financial_institution** | 原始债权机构错误 | ### Dataprev 背书错误返回表 {#dataprev_response_enumerator_errors} | Dataprev 代码 | 枚举值 | 描述 | QI 操作 | |-----------------|--------------------------------------------------|-------------------------------------------------------------|----------------------| | HW | consignable_margin_excceded | Exceeded consignable margin | Teimosinha | | IT | benefit_blocked_by_tbm | Benefit blocked due to benefit transfer | Teimosinha | | IE | benefit_blocked_by_beneficiary | Benefit blocked by beneficiary | Teimosinha | | AN | invalid_disbursement_account | Invalid disbursement bank account | Teimosinha | | HX | reservation_already_included | Reservation already included | 确认背书 | | IF | benefit_blocked_by_granting_process | Benefit blocked during granting process | Teimosinha | | AV | processing_payroll | Operation couldn`t be done during processing payroll period | Teimosinha | | OF | invalid_cbc | Invalid cbc | Teimosinha | | IA | first_name_mismatch | First name mismatch benefit owner or legal representative | Teimosinha | | OS | legal_representative_document_number_mismatch | Document number mismatch legal representative | Teimosinha | | AY | invalid_state | Invalid state | Teimosinha | | HZ | operation_not_allowed_on_this_reservation_status | Operation couldn`t be done with current reservation status | Teimosinha | | AP | invalid_contract_date | Accrual, end or start contract date is invalid | Teimosinha | | GA | required_fields_missing | Required fields are missing | Teimosinha | | BC | cbc_missing | CBC is missing | Teimosinha | | NC | contract_number_missing | Contract number is missing | Teimosinha | | NB | benefit_number_missing | Benefit number is missing | Teimosinha | | CA | invalid_bank_code | Invalid bank code | Teimosinha | | HR | exceeded_number_of_allowed_contracts | Amount of contracts is above the limit | Teimosinha | | PV | invalid_image_format | Image with wrong format | Teimosinha | | IR | operation_not_allowed_IR | Operation date is greater than benefit expiration | Teimosinha | | PK | wrong_bank_code_destination | Portability number was found with wrong bank code destination| Teimosinha | | PH | wrong_benefit_number_on_portability | Portability number was found with wrong benefit number | Teimosinha | | PI | invalid_contract_total_amount | Reservation contract total amount should be greater than Dataprev reference amount | Teimosinha | :::danger 注意！ 合同的所有利率和金额在创建预留时进行验证。 当合同长时间未背书时会出现 "invalid_contract_total_amount" 错误，这将影响先前确定的金额。 ::: ### 背书成功返回表 {#dataprev_response_enumerator_success} | Dataprev 代码 | 枚举值 | 描述 | |--------|--------------------------|-----------------------------------------| | BD | successfully_included | Inclusion has been successfully done | | BF | successfully_removed | Removal has been successfully done | | BR | successfully_reactivated | Reactivation has been successfully done | | BS | successfully_suspended | Suspension has been successfully done | ### 余额查询错误返回表 {#dataprev_balance_errors_enumerators} | 代码 | 枚举值 | 描述 | |--------|---------------------------------------|---------------------------------------------------------------------------------| | CR | not_found_legal_representative | no legal representative for the beneficiary | | CD | inexistent_beneficiary | no beneficiary found | | AS | benefity_without_legal_representative | beneficiary does not have a legal representative | | BI | inexistent_benefit | no benefit found | | D1 | inconsistent_balance_benefit_data | The balance benefit data registered is either inconsistent, null or incomplete. | ### 福利查询错误返回表 {#dataprev_benefits_errors_enumerators} | 代码 | 枚举值 | 描述 | |--------|---------------------------------------|---------------------------------------------------------------------------------| | CR | not_found_legal_representative | no legal representative for the beneficiary | | CD | inexistent_beneficiary | no beneficiary found | | AS | benefity_without_legal_representative | beneficiary does not have a legal representative | ### 福利状况表 {#benefit_situation_enumerator} | Items | |-------| | active | | excluded | | terminated | | suspended | | suspended_by_CONPAG | | terminated_by_SISOBI | | receiving_monthly_recover_6_months | | receiving_monthly_recover_18_months | | suspended_by_name_error | | suspended_by_credentialed_payer | | suspended_by_inspection | | suspended_by_audit | | terminated_by_inspection | | terminated_by_audit | | receiving_monthly_recover_6_months_inspection | | receiving_monthly_recover_18_months_inspection | | suspended_by_SISOBI | | canceled_by_audit | ### 福利状态表 {#benefit_status_enumerator} | 枚举值 | 描述 | |------------|-----------------------------------------------------| | Elegible | 符合贷款资格 | | Inelegible | 福利不符合贷款资格 | | Blocked | 福利符合资格，但贷款被封锁 | ### 封锁类型表 {#block_type_enumerator} | 枚举值 | 描述 | |------------|-----------------------------------------------------| | 0 | 无封锁 | | 1 | 被被保险人封锁 | | 2 | 因 TBM 被封锁 | | 3 | 在授权时被封锁 | ### 政治敏感人士类型表 {#politically_exposed_enumerator} | 枚举值 | 描述 | |------------|-----------------------------------------------------| | 0 | 非政治敏感人士 | | 1 | 政治敏感人士 - 第 1 级 | ### 福利类型表 {#benefit_type_enumerator} | 代码 | 福利 | | --- | ------------------------------------------------ | | 1 | pension_by_death_rural_worker | | 2 | pension_by_death_accident_rural_worker | | 3 | pension_by_death_rural_employer | | 4 | retirement_invalidity_rural_emploee | | 5 | retirement_invalidity_accident_rural_worker | | 6 | retirement_invalidity_rural_employer | | 7 | retirement_by_eldness_rural_worker | | 8 | retirement_by_age_rural_employer | | 9 | complement_by_work_accident_rural_worker | | 11 | support_invalidity_rural_worker | | 12 | support_by_age_rural_worker | | 13 | aid_sickness_rural_worker | | 15 | aid_time_off_rural_worker | | 16 | aid_federal | | 17 | international_agreement | | 18 | inclusion_benefit | | 19 | pension_student_law7004 | | 20 | pension_by_death_diplomat | | 21 | pension_by_death | | 22 | pension_by_death_statute | | 23 | pension_by_death_veteran | | 24 | pension_special_institutional_act | | 25 | aid_time_off | | 26 | pension_by_death_special_law593 | | 27 | pension_by_death_federal_emploee | | 28 | pension_by_death_general_regime_law20465 | | 29 | pension_by_death_marine_veteran | | 30 | monthly_income_lifetime_invalidity | | 31 | aid_sickness | | 32 | retirement_invalidity_social_security | | 33 | retirement_invalidity_aeronautic | | 34 | retirement_invalidity_marine_law1756 | | 35 | aid_sickness_veteran | | 36 | aid_social_security_accident | | 37 | retirement_capin_extra_emploee | | 38 | retirement_federal_extra_emploee | | 39 | aid_invalidity_student_law7004 | | 40 | monthly_income_lifetime_by_age_upper70_law6179 | | 41 | retirement_by_age | | 42 | retirement_by_contribution_time | | 43 | retirement_by_time_of_service_veteran | | 44 | retirement_special_aeronautic | | 45 | retirement_by_time_of_service_journalist | | 46 | retirement_special | | 47 | allowance_25 | | 48 | allowance_20 | | 49 | retirement_ordinary | | 50 | aid_sickness_extinct_basic_plan | | 51 | retirement_invalidity_extinct_basic_plan | | 52 | retirement_by_age_extinct_basic_plan | | 53 | aid_time_off_extinct_basic_plan | | 54 | pension_indemnity_federal | | 55 | pension_by_death_extinct_basic_plan | | 56 | pension_lifetime_syndrome_thalidomide | | 57 | retirement_by_teacher_labor_time | | 58 | retirement_anisty | | 59 | pension_by_death_amnesty | | 60 | indemnity | | 61 | aid_birth | | 62 | aid_funeral | | 63 | aid_funeral_rural_worker | | 64 | aid_funeral_rural_employer | | 65 | savings_special_autarchy | | 67 | savings_mandatory_ipase_law5128 | | 68 | savings_special_retirement_ps_affiliated_upper60 | | 69 | savings_student_law7004 | | 70 | restitution | | 71 | monthly_income | | 72 | retirement_by_time_of_service_law1756 | | 73 | monthly_income_family_statute | | 74 | complement_pension_federal | | 75 | complement_retirement_federal | | 76 | monthly_income_statute | | 77 | monthly_income_sinpas_family_statute | | 78 | retirement_by_age_law1756 | | 79 | advantage | | 80 | monthly_income_maternity | | 81 | compulsory_retirement | | 82 | retirement_by_time_of_service_sasse | | 83 | retirement_invalidity_ex_sasse | | 84 | pension_by_death_sasse | | 85 | pension_lifetime_rubber_tapper_law7986 | | 86 | pension_lifetime_rubber_tapper_dependent_law7986 | | 87 | continuous_aid_physical_disabilities | | 88 | continuous_aid_eldness | | 89 | pension_special_hemodialysis_victim_caruaru | | 90 | medic_assistency_work_accident | | 91 | aid_sickness_by_work_accident | | 92 | retirement_invalidity_work_accident | | 93 | pension_by_death_work_accident | | 94 | aid_work_accident | | 95 | aid_additional_work_accident | | 96 | pension_special_leprosy_law11520 | | 97 | savings_by_death_work_accident | | 98 | aid_longshoreman | | 99 | time_off_15 | ## 15. 场景模拟 ### 转移 **15.1.** 未偿余额申请 转移操作签名后，如果客户配置为手动发送，提案将创建为状态 "pending_submission"，只有在调用以下路由后，才会发起未偿余额申请。 如果配置为自动发送，提案将创建为状态 "pending_response"，即已在等待余额响应，无需调用此路由。 **Request** - ENDPOINT /v2/credit_transfer/proposal/PROPOSAL-KEY - MÉTODO PATCH *Payload：* **payload.json** ```json { "status": "pending_response" } ``` **15.2.** CTC 批准 提案必须处于 "pending_response" 状态。 **Request** - ENDPOINT /mock/credit_transfer/ctc - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "event_type": "proposal_creation_accepted" } ``` **15.3.** CTC 拒绝 提案必须处于 "pending_response" 状态。 **Request** - ENDPOINT /mock/credit_transfer/ctc - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "event_type": "proposal_creation_refused" } ``` **15.4.** 原始银行发送未偿余额 必须先发送 CTC 批准调用（**15.2**）。提案必须处于 "pending_acceptance" 状态。 调用此路由后，将收到 webhook 通知当前债务未偿余额；如要继续操作，需调用第（**7.2.1**）条中的路由 **Request** - ENDPOINT /mock/credit_transfer/ctc - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "event_type": "proposal_approval", "due_balance": 9000, // Opcional, se não informado será enviado o valor usado na criação da proposta "installment_face_value": 300, // Opcional, se não informado será enviado o valor usado na criação da proposta "installment_number": 40, // Opcional, se não informado será enviado o valor usado na criação da proposta "opened_installment_number": 35, // Opcional, se não informado será enviado igual ao installment_number "overdue_installment_number": 5 // Opcional, se não informado será enviado 0 } ``` **15.5.** 原始银行保留 必须先发送 CTC 批准调用（**15.2**）。提案必须处于 "pending_acceptance" 状态 **Request** - ENDPOINT /mock/credit_transfer/ctc - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "event_type": "proposal_retention" } ``` **15.6.** 原始银行退款 只能在提案被接受且转移操作已放款后发送。提案必须处于 "settlement_sent"、"pending_settlement_confirmation" 或 "paid" 状态。 **Request** - ENDPOINT /mock/credit_transfer/str - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "event_type": "payment_rejected" } ``` **15.7.** CTC 付款确认 提案必须已被接受且转移操作已放款。状态必须为 "settlement_sent"。 **Request** - ENDPOINT /mock/credit_transfer/ctc - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "event_type": "settlement_confirmation" } ``` **15.8.** 原始银行付款确认 必须在 CTC 付款确认（**15.7**）之后调用。提案必须处于 "pending_settlement_confirmation" 状态。 **Request** - ENDPOINT /mock/credit_transfer/ctc - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "event_type": "payment_confirmation" } ``` **15.9.** 担保背书 提案必须处于 "pending_settlement_confirmation" 或 "paid" 状态，且在 **15.7** 或 **15.8** 之后。 **Request** - ENDPOINT /mock/credit_transfer/collateral - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "credit_operation_type": "portability", "collateral_constituted": true } ``` ### 再融资 **15.10.** 担保背书 提案必须处于 "paid" 或 "pending_settlement_confirmation" 状态，且转移担保已被激活， 再融资必须已被接受。 **Request** - ENDPOINT /mock/credit_transfer/collateral - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "credit_operation_type": "refinancing", "collateral_constituted": true } ``` **15.11.** 担保背书失败 提案必须处于 "paid" 或 "pending_settlement_confirmation" 状态，且转移担保已被激活， 再融资必须已被接受。 **Request** - ENDPOINT /mock/credit_transfer/collateral - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "credit_operation_type": "refinancing", "collateral_constituted": false } ``` **15.12.** 放款失败 再融资操作必须已放款。 **Request** - ENDPOINT /mock/credit_transfer/disbursement - MÉTODO POST *Payload：* **payload.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "event_type": "disbursement_failed" } ``` ## 16. 在 QI 向合作方抵扣的转移操作中添加费用 要添加费用，操作必须已背书、已放款且未被转让。 ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation/rebate MÉTODO POST **Request** **payload.json** ```json { "amount": 20, "rebate_bank_account": { "name": "Teste Ltda", "document_number": "18533555000164", "account_digit": "0", "account_number": "4290001", "branch_number": "0001", "bank_code": "329" }, "amount_type": "percentage", "fee_type": "spread" } ``` **Response** **response.json** ```json {} ``` ## 17. 转移付款收据（STR00047） 转移付款完成后，可以生成交易收据。 ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /receipt_str0047 MÉTODO POST **Request** **payload.json** ```json {} ``` **Response** **response.json** ```json { "proposal_key": "CHAVE DA PROPOSTA", "receipt_url": "URL DO RECIBO", "receipt_document_key": "CHAVE DO RECIBO" } ``` --- # Envio de Documentos e Formalização URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/formalizacao Envio de Documentos e Formalização Envio dos dados complementares exigidos pela IN 138 do INSS e formalização da proposta de portabilidade e refinanciamento. ## Envio de documentos Segundo IN 138 do INSS é obrigatório o envio dos dados complementares do contrato. Os documentos devem ser enviados através do [endpoint de upload de documentos.](/documentation/upload_de_documentos/upload_de_documentos) e devem seguir a seguinte formatação: | Validações | Valores | |----------------|--------------| | Formato | JPEG | | Tamanho mínimo | 250 x 250 px | | Tamanho máximo | 2 MB | :::caution Atenção Contratos que tiverem documentos vinculados que não respeitam as regras de tamanho mínimo ou máximo serão cancelados permanentemente. ::: Caso as validações não sejam atendidas, no momento que o parceiro seguir com a proposta após receber o saldo devedor, iremos devolver os seguintes erros : **Ver exemplos de erro** **Formato inválido** ```json { "title": "Invalid document format", "description": "The document: document_identification_back should be in JPEG format.", "translation": "O documento: document_identification_back deve estar no formato JPEG.", "code": "SSC000061" } ``` **Tamanho inválido** ```json { "title": "Invalid document size", "description": "The document: document_identification_back should have at least 250x250px.", "translation": "O documento: document_identification_back deve ter no mínimo 250x250px.", "code": "SSC000060" } ``` Após o upload de documentos, as chaves dos documentos enviados devem ser informadas no payload de criação da proposta no tópico anterior dentro do campo *borrower* ou dentro do objeto de *related_parties** correspondente ao representante legal (*"role_type": "issuer_legal_representative"*): ```json { "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41", "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431", "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c" } ``` Ou ainda, após a criação da proposta, podem ser informadas através do seguinte endpoint: ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /related_party/ RELATED-PARTY-KEY /attached_document MÉTODO POST Testar no Playground Request Body ```json { "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41", "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431", "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c" } ``` :::info Informação A **related_party_key** é retornada na response da criação de dívida dentro do objeto **borrower** e dentro de cada uma das partes relacionadas dentro de **related_party_list** se for o caso. ::: ## Formalização da Proposta :::caution Atenção Para propostas que envolvam troco após o refinanciamento, é necessário o valor do troco calculado de acordo com as condições do contrato seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro: STATUS 400 **Response Body** ```json { "title": "Bad Request", "code": "CT000118", "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00." } ``` ::: Para formalização das operações de Portabilidade e/ou Refinanciamento (Troco), deve-se enviar as evidências de assinatura dos contratos gerados na digitação da Proposta. **No payload de assinatura devem conter os campos obrigatórios relacionados aos documentos enviados no item 5. Os campos obrigatórios são os seguintes: _ip_address_ e _signature_datetime_.** **6.1.** Para assinatura da Operação de Portabilidade o Parceiro deve realizar a seguinte chamada: **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation/signature Testar no Playground *Payload:* **payload.json** ```json { "type": "pdf-signature", "biometry_analysis_reference": "SERPRO", "signature_datetime": "2023-12-22T15:01:32.482Z", "signed_pdf_path": "https://termos-originacao.s3.amazonaws.com/5cd2a7f9", "ip_address": "179.145.48.219", "similarity_score": "0.9750000000000001" } ``` ## Enumeradores _Biometry Analysis Reference_ | Enumerador | Descrição | |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **serpro** | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro) | | **tse** | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE | | **not_found** | Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro. | A conclusão da assinatura será notificada de forma assíncrona: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation **body.json** ```json { "webhook_type": "credit_transfer.proposal.credit_operation", "proposal_key": "", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "portability", "credit_operation_key": "", "document_key": "", "signed_document_url": "", "credit_operation_status": "signed" } } ``` **6.2.** Para assinatura da Operação de Refinanciamento (Troco) o Parceiro deve realizar a seguinte chamada: **Request** - MÉTODO POST - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/signature Testar no Playground *Payload:* **payload.json** ```json { "type": "pdf-signature", "signed_pdf_path": "https://termos-originacao.s3.amazonaws.com/5cd2a7f9", "ip_address": "192.168.0.0", "signature_datetime": "2020-03-20T14:28:23.382748Z", "similarity_score": "0.98", "biometry_analysis_reference": "serpro" } ``` A conclusão da assinatura será notificada de forma assíncrona: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation **body.json** ```json { "webhook_type": "credit_transfer.proposal.credit_operation", "proposal_key": "", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "refinancing", "credit_operation_key": "", "document_key": "", "signed_document_url": "", "credit_operation_status": "signed" } } ``` --- # Máquinas de Status URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/maquinas-de-status Máquinas de Status — Port+Refin :::info Esta página descreve as máquinas de status que cobrem o que acontece **após a formalização da proposta**. Para o fluxo completo de digitação e pré-aprovação, consulte o [Fluxo Completo](./end-to-end). ::: ## Portabilidade — Máquina de Status ![Máquina de estados da proposta de portabilidade](/img/diagrams/inss-port-refin-maquinas-de-status-1.svg) Os estados da Proposta de Portabilidade refletem as etapas envolvidas no processo de portabilidade de crédito dentro do CTC (Central de Transferência de Crédito) da CIP. Segue abaixo a descrição do fluxo e do significado de cada status envolvido em uma Proposta de Portabilidade, desde sua digitação até sua liquidação. **7.1. pending_response:** Status da proposta após realização da digitação. Neste status a proposta foi recebida com sucesso pela QI e enviada para o CTC - CIP. **7.1.1 rejected:** Caso a digitação da proposta seja rejeitada pelo CTC - CIP, será enviado um webhook com o motivo da rejeição: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS rejected **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "rejected", "event_datetime": "2022-11-24T15:42:12", "data": { "error": { "code": "ECTC0023", "reason": "Contrato com portabilidade em andamento" } } } ``` **7.1.1 rejected reasons:** Caso a digitação da proposta seja rejeitada pelo CTC - CIP, será enviado um webhook com o motivo da rejeição: | reason | description | external_code | |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------| | portability_in_progress | Contrato com portabilidade em andamento | ECTC0023 | | portability_finished | Portabilidade já finalizada para o contrato informado | ECTC0028 | | portability_in_expiration_progress | Portabilidade não permitida. Contrato com portabilidade em situação de "Decurso de prazo" por não efetivação da portabilidade | ECTC0085 | | unexpected_error | Erro inesperado | ECTC9999 | | portability_payment_rejected | Pagamento de portabilidade rejeitado. | | | divergent_due_balance | Saldo devedor final deve ser menor que saldo devedor devolvido pela cip. | | **7.2. pending_acceptance:** Status da Proposta após envio/aceite pelo CTC - CIP. A Proposta, neste momento, está aguardando resposta de saldo devedor pelo banco credor original. Neste momento é enviado um webhook com o número da Portabilidade no CTC - CIP: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS pending_acceptance **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "pending_acceptance", "event_datetime": "2022-11-24T15:42:12", "data": { "portability_number": "202211230000246536429", "inclusion_date": "2022-11-24", "due_balance_expected_return_date": "2022-12-01" } } ``` :::info O **"portability_number"** é o Número da Portabilidade dentro do CTC - CIP, e é o número utilizado pela instituição proponente e instituição credora original para localizar a Proposta de Portabilidade. ::: Assim que o banco credor original responder à solicitação de portabilidade, será enviado um webhook com a resposta do valor do saldo devedor no caso da não retenção, e com a informação de "retido", no caso da retenção: **7.2.1. accepted:** Status da Proposta quando o banco credor original retorna o saldo devedor e não retem o crédito. Será enviado um webhook com a informação do saldo devedor. O banco credor original tem até 5 d.u. após a recepção da Proposta de Portabilidade, para envio da resposta com a informação do saldo devedor da operação. **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS accepted **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "accepted", "event_datetime": "2022-11-24T15:42:12", "data": { "final_due_balance": 1000, "portability_number": "202211230000246536429", "original_contract": { "origin_contract_number": "5584745", "origin_ispb_number": "60746948", "origin_document_number": "90406718261", "origin_operation_type": "0202", "installment_face_value": 1000, "total_iof": 1, "first_due_date": "2021-05-31", "last_due_date": "2022-05-31", "interest": 1, "cet": 1, "installment_number": 12, "amortization": 1, "final_due_balance": 1000, "final_due_date": "2021-08-31", "contract_date": "2021-04-31" } } } ``` Com a informação do saldo devedor retornado pela instituição credora original, o parceiro tomará a decisão se seguir ou não com a Portabilidade. :::info Horário limite para envio do saldo devedor pela instituição credora original é às 10:00. ::: Após o recebimento do saldo devedor, caso o Parceiro decida seguir com a Proposta Portabilidade, ele deve realizar a seguinte chamada: **Request** - MÉTODO PATCH - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY Testar no Playground *Payload:* **payload.json** ```json { "status":"accepted_by_requester" } ``` :::caution Atenção Para propostas que envolvam troco após o refinanciamento, é necessário que o valor do troco calculado de acordo com as novas condições do contrato após o retorno do saldo devedor seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro: STATUS 400 **Response Body** ```json { "title": "Bad Request", "code": "CT000118", "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00." } ``` ::: O Parceiro pode adicionar dados de novo valor de parcela ou nova taxa nessa chamada, caso queira alterá-los: **Request** - MÉTODO PATCH - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY *Payload:* **payload.json** ```json { "status":"accepted_by_requester", "financial": { "installment_face_value": 100 } } ``` **Request** - MÉTODO PATCH - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY *Payload:* **payload.json** ```json { "status":"accepted_by_requester", "financial": { "monthly_interest_rate": 0.01 } } ``` :::info Campos adicionais opcionais Além dos campos `status` e `financial`, o endpoint de aceite da proposta também aceita os seguintes campos opcionais: - **`borrower.document_identification_type`** (string ou null): Tipo do documento de identificação - **`borrower.document_identification_number`** (string, máx. 16 caracteres): Número do documento de identificação - **`borrower.gender`** (string ou null): Gênero do tomador. Valores aceitos: `"male"`, `"female"` ou `null` - **`credit_agent`** (objeto): Agente de crédito com `name` (string, máx. 100) e `document_number` (string, 11 ou 14 dígitos) ::: :::danger Atenção! Caso o valor da parcela seja maior que valor total disponível (valor da parcela do contrato de origem + margem total disponível do benefício), será retornado o seguinte erro: ```json { "title": "Reservation amount greater than available total balance", "description": "The installment face value: 54.4 is greater than the available total balance (origin installment face value + available total balance):30.4. Available total balance: -20.0.", "translation": "O valor da parcela: 54.4 é maior que o valor total disponível (valor da parcela do contrato de origem + margem total disponível) : 30.4. Margem total diponível: -20.0.", "code": "SSC000059" } ``` Ao receber esta crítica, é possível que uma nova chamada seja feita, alterando o valor da parcela para que ela se ajuste ao valor total disponível. Se o ajuste no valor da parcela não for feito até o horário limite para aceite do saldo devedor, será necessária uma nova digitação de proposta. ::: Caso o Parceiro decida por não prosseguir com a Proposta de Portabilidade, ele deve, **obrigatoriamente** realizar a seguinte chamada para informar a desistência da Portabilidade: **Request** - MÉTODO DELETE - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY Testar no Playground Após o envio do cancelamento da Proposta de Portabilidade ao CTC - CIP, será enviado um webhook de Proposta Cancelada: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS canceled **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_status": "canceled", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12" } ``` :::info O horário limite para aceite do saldo devedor é 16:30. Não é possível retomar uma Proposta com status "canceled". Caso a Proposta esteja com este status, será necessária a realização de uma nova digitação. ::: **7.2.2. retained:** Status da Proposta quando o banco credor original retem o crédito, será enviado o webhook com a informação de retenção. O banco credor original do crédito tem até 2 d.u. após a recepção da Proposta de Portabilidade, para envio da resposta de retenção do crédito. **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS retained **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "retained", "event_datetime": "2022-11-24T15:42:12", "data": { "retained_reason": { "reason": "issuer_retention", "description": "Retenção do Cliente" } } } ``` ### Detalhamento de campos no webhook de proposal | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | reason | lista dos motivos de retenção de uma Proposta | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#retention_reason_enumerator) | **7.3. accepted_by_requester:** Após aprovada pelo parceiro, a Proposta segue o fluxo interno da QI para liquidação. **7.4. settlement_sent:** Após conclusão do fluxo interno da QI para liquidação da Proposta de Portabilidade o recurso para pagamento do saldo devedor é enviado ao credor original disparando o seguinte webhook para o Parceiro: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS settlement_sent **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "settlement_sent", "event_datetime": "2022-11-24T15:42:12", "data": { "receipt": { "amount": 1000, "timestamp": "2022-09-14 11:55:31", "description": "237 0001 1000093 1000093-3 59588111000103 - BCO BRADESCO S.A.", "ted_receipt_document_key": "a34e84a2-1628-4f23-8c11-2b2f4656ced1", "ted_receipt_url": "https://qitech.com.br/", "transaction_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf", "origin": { "account_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf", "bank_code": "329", "branch": "0001", "branch_digit": null, "account_number": "1000361", "account_digit": "3", "type": "checking_account", "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.", "document": "32402502000135" }, "destination": { "bank_code": "237", "branch": "0001", "branch_digit": null, "account_number": "1000093", "account_digit": "3", "type": "checking_account", "name": "BCO BRADESCO S.A.", "document": "59588111000103", "purpose": "Saída Liquidação de Portabilidade" } } } } ``` Neste momento será iniciada averbação da Operação de Portabilidade na Dataprev. O processo de averbação acontecerá em paralelo aos itens seguintes (itens 7.5., 7.5.1. e 7.5.2.) **7.5. pending_settlement_confirmation:** Após a confirmação do envio dos recursos para pagamento do saldo devedor, é aguardada a confirmação da quitação do contrato por parte da Instituição Credora Original. Nesta etapa o Parceiro receberá o seguinte webhook: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS pending_settlement_confirmation **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "pending_settlement_confirmation", "event_datetime": "2022-11-24T15:42:12" } ``` :::info A confirmação da quitação do contrato é encaminhada pela Instituição Credora Original ao CTC - CIP e posteriormente encaminhado pelo CTC - CIP à QI. O SLA para confirmação da quitação da Portabilidade é de **2 d.u.** contados a partir do envio dos recursos para pagamento do saldo devedor do contrato original. ::: **7.5.1. paid:** Assim que a QI receber do CTC - CIP a confirmação da quitação do Contrato Original, a Proposta constará como paga e a Portabilidade estará finalizada. **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS paid **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "paid", "event_datetime": "2022-11-24T15:42:12" } ``` Nesta etapa, caso a averbação da Operação de Portabilidade já esteja concluída, a Operação de Refinanciamento (Troco), poderá ser iniciada (fluxo descrito no item 7). **7.5.1.1.** A notificação sobre a averbação da Operação de Portabilidade será enviada através do seguinte webhook: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.collateral **body.json** ```json { "webhook_type": "credit_transfer.proposal.collateral", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "portability", "credit_operation_key": "\", "collateral_type": "social_security", "collateral_constituted": true, "collateral_data": { "reservation_method": "portability", } } } ``` data.collateral_data.reservation_method: [portability, new_credit ] **7.5.2. rejected:** Caso o banco credor original rejeite a quitação do contrato, o recurso enviado para quitação do saldo devedor do contrato original será devolvido, e a proposta será finalizada. O parceiro receberá o webhook de **"rejected"**. **Webhook** - WEBHOOK_TYPE credit_transfer.proposal - STATUS rejected **body.json** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "\", "proposal_status": "rejected", "event_datetime": "2022-11-24T15:42:12", "data": { "error": { "code": "QCTC0001", "reason": "Pagamento de portabilidade rejeitado." } } } ``` Caso nesta etapa a Operação de Portabilidada já esteja averbada na Dataprev, será realizada a desaverbação da margem. :::info Não é possível retomar uma Proposta com status "**rejected**". É sempre necessário realizar uma nova digitação. ::: --- ## Refinanciamento (Troco) — Máquina de Status ![Máquina de estados da operação de refinanciamento](/img/diagrams/inss-port-refin-maquinas-de-status-2.svg) **8.1** No momento em que a Operação de Portabilidade é paga, o Parceiro pode optar por seguir com a Operação de Refinanciamento (Troco) ou não. #### Enumeradores credit_operation_status | Enumerador | Descrição | |-------------------------------------------|---------------------------------------| | waiting_signature | Operação aguardando assinatura | | signed | Operação assinada | | issued | Operação emitida | | disbursed | Operação desembolsada | | settled | Operação liquidada | | canceled | Operação cancelada | | canceled_permanently | Operação cancelada permanentemente | **8.1.1.** Para prosseguir com o Refinanciamento (Troco), o Parceiro deve realizar a seguinte chamada passando os campos 'Financial' e 'Disbursement Bank Accounts': *Adicionalmente, pode-se passar o campo 'purchaser_document_number' para alterar o cessionário da operação. **Request** - MÉTODO POST - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/acceptance Testar no Playground **Request Body** ```json { "financial": { "installment_face_value": 379.87, "monthly_interest_rate": 0.0166, "number_of_installments": 84, "limit_days_to_disburse": 7, "disbursement_date": "2024-07-02", "rebates": [ { "rebate_bank_account": { "bank_code": "329", "account_digit": "9", "document_number": "18533555000164", "name": "Teste Ltda", "account_number": "4290002", "branch_number": "0001" }, "amount_type": "percentage", "fee_type": "spread", "amount": 9.5 }, { "amount": 20, "rebate_bank_account": { "name": "Teste Ltda", "document_number": "18533555000164", "account_digit": "0", "account_number": "4290001", "branch_number": "0001", "bank_code": "329" }, "amount_type": "percentage", "fee_type": "insurance_premium" } ] }, "disbursement_bank_accounts": [ { "document_number": "92093764000197", "branch_number": "0001", "name": "TESTE LTDA", "percentage_receivable": 100, "account_number": "120012", "account_digit": "3", "bank_code": "329" } ], "purchaser_document_number": "28534595027164" } ``` **Response:** **Response** ```json { "credit_operation_key": "\", "contract_number": "00000002", "document_key": "\", "document_url": "\", "credit_operation_status": "issued", "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-08-09", "calendar_days": 53, "digitable_line": null, "due_date": "2021-08-08", "due_interest": 0, "due_principal": 997.87, "fine_amount": null, "has_interest": true, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "additional_costs": [], "bank_slip_key": null, "business_due_date": "2021-09-08", "calendar_days": 31, "digitable_line": null, "due_date": "2021-09-08", "due_interest": 0, "due_principal": 690.8886500498395, "fine_amount": null, "has_interest": true, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "installment_status": "created", "installment_type": "principal", "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "tax_amount": 0, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 50, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 997.87, "final_disbursement_amount": 100, "issue_amount": 1147.87, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }], "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "ispb": "00000000", "branch_number": "0001" } } ``` **8.1.2.** Caso o Parceiro opte por não prosseguir com a Operação de Refinanciamento (Troco), ele deve realizar a seguinte chamada: **Request** - MÉTODO DELETE - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation **8.2. Averbação do Refinanciamento (Troco):** Assim que o Parceiro optar por prosseguir com a Operação de Refinanciamento, a rotina para averbação da margem consignável terá início. Assim que a averbação da margem consignável do INSS for concluída o parceiro recebera o seguinte webhook: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.collateral **Body** ```json { "webhook_type": "credit_transfer.proposal.collateral", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_type": "refinancing", "credit_operation_key": "\", "collateral_type": "social_security", "collateral_constituted": true } } ``` **8.3. Desembolo do Refinanciamento (Troco):** Assim que a averbação da margem consignável do INSS for concluída a operação estará pronta para desembolso. No desembolso da Operação de Refinanciamento, a Operação de Portabilidade será quitada e caso exista valor desembolsado remanescente (**7.1.1. "disbursement_options.final_disbursement_amount"**), este valor será liberado para o cliente (Troco) na conta para desembolso da Operação (**"disbursement_bank_account"**). A liberação do troco para o cliente pode ser realizada via PIX ou TED, em qualquer horário do dia (obedecendo horário comercial de 7:00 às 17:00 em dias úteis, no caso da TED). **8.3.1.** Caso o desembolso do troco para o cliente seja bem sucedido, será enviado um webhook com os dados da comprovação do desembolso: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation **body.json** ```json { "webhook_type": "credit_transfer.proposal.credit_operation", "proposal_key": "\", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_status": "disbursed", "credit_operation_type": "refinancing", "credit_operation_key": "\", "ted_receipt_list": [{ "fee": 0, "url": "https://qitech.com.br/", "amount": 500, "origin": { "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.", "type": "payment_account", "branch": "0001", "document": "32402502000135", "bank_code": "329", "account_key": "871059bd-4014-41ad-82b4-28275ff0e67b", "branch_digit": null, "account_digit": "5", "account_branch": "0001", "account_number": "00002" }, "timestamp": "2022-09-28T13:00:47", "description": "DESCRIPTION", "destination": { "name": "Elaine Isadora da Cruz", "type": "checking_account", "bank_code": "033", "branch": "0001", "purpose": "Crédito PIX em Conta", "document_number": "90406718261", "bank_ispb": "90400888", "branch_digit": null, "account_digit": "1", "account_number": "00001" }, "end_to_end_id": null, "transaction_key": "871059bd-4014-41ad-82b4-28275ff0e67b", "origin_transaction_key": null }] } } ``` **8.3.2.** Caso ocorra falha no desembolso, o parceiro receberá o seguinte webhook: **7.3.2.1.** Falha no desembolso via PIX: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation **body.json** ```json { "webhook_type": "credit_transfer.proposal.credit_operation", "proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999", "event_datetime": "2022-11-24T15:42:12", "data": { "credit_operation_status": "canceled", "credit_operation_type": "refinancing", "credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333", "pix_refusal": { "reason_enumerator": "invalid_document_number", "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino." }, "cancel_reason": "pix_refusal" } } ``` **7.3.2.2.** Falha no desembolso via TED: **Webhook** - WEBHOOK_TYPE credit_transfer.proposal.credit_operation **body.json** ```json { "webhook": { "data": { "cancel_reason": "Agência ou Conta Destinatária do Crédito Inválida", "credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333", "credit_operation_type": "refinancing", "credit_operation_status": "canceled", "cancel_reason_enumerator": "agencia_conta_invalida" }, "proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999", "webhook_type": "credit_transfer.proposal.credit_operation", "event_datetime": "2023-12-22T10:15:25" } } ``` **8.3.3.** No caso de falha no desembolso da Operação, o desembolso pode ser retentato alterando-se os dados bancários: **Request** - MÉTODO PATCH - ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation Testar no Playground *Payload:* **payload.json** ```json { "disbursement_date": "2022-11-04", "disbursement_bank_account": { "account_branch": "1232", "account_digit": "4", "account_number": "412412412", "account_type": "checking_account", "document_number": "14950479032", "ispb": "17298092", "name": "Maria da Silva" } } ``` --- # Digitação da Proposta URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/proposta Digitação da Proposta Cria a proposta de portabilidade (com ou sem refinanciamento do Troco) em `POST /v2/credit_transfer/proposal`, recupera e corrige os dados da proposta. Para acompanhar os status depois da formalização, veja [Máquinas de Status](/documentation/guides/INSS/portability+refinancing/maquinas-de-status). :::caution Atenção Para que os pedidos de averbação, tanto da portabilidade, como do refinanciamento sejam criados com sucesso, é preciso que seja feita uma consulta de dados válida para o benefício **previamente**. Para isso basta seguir os passos do item [2 - Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio). ::: :::info Assinatura em grupo (opcional) Para reunir esta proposta com outras operações INSS do **mesmo beneficiário** e coletar **uma única assinatura**, envie `document_batch_group_key` na **raiz** do payload de criação da proposta. Nesse caso, a resposta **não retorna** `signature_information` — o link de assinatura é único e obtido no envio do grupo para assinatura. Consulte o fluxo de [Assinatura em grupo](/documentation/guides/INSS/signatures/batch-group-signature). ::: ## Falha na averbação por falta de uma consulta de dados válida do benefício Se uma consulta dos dados do benefício não for realizada com sucesso antes do pedido de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro" e será enviado um webhook no seguinte formato para informar o ocorrido: WEBHOOK_TYPE social_security_success_balance_request_not_found STATUS Pending requester action Webhook Body ```json { "webhook": { "key": "", "data": { "enumerator": "success_balance_request_not_found", "description": "Success balance request not found for the specified benefit number" }, "status": "pending_requester_action", "webhook_type": "social_security_success_balance_request_not_found", "event_datetime": "2024-02-26T21:36:22" } } ``` Para prosseguir, as seguintes ações deverão ser tomadas: 1. Realizar a consulta dos dados do benefício em questão seguindo os passos do item 2 - [Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio); 2. Enviar uma requisição no formato abaixo para informar que a consulta foi realizada. ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /validate_reservation MÉTODO POST Testar no Playground :::info Importante Essa requisição não apenas confirma a existência de uma consulta válida dos dados do benefício, mas também verifica se as informações enviadas para a criação da averbação estão corretas, permitindo assim a continuidade do processo. ::: :::warning CIN — Carteira de Identidade Nacional O campo `document_identification_type` agora aceita o valor `cin` (Carteira de Identidade Nacional). Quando utilizado, o campo `document_identification_number` **deve ser igual ao CPF** do portador (`individual_document_number`). O número do CIN é o próprio CPF. Valores aceitos em `document_identification_type`: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. **Atenção:** o envio do documento de identificação (`document_identification`) passará a ser **obrigatório** nas operações de portabilidade INSS. Comunique seus integradores com antecedência. ::: **4.1. Digitação da Proposta de Portabilidade com Refinanciamento:** Essa forma de digitação é utilizada para realizar a portabilidade de um contrato de crédito, liberando, ao final, mais dinheiro para o devedor. O valor liberado após a portabilidade é chamado de "Troco". A Proposta de Portabilidade e a Proposta de Refinanciamento podem ser geradas em uma mesma Request. Para a digitação da proposta devem ser enviadas as seguintes informações: - Dados cadastrais do tomador do crédito. - Dados cadastrais do Representante Legal (caso aplicável). - Dados financeiros da operação de portabilidade informando sempre o número de parcelas e uma das opções entre taxa de juros e valor de face da parcela. - Dados financeiros da operação de refinanciamento (operação que quita a operação de portabilidade e libera o troco) juntamente com os dados de conta bancária para pagamento do troco, conforme retornado na consulta dos dados do benefício. - Agente de crédito responsável pela originação da proposta, também conhecido como 'pastinha. - Saldo devedor, número do contrato original e ispb do credor original. Como a operação de Refinanciamento não possui data de desembolso fixa, a mudança na data de desembolso altera os valores da operação, sendo necessário informar se a taxa ("**monthly_interest_rate**") deve ser fixa ou se o valor liberado ao cliente ("**disbursed_amount**") deve ser fixo. **Caso a proposta seja de cliente analfabeto, os dados do rogado e testemunhas devem ser enviados no campo additional_data do payload de criação da proposta. Porém, deve ser previamente alinhado com a QI Tech quais informações e formato serão utilizados** :::danger Documento de identificação obrigatório (a partir de 03/08/2026) A Núclea passará a exigir o documento de identificação do tomador no registro da portabilidade a partir de **06/08/2026**. Por isso, a partir de **segunda-feira, 03/08/2026**, `borrower.document_identification_type` e `borrower.document_identification_number` passam a ser **obrigatórios** na digitação da proposta — propostas sem esses campos retornam erro. Quando `document_identification_type` for `cin`, o `document_identification_number` **pode** ser igual ao `individual_document_number` (CPF), já que a CIN usa o número do CPF. Para os demais tipos (`rg`, `cnh`), enviar o CPF em `document_identification_number` retorna erro. ::: ### Documento de identificação do tomador | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `borrower.document_identification_type` | string | ✅ | Tipo do documento de identificação. Valores: `rg`, `cnh`, `cin`. | | `borrower.document_identification_number` | string (máx. 16) | ✅ | Número do documento informado em `document_identification_type`. Igual ao CPF **somente** quando o tipo for `cin`. | | `borrower.document_identification_date` | string | — | Data de emissão do documento (`YYYY-MM-DD`). | Os mesmos campos existem em cada item de `related_parties` (representante legal) e seguem a mesma regra de preenchimento. **Ver exemplos de payload (Taxa Fixa / Valor Liberado Fixo)** **Com Taxa Fixa** **4.1.1. Digitação da Proposta de Portabilidade com Refinanciamento com taxa fixa:** Segue abaixo, exemplo de digitação da proposta fixando a taxa da operação: **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal Testar no Playground *Payload:* **Sem Registro na C3** ```json title='Request Body' { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Marilene da Silva", "mother_name": "Maria Mariane", "birth_date": "1990-05-06", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "20676928013", "document_identification_number": "381803326", // obrigatório "document_identification_type": "rg", // obrigatório — rg | cnh | cin "document_identification_date": "2019-01-28", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "912828135" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Águas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [ { "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "20676928013", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" } ], "collaterals": [ { "collateral_type": "social_security", "collateral_data": { "benefit_number": "22255220", "state": "SP", "subcorban_document_number": "12123456000101" } } ], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "300523588BF" }, "refinancing_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "installment_face_value": 100, "number_of_installments": 10 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "000059923", "ispb": "341", "bank_code": "341", "branch_number": "0155" }, "contract_number": "200523588BF" }, "origin_contract": { "ispb": "60746948", "contract_number": "558472", "last_due_balance": 997.87 }, "additional_data": {} } ``` **Com Registro na C3** ```json title='Request Body' { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Marilene da Silva", "mother_name": "Maria Mariane", "gender": "female", "birth_date": "1990-05-06", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "20676928013", "document_identification_number": "381803326", // obrigatório "document_identification_type": "rg", // obrigatório — rg | cnh | cin "document_identification_date": "2019-01-28", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "912828135" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Águas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [ { "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "20676928013", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" } ], "collaterals": [ { "collateral_type": "social_security", "collateral_data": { "benefit_number": "22255220", "state": "SP", "subcorban_document_number": "12123456000101" } } ], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "300523588PF" }, "refinancing_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "installment_face_value": 100, "number_of_installments": 10 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "000059923", "ispb": "341", "bank_code": "341", "branch_number": "0155" }, "contract_number": "200523588PK" }, "origin_contract": { "ispb": "60746948", "contract_number": "558472", "last_due_balance": 997.87 }, "additional_data": {} } ``` :::info Carência Conforme mudança da IN 204, a partir de 19/05, as operações poderão ter carência. Para tal, basta digitar dentro do "**collateral_data**" o campo "**number_of_grace_periods**". contendo o valor do número de meses desejados de carência, como no exemplo abaixo: ```json "collaterals": [ { "collateral_type": "social_security", "collateral_data": { "benefit_number": "22255220", "state": "RS", "number_of_grace_periods": 3, "subcorban_document_number": "12123456000101" } } ] ``` ::: :::caution Atenção A lista "**related_parties**", só deve ser enviada caso seja uma operação com Representante Legal. Quando enviado, deve conter os dados cadastrais do representante legal e o campo "**role_type**" deve ser enviado contendo o valor: "**issuer_legal_representative**". ::: :::info No campo "**origin_contract.ispb**" é informado o **ISPB** da instituição Credora Original. O **ISPB** é a base do CNPJ da instituição. Para ter acesso à lista completa de **ISPB's** de cada instituição participante do CTC - CIP (Central de Transferência de Crédito), basta utilizar o endpoint de consulta de participantes do CTC (índice): ::: **Com Valor Liberado Fixo** **4.1.2. Digitação da Proposta de Portabilidade com Refinanciamento com valor liberado fixo:** Segue abaixo, exemplo de digitação da proposta fixando o valor liberado ao cliente: **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal *Payload:* **Sem Registro na C3** ```json title='Request Body' { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Elaine Isadora da Cruz", "mother_name": "Maria Mariane", "birth_date": "1990-05-06", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "90406718261", "document_identification_number": "381803326", // obrigatório "document_identification_type": "rg", // obrigatório — rg | cnh | cin "document_identification_date": "2019-01-28", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "996363253" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Aguas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [{ "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "45102538004", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" }], "collaterals": [{ "collateral_type": "social_security", "collateral_data": { "benefit_number": "12345678", "state": "SP", "subcorban_document_number": "12123456000101" } }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "3635259610" }, "refinancing_credit_operation": { "financial": { "disbursed_amount": 1000, "installment_face_value": 110, "number_of_installments": 10 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" }, "contract_number": "3635259632" }, "origin_contract": { "ispb": "60746948", "contract_number": "5584745", "last_due_balance": 800 }, "additional_data": {} } ``` **Com Registro na C3** ```json title='Request Body' { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Elaine Isadora da Cruz", "mother_name": "Maria Mariane", "birth_date": "1990-05-06", "gender": "female", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "90406718261", "document_identification_number": "381803326", // obrigatório "document_identification_type": "rg", // obrigatório — rg | cnh | cin "document_identification_date": "2019-01-28", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "996363253" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Aguas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [{ "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "45102538004", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" }], "collaterals": [{ "collateral_type": "social_security", "collateral_data": { "benefit_number": "12345678", "state": "SP", "subcorban_document_number": "12123456000101" } }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "3635259611" }, "refinancing_credit_operation": { "financial": { "disbursed_amount": 1000, "installment_face_value": 110, "number_of_installments": 10 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" }, "contract_number": "3635259663" }, "origin_contract": { "ispb": "60746948", "contract_number": "5584745", "last_due_balance": 800 }, "additional_data": {} } ``` **4.1.3. Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal **body.json** ```json { "borrower": { "individual_document_number": "90406718261", "name": "Elaine Isadora da Cruz", "related_party_key": "d7f84a9d-28ba-4355-8e5e-a436ff4c3c2d", "role_type": "issuer" }, "portability_credit_operation": { "collateral_is_constituted": false, "contract_number": "3635259611", "credit_operation_key": "235ce3a5-eea1-4b13-9335-3de577318f8b", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.17295, "cet": 0.0134, "contract_fee_amount": 0.0, "contract_fees": [ { "amount": 0.5, "amount_type": "percentage", "fee_amount": 0.0, "fee_type": "tac" } ], "disbursed_issue_amount": 800.0, "disbursement_date": "2023-12-22", "external_contract_fee_amount": 0.0, "external_contract_fees": [ { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "spread", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "tac", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "insurance_premium", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 } ], "installments": [ { "business_due_date": "2024-02-22", "calendar_days": 62, "due_date": "2024-02-22", "due_principal": 800.0, "installment_number": 1, "pre_fixed_amount": 21.977846031814607, "principal_amortization_amount": 65.21215396818539, "total_amount": 87.19, "workdays": 40 }, { "business_due_date": "2024-03-22", "calendar_days": 29, "due_date": "2024-03-22", "due_principal": 734.7878460318146, "installment_number": 2, "pre_fixed_amount": 9.373907348762184, "principal_amortization_amount": 77.81609265123781, "total_amount": 87.19, "workdays": 21 }, { "business_due_date": "2024-11-22", "calendar_days": 31, "due_date": "2024-11-22", "due_principal": 86.03031050776795, "installment_number": 10, "pre_fixed_amount": 1.1637189988799015, "principal_amortization_amount": 86.0262810011201, "total_amount": 87.19, "workdays": 22 } ], "issue_amount": 800.0, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17042118, "daily_rate": 0.00043722, "interest_base": "calendar_days", "monthly_rate": 0.0132 }, "total_iof": 0.0 } ], "document_key": "c4cedeaf-23bf-450d-9fba-5ec6b5d45afb", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c4cedeaf-23bf-450d-9fba-5ec6b5d45afb/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-3635259611.pdf", "final_disbursement_amount": 0.0 }, "proposal_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497", "proposal_number": "17032782193414588", "proposal_status": "pending_submission", "refinancing_credit_operation": { "collateral_is_constituted": false, "contract_number": "3635259663", "credit_operation_key": "f73ba4d2-cd0a-4405-a47e-a51f325a9756", "credit_operation_status": "waiting_signature", "disbursement_accounts": [ { "account_branch": "0001", "account_digit": "1", "account_number": "00001", "bank_code": "033" } ], "disbursement_options": [ { "annual_cet": 0.193423, "cet": 0.0148, "contract_fee_amount": 1.03, "disbursed_issue_amount": 1000.0, "disbursement_date": "2023-12-22", "issue_amount": 1005.24, "number_of_installments": 10, "final_disbursement_amount": 200.0 } ], "document_key": "f4dfb505-3cec-4a97-9b16-dadc39bb4c7e", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/f4dfb505-3cec-4a97-9b16-dadc39bb4c7e/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-3635259663.pdf", "final_disbursement_amount": 200.0 }, "related_party_list": [ { "individual_document_number": "45102538004", "name": "Nome Representante Legal", "related_party_key": "632fa6c5-40e8-4e76-862e-e10951ed8bff", "role_type": "issuer_legal_representative" } ] } ``` Segue abaixo definições e descrições de alguns campos retornados na resposta da digitação da Proposta: **[A]**: ***"portability_credit_operation.disbursement_options.iof_amount"***: Na Operação de Portabilidade o IOF sempre será zero. **[B]**: ***"portability_credit_operation.disbursement_options.disbursed_issue_amount"***: É igual ao valor do saldo devedor do Contrato Original. **[C]**: ***"portability_credit_operation.disbursement_options.issue_amount"***: É o valor da Operação de Portabilidade. :::tip Relação [C] = [A] + [B] ::: **[D]**: ***"refinancing_credit_operation.disbursement_options.iof_amount"***: Valor de IOF da Operação de Refinanciamento (Troco). **[E]**: ***"refinancing_credit_operation.disbursement_options.disbursed_issue_amount"***: É o valor destinado à quitação do saldo devedor da Operação de Portabilidade. :::tip Relação [E] = [C] ::: **[F]**: **"refinancing_credit_operation.disbursement_options.final_disbursement_amount"**: É o valor do Troco liberado para o cliente na conta de desembolso informada no momento da digitação da Proposta (deve ser a conta informação da consulta dos dados do benefício). **[G]**: **"refinancing_credit_operation.disbursement_options.issue_amount"**: É o valor do Refinanciamento. :::tip Relação {"\n"} [G] = [F] + [E] + [D] {"\n"} ::: Os campos "**portability_credit_operation.disbursement_options.collateral_constituted**" e "**refinancing_credit_operation.disbursement_options.collateral_constituted**" informam se a margem do cliente esta averbada na Dataprev. O processo de averbação da Portabilidade será iniciado assim que os recursos para quitação do contrato original forem enviados a Instituição Credora Original (Item **6.4.**). O Processo de averbação do Refinanciamento é iniciado no momento em que o Parceiro decide por prosseguir com a Operação de Refinanciamento (Item **7.1.1.** e **7.2.**). **4.2. Digitação da Proposta de Portabilidade:** A Proposta de Portabilidade (Portabilidade Pura) deve ser digitada de forma semelhante ao descrito no item 4.1.1, porém deve ser enviada sem o objeto **"refinancing_credit_operation"**. **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal **body.json** ```json { "proposal_type": "inss", "purchaser_document_number": "32402502000135", "credit_agent": { "document_number": "87237271016", "name": "Agente de credito" }, "borrower": { "person_type": "natural", "name": "Elaine Isadora da Cruz", "mother_name": "Maria Mariane", "birth_date": "1990-05-06", "gender": "female", "profession": "Desenvolvedora", "nationality": "Brasileira", "marital_status": "single", "is_pep": false, "individual_document_number": "90406718261", "document_identification_number": "381803326", // obrigatório "document_identification_type": "rg", // obrigatório — rg | cnh | cin "document_identification_date": "2019-01-28", "email": "elaineisadoradacruz@hotmal.com", "phone": { "country_code": "055", "area_code": "11", "number": "996363253" }, "address": { "street": "Passagem Mariana", "state": "PA", "city": "Ananindeua", "neighborhood": "Aguas Lindas", "number": "660", "postal_code": "67118003", "complement": "complemento" }, "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d", "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a", "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076" }, "related_parties": [{ "name": "Nome Representante Legal", "email": "email@email.com.br", "birth_date": "2000-12-12", "is_pep": false, "mother_name": "maria", "phone": { "number": "991294043", "area_code": "11", "country_code": "055" }, "address": { "street": "Avenida das Castanheiras", "state": "SP", "city": "Brasília", "neighborhood": "bairro", "number": "12", "postal_code": "71900100", "complement": "" }, "role_type": "issuer_legal_representative", "person_type": "natural", "individual_document_number": "45102538004", "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650", "document_identification_type": "rg", "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b", "document_identification_number": "123456789", "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1" }], "collaterals": [{ "collateral_type": "social_security", "collateral_data": { "benefit_number": "12345678", "state": "SP", "subcorban_document_number": "12123456000101" } }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 }, "contract_number": "1020252636" }, "origin_contract": { "ispb": "60746948", "contract_number": "558474520", "last_due_balance": 800 }, "additional_data": {} } ``` **Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal *Payload:* **payload.json** ```json { "borrower": { "individual_document_number": "90406718261", "name": "Elaine Isadora da Cruz", "related_party_key": "f9fbaa93-4d57-494f-b60f-dcba8cb64a45", "role_type": "issuer" }, "portability_credit_operation": { "collateral_is_constituted": false, "contract_number": "1020252636", "credit_operation_key": "1cd34a63-5a61-49a3-90a5-7a515ee98932", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.17295, "cet": 0.0134, "disbursed_issue_amount": 800.0, "disbursement_date": "2023-12-22", "issue_amount": 800.0, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17042118, "daily_rate": 0.00043722, "interest_base": "calendar_days", "monthly_rate": 0.0132 }, "total_iof": 0.0 } ], "document_key": "2f9ac920-a5e8-4386-b049-dc971e1fc20b", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/2f9ac920-a5e8-4386-b049-dc971e1fc20b/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-1020252636.pdf", "final_disbursement_amount": 0.0 }, "proposal_key": "9661aef8-e897-4405-a44f-ca8a43d9cee3", "proposal_number": "17032785232138245", "proposal_status": "pending_submission", "related_party_list": [ { "individual_document_number": "45102538004", "name": "Nome Representante Legal", "related_party_key": "c8166f37-b496-455a-96e7-f75e24f084a1", "role_type": "issuer_legal_representative" } ] } ``` ### 4.3. Recuperando dados de uma proposta ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY ou REQUESTER-CONTROL-KEY MÉTODO GET #### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---| ---| ---| | `proposal_key` | string | Chave identificadora da proposta | - | | `requester_control_key` | string | Chave identificadora do cliente para recuperar os dados de uma proposta (casos de timeout ou operação duplicada), enviar no lugar da proposal_key | - | *Response:* **response.json** ```json { "borrower": { "address": { "city": "SAO PAULO", "complement": "Moradia", "neighborhood": "CENTRO", "number": "10", "postal_code": "01153000", "state": "SP", "street": "RUA CENTRAL" }, "birth_date": "1976-05-25", "document_identification_number": "306385466", "email": "ivanete@windowslive.com", "individual_document_number": "25500337874", "is_pep": false, "marital_status": "single", "mother_name": "EDITE MARIA DANTAS", "name": "IVANETE SATURNINO DE SOUZA", "nationality": "Brasleira", "person_type": "natural", "phone": { "area_code": "11", "country_code": "055", "number": "985814768" }, "profession": "Aposentado", "related_party_key": "511d7186-3c17-4f35-8887-c4aefaf270be", "role_type": "issuer" }, "collaterals": [ { "collateral_data": { "benefit_number": 2045043317, "state": "SP" }, "collateral_type": "social_security" } ], "origin_operation": { "contract_date": "2025-06-02", "contract_number": "0123489618691", "financial_institution_code_number": "237", "installment_number": 84, "ispb_number": "60746948", "last_due_balance": 17879.22, "opened_installment_number": 67, "overdue_installment_number": 0 }, "portability_credit_operation": { "collateral_is_constituted": false, "contract_number": "CTC0000024971", "credit_operation_key": "e5bfbd28-0144-4eaa-b7f1-d0efb0b6b155", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.2321, "cet": 0.0175, "disbursed_issue_amount": 17879.22, "disbursement_date": "2025-06-02", "issue_amount": 17879.22, "number_of_installments": 67, "prefixed_interest_rate": { "annual_rate": 0.2285378296, "daily_rate": 0.0005718988, "interest_base": "calendar_days", "monthly_rate": 0.0173 }, "total_iof": 0 } ], "document_key": "f85d9799-e29f-4133-80c3-3e95f16f2a54", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/f85d9799-e29f-4133-80c3-3e95f16f2a54/MMRIOLTDA-IVANETESATURNINODESOUZA-CCB-CTC0000024971.pdf", "final_disbursement_amount": 17879.22 }, "proposal_key": "1e1d3f4d-21aa-4b6f-8515-6d978dc2afa5", "proposal_number": "17488903030996687", "proposal_status": "pending_submission", "refinancing_credit_operation": { "collateral_is_constituted": false, "contract_number": "CTC0000024972", "credit_operation_key": "7cc4d931-34d5-4b03-b04b-9ae4b6721f45", "credit_operation_status": "waiting_signature", "disbursement_accounts": [ { "account_branch": "1261", "account_digit": "1", "account_number": "000062293", "bank_code": "237" } ], "disbursement_options": [ { "annual_cet": 0.2517, "cet": 0.0189, "disbursed_issue_amount": 20373.27, "disbursement_date": "2025-06-02", "final_disbursement_amount": 2494.05, "issue_amount": 20458.57, "number_of_installments": 96, "prefixed_interest_rate": { "annual_rate": 0.2460411933, "daily_rate": 0.0006112186, "interest_base": "calendar_days", "monthly_rate": 0.0185 }, "total_iof": 85.3 } ], "document_key": "60763cba-da54-4826-bf76-b8f3d26c6326", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/60763cba-da54-4826-bf76-b8f3d26c6326/MMRIOLTDA-A-CCB-CTC0000024972.pdf", "final_disbursement_amount": 2494.05 }, "requester_control_key": "0e856d23-0746-4444-a71a-2957a64c869a" } ``` :::info No caso da recuperação dos dados de uma proposta de portabilidade pura o objeto "refinancing_credit_operation" não será retornado. ::: ## Correção de dados A correção dos dados de uma proposta já criada — com ou sem nova assinatura da CCB — está em **[Correção de Dados da Proposta](/documentation/guides/INSS/portability+refinancing/correcao-de-dados)**. ## Simulando cenários de sucesso e insucesso na averbação em Sandbox: A simulação de cenários é baseado no primeiro dígito do CPF informado na operação. **11.1.** Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook. **11.2.** Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo. **11.3.** Erros com Ação "cancel" receberá um webhook com o resultado final da operação. | Início do cpf | Enumerador | Descrição | Ação | |---------------|------------------------------|-----------------------------------------------------------------------------------|--------| | 2 | invalid_disbursement_account | Invalid disbursemente bank account | cancel | | 3 | operation_not_allowed_IR | Operation not allowed due to operation deadline greatter than benefit termination | cancel | :::caution Atenção Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado. | Enumerador | Descrição | |---------------|------------------------------------------------------------------| | mock_error | Informed document number is not a valid mock on test environment | ::: --- # Recálculo da Portabilidade URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/recalculate-portability Recálculo da Portabilidade Reduz o **saldo devedor** de uma operação de portabilidade a partir de um **novo valor de parcela**, sem gerar uma nova CCB. Use quando a margem consignável disponível do beneficiário no INSS não comporta a parcela originalmente contratada e a operação precisa ser ajustada para caber na margem. O recálculo altera, na mesma operação: - o **valor da parcela**, que passa a ser o valor informado; - o **valor de emissão** (`issue_amount`), ou seja, o saldo devedor pago ao credor original; - o valor comunicado à Dataprev como saldo devedor quitado da portabilidade. A diferença entre o valor de emissão original e o recalculado é lançada automaticamente como **desconto na remuneração do requisitante**, com a observação "Recálculo de portabilidade para adequação de margem disponível". :::info Diferença para o recálculo do refinanciamento Este endpoint atua sobre a **operação de portabilidade**. Para ajustar a operação de **refinanciamento** da mesma proposta, com ou sem nova CCB, veja [Recálculo e Reformalização do Refinanciamento](/documentation/guides/INSS/portability+refinancing/reformalization). ::: ## Request ENDPOINT /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate_portability MÉTODO POST ### Path Params credit_operation_key string (UUID) obrigatório Chave única da operação de portabilidade a ser recalculada. ### Body Params new_installment_amount number obrigatório Novo valor total da parcela. Precisa ser menor que o valor da parcela atual e maior ou igual a 10,00. new_monthly_interest_rate number opcional Nova taxa de juros mensal. Se omitida, a taxa atual da operação é mantida. ```json { "new_installment_amount": 123.51, "new_monthly_interest_rate": 0.018 } ``` :::caution Atenção O número de parcelas e as datas de vencimento **não mudam**. O que muda é o valor da parcela e, por consequência, o valor de emissão da operação. ::: ### Pré-condições A operação precisa atender **todas** as condições abaixo para ser recalculada: | Condição | Erro se não atendida | |----------|----------------------| | Operação existe | [`COP000027`](#COP000027) (404) | | Requisitante é dono da operação | [`QIT000005`](#QIT000005) (403) | | Operação é de portabilidade | [`COP000489`](#COP000489) | | Garantia do tipo `social_security` ou `social_security_portability` | [`COP000276`](#COP000276) | | Status da operação: `opened` | [`COP000489`](#COP000489) | | Nova parcela maior ou igual a 10,00 | [`COP000510`](#COP000510) | | Nova parcela menor que a parcela atual | [`COP000512`](#COP000512) | | Operação possui exatamente uma opção de desembolso | [`COP000513`](#COP000513) | | Valor de emissão recalculado menor que o original | [`COP000514`](#COP000514) | | Valor de emissão recalculado de ao menos 15% do original | [`COP000511`](#COP000511) | ## Response STATUS 200 Retorna o objeto completo da operação de crédito recalculada, na mesma estrutura da [consulta por credit_operation_key](/documentation/emissao_de_divida/consulta_por_credit_operation_key). Os campos que mudam são `issue_amount`, `disbursed_issue_amount` e os valores das parcelas em `disbursement_options`. Além deles, a resposta traz o objeto `negative_rebate` com o desconto lançado na remuneração do requisitante por causa do recálculo. É o mesmo valor enviado ao serviço de remuneração, então não é preciso deduzi-lo da diferença entre os valores de emissão. negative_rebate.amount number Valor do desconto, sempre negativo. É a diferença entre o valor de emissão recalculado e o original. negative_rebate.original_issue_amount number Valor de emissão antes do recálculo. negative_rebate.recalculated_issue_amount number Valor de emissão depois do recálculo. negative_rebate.reference_date string (date) Data de referência do lançamento. negative_rebate.fee_type string Tipo da tarifa lançada. Sempre net_payment_discount . negative_rebate.discount_observation string Observação que acompanha o lançamento. ```json { "negative_rebate": { "amount": -133.11, "original_issue_amount": 1000.0, "recalculated_issue_amount": 866.89, "reference_date": "2026-09-03", "fee_type": "net_payment_discount", "discount_observation": "Recálculo de portabilidade para adequação de margem disponível" } } ``` ## Erros | Código HTTP | Código QI | Descrição | Tradução | |-------------|-----------|-----------|----------| | 403 | `QIT000403` | You are not allowed to perform this action at this endpoint | Você não está autorizado a performar esta ação neste endpoint | | 403 | `QIT000005` | Selected agent do not own this item | O agente selecionado não é dono do item | | 404 | `COP000027` | Credit Operation not found | Operação não encontrada | | 400 | `COP000276` | Collateral type doesn't allow to recalculate operation | Garantia do contrato não permite que a operação seja recalculada | | 400 | `COP000335` | Assignment amount is greater than final amount | O valor de cessão é superior ao valor final da operação | | 400 | `COP000339` | Final disbursement amount cannot be negative | O valor de desembolso final não pode ser negativo | | 400 | `COP000489` | The credit operation is not allowed to be recalculated | A operação de crédito não está permitida para ser recalculada | | 400 | `COP000510` | The new installment amount is below the minimum allowed | O novo valor da parcela está abaixo do mínimo permitido | | 400 | `COP000511` | The recalculated issue amount is below the minimum allowed | O valor de emissão recalculado está abaixo do mínimo permitido | | 400 | `COP000512` | The new installment amount must be lower than the original installment amount | O novo valor da parcela deve ser menor que o valor da parcela original | | 400 | `COP000513` | The credit operation must have exactly one disbursement option to be recalculated | A operação de crédito deve possuir exatamente uma opção de desembolso para ser recalculada | | 400 | `COP000514` | The recalculated issue amount must be lower than the original issue amount | O valor de emissão recalculado deve ser menor que o valor de emissão original | Motivos detalhados do erro COP000489 O código `COP000489` é retornado para diferentes pré-condições não atendidas. O campo `reason` na resposta indica o motivo específico: | Motivo | Descrição | |--------|-----------| | Operação não é portabilidade | A operação de crédito não é uma operação de portabilidade | | Status inválido | O status da operação de crédito não a permite ser recalculada | --- # Recálculo e Reformalização do Refinanciamento URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/reformalization Recálculo e Reformalização do Refinanciamento Enquanto a operação de **refinanciamento ainda não foi averbada na Dataprev**, é possível corrigir seus dados financeiros e bancários. Existem dois endpoints para isso: | Endpoint | Gera nova CCB? | Quando usar | |----------|----------------|-------------| | `PUT …/refinancing_credit_operation` | **Sim** (reassinatura) | Corrigir condições e **emitir uma nova CCB** para reassinatura. | | `PUT …/refinancing_credit_operation/recalculate` | **Não** | Ajustar o **valor da parcela** sem gerar nova CCB. | Ambos aceitam o objeto `collateral_data` para **adicionar, alterar ou remover a carência** (`number_of_grace_periods`) informada pelo requisitante — veja [Carência](#carência). :::info Pré-condição comum A operação de refinanciamento **não pode estar averbada** (constituída na Dataprev). Caso contrário, retornamos [`CT000079`](#errors). ::: --- ## Correção com nova CCB Corrige os dados financeiros e bancários da operação de refinanciamento gerando uma **nova CCB**. Use quando for necessário reemitir o contrato. ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation MÉTODO PUT Testar no Playground **Request Body** ```json { "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-06-10", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "monthly_interest_rate": 0.0167, "installment_face_value": 410, "limit_days_to_disburse": 7, "number_of_installments": 84 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" } } ``` A resposta (`200`) retorna o objeto da operação de refinanciamento — mesma estrutura apresentada no [Fluxo Completo](/documentation/guides/INSS/portability+refinancing/end-to-end). :::caution Reassinatura obrigatória A `credit_operation_key`, a `document_key`, a `document_url`, a `related_party_key` e a `borrower.related_party_key` **mudam** após essa ação, sendo necessária a **reassinatura da CCB**. ::: --- ## Recálculo sem nova CCB Recalcula o **valor da parcela** da operação de refinanciamento **sem gerar uma nova CCB**. O novo valor de parcela deve ser **menor** que o original. ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/recalculate MÉTODO PUT Testar no Playground **Request Body** ```json { "financial": { "interest_type": "pre_price_days", "first_due_date": "2024-06-10", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "credit_operation_type": "ccb", "monthly_interest_rate": 0.0167, "installment_face_value": 410, "limit_days_to_disburse": 7, "number_of_installments": 84 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" } } ``` A resposta (`200`) retorna o objeto da operação de refinanciamento — mesma estrutura apresentada no [Fluxo Completo](/documentation/guides/INSS/portability+refinancing/end-to-end). :::caution Atenção O novo `installment_face_value` precisa ser **menor** que o valor original. A redução do valor de troco para o tomador não pode ultrapassar **30%** (caso contrário, retornamos [`CT000105`](#errors)). ::: --- ## Carência Conforme a IN 204, as operações de INSS podem ter **carência** (`number_of_grace_periods`), informada dentro de `collateral_data` na criação da proposta. Tanto a **correção com nova CCB** quanto o **recálculo** permitem **alterar ou remover** essa carência, enviando o objeto `collateral_data` no corpo da requisição. collateral_data.number_of_grace_periods integer opcional Número de meses de carência (de 0 a 3). Aplica-se à garantia social_security da operação. | Valor enviado | Comportamento | |---------------|---------------| | `1`, `2` ou `3` | **Define/atualiza** a carência da operação. | | `0` | **Remove** a carência previamente informada. | | Campo ausente (sem `collateral_data`) | Mantém a carência atual, sem alteração. | | Fora do intervalo (`< 0` ou `> 3`) | Erro [`CT000090`](#errors). | **Exemplo — removendo a carência no recálculo** ```json { "financial": { "installment_face_value": 380, "number_of_installments": 84, "monthly_interest_rate": 0.0166 }, "disbursement_bank_account": { "account_digit": "1", "account_number": "00001", "bank_code": "033", "branch_number": "0001" }, "collateral_data": { "number_of_grace_periods": 0 } } ``` :::info Ao alterar a carência, a **primeira data de vencimento** (`first_due_date`) é recalculada junto à Dataprev a partir do novo número de meses de carência. ::: --- ## Erros {#errors} | Código HTTP | Código QI | Descrição | |-------------|-----------|-----------| | 404 | `CT000002` | Proposta não encontrada. | | 404 | `CT000043` | Operação de refinanciamento não encontrada. | | 400 | `CT000046` | O status da operação de refinanciamento não permite essa operação. | | 400 | `CT000079` | Operação de refinanciamento não pode estar constituída (averbada) para alterar dados. | | 400 | `CT000090` | Número de carências inválido. O intervalo aceito é de 0 a 3. | | 400 | `CT000100` | O valor do desembolso final é inferior ao mínimo permitido. | | 400 | `CT000105` | A redução do valor de troco para o tomador não pode ser maior que 30%. | | 400 | `CT000133` | Prêmio de seguro QI não é permitido para INSS. | --- # Simulação da Proposta URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/simulacao Simulação da Proposta Simula a proposta de portabilidade e/ou refinanciamento (o Troco) a partir do saldo devedor informado, antes da digitação. Próximo passo: [Digitação da Proposta](/documentation/guides/INSS/portability+refinancing/proposta). :::caution Atenção Para propostas que envolvam troco após o refinanciamento, é necessário o valor do troco calculado de acordo com as condições do contrato seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro: STATUS 400 **Response Body** ```json { "title": "Bad Request", "code": "CT000118", "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00." } ``` ::: **3.1. Simulação de Portabilidade com Refinanciamento:** Antes de realizar a digitação da Proposta de Portabilidade com Refinanciamento, é possível simular as condições financeiras da proposta, sem a necessidade de coletar os dados cadastrais do cliente. **Ver exemplos de payload (Taxa Fixa / Valor Liberado Fixo)** **Com Taxa Fixa** **3.1.1. Simulação de Portabilidade com Refinanciamento, com taxa fixa:** Assim como na Digitação da Proposta (4.1.1), é possível realizar a simulação fixando a taxa do contrato: **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Request:* **body.json** ```json { "borrower": { "person_type": "natural" }, "collaterals": [{ "collateral_type": "social_security" }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "number_of_installments": 10 } }, "refinancing_credit_operation": { "financial": { "days_to_accrual": 0, "monthly_interest_rate": 0.0132, "installment_face_value": 100, "number_of_installments": 10 } }, "origin_contract": { "last_due_balance": 997.87 } } ``` :::info No payload acima, são descritos os dados mínimos para realização da simulação. ::: **Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload:* **response.json** ```json { "borrower": { "individual_document_number": "98765432100", "related_party_key": "fa55dca3-3147-45d2-bb8d-941f2d7191da", "role_type": "issuer" }, "portability_credit_operation": { "credit_operation_key": "a66675e6-bdc2-4468-8420-2889d5cec0a8", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.173044, "cet": 0.0134, "contract_fee_amount": 0.0, "contract_fees": [ { "amount": 0.5, "amount_type": "percentage", "fee_amount": 0.0, "fee_type": "tac" } ], "disbursed_issue_amount": 997.87, "disbursement_date": "2023-12-22", "external_contract_fee_amount": 0.0, "external_contract_fees": [ { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "spread", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "tac", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "insurance_premium", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 } ], "installments": [ { "business_due_date": "2024-02-22", "calendar_days": 62, "due_date": "2024-02-22", "due_principal": 997.87, "installment_number": 1, "pre_fixed_amount": 27.413791524708554, "principal_amortization_amount": 81.34620847529145, "total_amount": 108.76, "workdays": 40 }, { "business_due_date": "2024-03-22", "calendar_days": 29, "due_date": "2024-03-22", "due_principal": 916.5237915247086, "installment_number": 2, "pre_fixed_amount": 11.692366920719124, "principal_amortization_amount": 97.06763307928088, "total_amount": 108.76, "workdays": 21 }, { "business_due_date": "2024-04-22", "calendar_days": 31, "due_date": "2024-04-22", "due_principal": 819.4561584454277, "installment_number": 3, "pre_fixed_amount": 11.179911547915339, "principal_amortization_amount": 97.58008845208467, "total_amount": 108.76, "workdays": 20 }, { "business_due_date": "2024-05-22", "calendar_days": 30, "due_date": "2024-05-22", "due_principal": 721.876069993343, "installment_number": 4, "pre_fixed_amount": 9.5288330736045, "principal_amortization_amount": 99.2311669263955, "total_amount": 108.76, "workdays": 21 }, { "business_due_date": "2024-06-24", "calendar_days": 33, "due_date": "2024-06-24", "due_principal": 622.6449030669476, "installment_number": 5, "pre_fixed_amount": 9.046812945831448, "principal_amortization_amount": 99.71318705416856, "total_amount": 108.76, "workdays": 22 }, { "business_due_date": "2024-07-22", "calendar_days": 28, "due_date": "2024-07-22", "due_principal": 522.9317160127789, "installment_number": 6, "pre_fixed_amount": 6.439743824282488, "principal_amortization_amount": 102.32025617571752, "total_amount": 108.76, "workdays": 20 }, { "business_due_date": "2024-08-22", "calendar_days": 31, "due_date": "2024-08-22", "due_principal": 420.61145983706143, "installment_number": 7, "pre_fixed_amount": 5.738438681013405, "principal_amortization_amount": 103.0215613189866, "total_amount": 108.76, "workdays": 23 }, { "business_due_date": "2024-09-23", "calendar_days": 32, "due_date": "2024-09-23", "due_principal": 317.58989851807485, "installment_number": 8, "pre_fixed_amount": 4.473657660291388, "principal_amortization_amount": 104.28634233970861, "total_amount": 108.76, "workdays": 22 }, { "business_due_date": "2024-10-22", "calendar_days": 29, "due_date": "2024-10-22", "due_principal": 213.30355617836625, "installment_number": 9, "pre_fixed_amount": 2.721176981322744, "principal_amortization_amount": 106.03882301867725, "total_amount": 108.76, "workdays": 21 }, { "business_due_date": "2024-11-22", "calendar_days": 31, "due_date": "2024-11-22", "due_principal": 107.26473315968899, "installment_number": 10, "pre_fixed_amount": 1.4934220715493307, "principal_amortization_amount": 107.26657792845067, "total_amount": 108.76, "workdays": 22 } ], "issue_amount": 997.87, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17042118, "daily_rate": 0.00043722, "interest_base": "calendar_days", "monthly_rate": 0.0132 }, "total_iof": 0.0 } ], "final_disbursement_amount": 0.0 }, "proposal_key": "28a925f6-570e-4724-9132-3bd42f267c4f", "proposal_number": "17032788499215403", "proposal_status": "pending_submission", "refinancing_credit_operation": { "credit_operation_key": "aaf9abe0-2b8a-4688-8e09-413e1bd5285e", "credit_operation_status": "waiting_signature", "disbursement_accounts": [], "disbursement_options": [ { "annual_cet": 0.172031, "cet": 0.0133, "contract_fee_amount": -0.4, "contract_fees": [ { "amount": 0.5, "amount_type": "percentage", "fee_amount": -0.4, "fee_type": "tac" } ], "disbursed_issue_amount": 918.04, "disbursement_date": "2023-12-22", "external_contract_fee_amount": 0.0, "external_contract_fees": [ { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "spread", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "tac", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 }, { "amount": 0.0, "amount_released": 0, "amount_type": "absolute", "cofins_amount": 0, "csll_amount": 0, "description": null, "fee_amount": 0.0, "fee_type": "insurance_premium", "irrf_amount": 0, "net_fee_amount": 0.0, "pis_amount": 0, "tax_amount": 0.0 } ], "installments": [ { "business_due_date": "2024-02-22", "calendar_days": 62, "due_date": "2024-02-22", "due_principal": 917.64, "installment_number": 1, "pre_fixed_amount": 25.2095730147, "principal_amortization_amount": 74.7904269853, "total_amount": 100.0, "workdays": 40 }, { "business_due_date": "2024-03-22", "calendar_days": 29, "due_date": "2024-03-22", "due_principal": 842.8495730147, "installment_number": 2, "pre_fixed_amount": 10.7524369787, "principal_amortization_amount": 89.2475630213, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-04-22", "calendar_days": 31, "due_date": "2024-04-22", "due_principal": 753.6020099934, "installment_number": 3, "pre_fixed_amount": 10.2814172859, "principal_amortization_amount": 89.7185827141, "total_amount": 100.0, "workdays": 20 }, { "business_due_date": "2024-05-22", "calendar_days": 30, "due_date": "2024-05-22", "due_principal": 663.8834272793, "installment_number": 4, "pre_fixed_amount": 8.7632941742, "principal_amortization_amount": 91.2367058258, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-06-24", "calendar_days": 31, "due_date": "2024-06-22", "due_principal": 572.6467214535, "installment_number": 5, "pre_fixed_amount": 7.8126464787, "principal_amortization_amount": 92.1873535213, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-07-22", "calendar_days": 30, "due_date": "2024-07-22", "due_principal": 480.4593679322, "installment_number": 6, "pre_fixed_amount": 6.3420966342, "principal_amortization_amount": 93.6579033658, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-08-22", "calendar_days": 31, "due_date": "2024-08-22", "due_principal": 386.8014645664, "installment_number": 7, "pre_fixed_amount": 5.2771618926, "principal_amortization_amount": 94.7228381074, "total_amount": 100.0, "workdays": 23 }, { "business_due_date": "2024-09-23", "calendar_days": 31, "due_date": "2024-09-22", "due_principal": 292.078626459, "installment_number": 8, "pre_fixed_amount": 3.9848593609, "principal_amortization_amount": 96.0151406391, "total_amount": 100.0, "workdays": 21 }, { "business_due_date": "2024-10-22", "calendar_days": 30, "due_date": "2024-10-22", "due_principal": 196.0634858199, "installment_number": 9, "pre_fixed_amount": 2.5880710578, "principal_amortization_amount": 97.4119289422, "total_amount": 100.0, "workdays": 22 }, { "business_due_date": "2024-11-22", "calendar_days": 31, "due_date": "2024-11-22", "due_principal": 98.6515568777, "installment_number": 10, "pre_fixed_amount": 1.3459361963, "principal_amortization_amount": 98.6540638037, "total_amount": 100.0, "workdays": 22 } ], "issue_amount": 917.64, "number_of_installments": 10, "prefixed_interest_rate": { "annual_rate": 0.17042118, "daily_rate": 0.00043722, "interest_base": "calendar_days", "monthly_rate": 0.0132 }, "total_iof": 0.0 } ], "final_disbursement_amount": -79.83 } } ``` **Com Valor Liberado Fixo** **3.1.2. Simulação de Portabilidade com Refinanciamento, com valor liberado fixo:** Assim como na digitação da proposta (**4.1.2**), é possível realizar a simulação fixando o valor liberado ao cliente: **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload:* **payload.json** ```json { "borrower": { "person_type": "natural" }, "collaterals": [{ "collateral_type": "social_security" }], "portability_credit_operation": { "financial": { "installment_face_value": 100, "number_of_installments": 10 } }, "refinancing_credit_operation": { "financial": { "days_to_accrual": 0, "disbursed_amount": 1000, "installment_face_value": 100, "number_of_installments": 10 } }, "origin_contract": { "last_due_balance": 997.87 } } ``` **Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload:* **payload.json** ```json { "portability_credit_operation": { "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-08-09", "calendar_days": 53, "due_date": "2021-08-08", "due_principal": 997.87, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-09-08", "calendar_days": 31, "due_date": "2021-09-08", "due_principal": 690.89, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 0, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 1000, "issue_amount": 1000, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }] }, "refinancing_credit_operation": { "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-08-09", "calendar_days": 53, "due_date": "2021-08-08", "due_principal": 997.87, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-09-08", "calendar_days": 31, "due_date": "2021-09-08", "due_principal": 690.89, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 0, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 1000, "issue_amount": 1000, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }] } } ``` **3.2. Simulação de Portabilidade:** Também é possível simular as condições financeiras de uma Proposta de Portabilidade (Portabilidade Pura), sem a necessidade de coletar os dados cadastrais do cliente. **Request** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload:* **payload.json** ```json { "borrower": { "person_type": "natural" }, "collaterals": [{ "collateral_type": "social_security" }], "portability_credit_operation": { "financial": { "monthly_interest_rate": 0.0132, "installment_face_value": 100, "number_of_installments": 10 } }, "origin_contract": { "last_due_balance": 997.87 } } ``` **Response** - MÉTODO POST - STATUS /v2/credit_transfer/proposal_simulation *Payload:* **payload.json** ```json { "portability_credit_operation": { "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 }, "disbursement_options": [{ "installments": [{ "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-08-09", "calendar_days": 53, "due_date": "2021-08-08", "due_principal": 997.87, "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036", "installment_number": 1, "pre_fixed_amount": 54.84865004983954, "principal_amortization_amount": 306.98134995016045, "total_amount": 361.83, "workdays": 37 }, { "bank_slip_key": null, "digitable_line": null, "business_due_date": "2021-09-08", "calendar_days": 31, "due_date": "2021-09-08", "due_principal": 690.89, "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1", "installment_number": 2, "pre_fixed_amount": 21.964874249804833, "principal_amortization_amount": 339.86512575019515, "total_amount": 361.83, "workdays": 22 } ], "prefixed_interest_rate": { "annual_rate": 0.44556431, "daily_rate": 0.00564312, "monthly_rate": 0.0556431, "interest_base": "calendar_days_365" }, "iof_amount": 0, "external_contract_fee_amount": 0, "external_contract_fees": [], "contract_fee_amount": 0, "contract_fees": [], "number_of_installments": 2, "disbursed_issue_amount": 1000, "issue_amount": 1000, "disbursement_date": "2021-05-31", "cet": 1.212, "annual_cet": 32.122 }] } } ``` --- # Enumeradores URL: /zh-Hans/documentation/guides/INSS/reference/enumeradores Enumeradores Tabelas de referência compartilhadas por **todos** os fluxos INSS — crédito novo, refinanciamento, portabilidade e cartão consignado. Esta é a única página onde estes enumeradores são definidos; as demais páginas linkam para as âncoras daqui. :::info Retorno da Dataprev Os códigos de duas letras (`HW`, `BD`, `CR`…) são os da própria Dataprev. O campo que a QI Tech entrega nos webhooks e nas consultas é o **enumerador**, na segunda coluna. ::: ## Enumeradores Retention Reason {#retention_reason_enumerator} | Enumerador | Descrição | |------------------------------------------|--------------------------------------------------------| | **issuer_retention** | Retenção do Cliente | | **different_from_original** | Condições da proposta divergentes do contrato original | | **issuer_lawsuit** | Cliente com ação judicial | | **insurance_in_progress** | Indenização de seguro em andamento | | **collateral_in_execution** | Garantia em Execução | | **contract_not_found** | Contrato não encontrado | | **invalid_contract_type** | Tipo de contrato inválido | | **portability_in_progress** | Portabilidade em andamento | | **assigned_contract** | Contrato cedido | | **issuer_document_number_invalid** | CPF não é do contrato | | **unrelated_issuer_document_number** | CPF informado não é o do titular | | **assigned_without_co_obligation** | Contrato cedido sem coobrigação | | **fgts_in_use** | FGTS AMORTIZAR em uso | | **fgts_funding** | FGTS funding | | **portability_not_requested** | O cliente não solicitou a portabilidade | | **wrong_original_financial_institution** | IF Credora Original Incorreta | ## Tabela de retorno de erros Dataprev - averbação {#dataprev_response_enumerator_errors} | Código Dataprev | Enumerador | Descrição | Ação Qi | |-----------------|--------------------------------------------------|-------------------------------------------------------------|----------------------| | HW | consignable_margin_excceded | Exceeded consignable margin | Teimosinha | | IT | benefit_blocked_by_tbm | Benefit blocked due to benefit transfer | Teimosinha | | IE | benefit_blocked_by_beneficiary | Benefit blocked by beneficiary | Teimosinha | | AN | invalid_disbursement_account | Invalid disbursement bank account | Pendente de ação do parceiro (corrigir os dados bancários) | | HX | reservation_already_included | Reservation already included | Confirmar averbação | | IF | benefit_blocked_by_granting_process | Benefit blocked during granting process | Teimosinha | | AV | processing_payroll | Operation couldn`t be done during processing payroll period | Teimosinha | | OF | invalid_cbc | Invalid cbc | Teimosinha | | IA | first_name_mismatch | First name mismatch benefit owner or legal representative | Teimosinha | | OS | legal_representative_document_number_mismatch | Document number mismatch legal representative | Teimosinha | | AY | invalid_state | Invalid state | Teimosinha | | HZ | operation_not_allowed_on_this_reservation_status | Operation couldn`t be done with current reservation status | Teimosinha | | AP | invalid_contract_date | Accrual, end or start contract date is invalid | Teimosinha | | GA | required_fields_missing | Required fields are missing | Teimosinha | | BC | cbc_missing | CBC is missing | Teimosinha | | NC | contract_number_missing | Contract number is missing | Teimosinha | | NB | benefit_number_missing | Benefit number is missing | Teimosinha | | CA | invalid_bank_code | Invalid bank code | Teimosinha | | HR | exceeded_number_of_allowed_contracts | Amount of contracts is above the limit | Teimosinha | | PV | invalid_image_format | Image with wrong format | Teimosinha | | IR | operation_not_allowed_IR | Operation date is greater than benefit expiration | Cancelar | | PK | wrong_bank_code_destination | Portability number was found with wrong bank code destination| Teimosinha | | PH | wrong_benefit_number_on_portability | Portability number was found with wrong benefit number | Teimosinha | | PI | invalid_contract_total_amount | Reservation contract total amount should be greater than Dataprev reference amount | Teimosinha | :::danger Atenção! Todas as taxas e valores do contrato são validados no momento da criação da reserva. A crítica "invalid_contract_total_amount" ocorre nos casos em que os contratos se estendem por muito tempo sem serem averbados, o que impacta os valores previamente estabelecidos. ::: ## Tabela de retorno de sucesso - averbação {#dataprev_response_enumerator_success} | Código Dataprev | Enumerador | Descrição | |--------|--------------------------|-----------------------------------------| | BD | successfully_included | Inclusion has been successfully done | | BF | successfully_removed | Removal has been successfully done | | BR | successfully_reactivated | Reactivation has been successfully done | | BS | successfully_suspended | Suspension has been successfully done | ## Tabela de retorno de erros na consulta de saldo {#dataprev_balance_errors_enumerators} | Código | Enumerador | Descrição | |--------|---------------------------------------|---------------------------------------------------------------------------------| | CR | not_found_legal_representative | no legal representative for the beneficiary | | CD | inexistent_beneficiary | no beneficiary found | | AS | benefity_without_legal_representative | beneficiary does not have a legal representative | | BI | inexistent_benefit | no benefit found | | D1 | inconsistent_balance_benefit_data | The balance benefit data registered is either inconsistent, null or incomplete. | ## Tabela de retorno de erros na consulta de benefícios {#dataprev_benefits_errors_enumerators} | Código | Enumerador | Descrição | |--------|---------------------------------------|---------------------------------------------------------------------------------| | CR | not_found_legal_representative | no legal representative for the beneficiary | | CD | inexistent_beneficiary | no beneficiary found | | AS | benefity_without_legal_representative | beneficiary does not have a legal representative | ## Tabela de situação de benefícios {#benefit_situation_enumerator} | Items | |-------| | active | | excluded | | terminated | | suspended | | suspended_by_CONPAG | | terminated_by_SISOBI | | receiving_monthly_recover_6_months | | receiving_monthly_recover_18_months | | suspended_by_name_error | | suspended_by_credentialed_payer | | suspended_by_inspection | | suspended_by_audit | | terminated_by_inspection | | terminated_by_audit | | receiving_monthly_recover_6_months_inspection | | receiving_monthly_recover_18_months_inspection | | suspended_by_SISOBI | | canceled_by_audit | ## Tabela de status de benefícios {#benefit_status_enumerator} | Enumerador | Descrição | |------------|-----------------------------------------------------| | Elegible | Elegível para empréstimo | | Inelegible | Benefício inelegível para empréstimo | | Blocked | Benefício elegível, porém bloqueado para empréstimo | ## Tabela de tipos de bloqueio {#block_type_enumerator} A Dataprev devolve o **código** em `tipoBloqueio.codigo`; a QI Tech entrega o **enumerador** correspondente no campo `block_type`. | Código Dataprev | Enumerador (`block_type`) | Descrição | |---|---|---| | 0 | `not_blocked` | Sem bloqueio | | 1 | `blocked_by_benefitiary` | Bloqueado pelo Segurado | | 2 | `blocked_by_tbm` | Bloqueado por TBM | | 3 | `blocked_in_concession` | Bloqueado na Concessão | ## Tabela de tipos de politicamente exposto {#politically_exposed_enumerator} | Enumerador | Descrição | |------------|-----------------------------------------------------| | 0 | Pessoa Não Exposta Politicamente | | 1 | Pessoa Exposta Politicamente - Nível 1 | ## Tabela de benefícios {#benefit_type_enumerator} | código | benefício | | --- | ------------------------------------------------ | | 1 | pension_by_death_rural_worker | | 2 | pension_by_death_accident_rural_worker | | 3 | pension_by_death_rural_employer | | 4 | retirement_invalidity_rural_emploee | | 5 | retirement_invalidity_accident_rural_worker | | 6 | retirement_invalidity_rural_employer | | 7 | retirement_by_eldness_rural_worker | | 8 | retirement_by_age_rural_employer | | 9 | complement_by_work_accident_rural_worker | | 11 | support_invalidity_rural_worker | | 12 | support_by_age_rural_worker | | 13 | aid_sickness_rural_worker | | 15 | aid_time_off_rural_worker | | 16 | aid_federal | | 17 | international_agreement | | 18 | inclusion_benefit | | 19 | pension_student_law7004 | | 20 | pension_by_death_diplomat | | 21 | pension_by_death | | 22 | pension_by_death_statute | | 23 | pension_by_death_veteran | | 24 | pension_special_institutional_act | | 25 | aid_time_off | | 26 | pension_by_death_special_law593 | | 27 | pension_by_death_federal_emploee | | 28 | pension_by_death_general_regime_law20465 | | 29 | pension_by_death_marine_veteran | | 30 | monthly_income_lifetime_invalidity | | 31 | aid_sickness | | 32 | retirement_invalidity_social_security | | 33 | retirement_invalidity_aeronautic | | 34 | retirement_invalidity_marine_law1756 | | 35 | aid_sickness_veteran | | 36 | aid_social_security_accident | | 37 | retirement_capin_extra_emploee | | 38 | retirement_federal_extra_emploee | | 39 | aid_invalidity_student_law7004 | | 40 | monthly_income_lifetime_by_age_upper70_law6179 | | 41 | retirement_by_age | | 42 | retirement_by_contribution_time | | 43 | retirement_by_time_of_service_veteran | | 44 | retirement_special_aeronautic | | 45 | retirement_by_time_of_service_journalist | | 46 | retirement_special | | 47 | allowance_25 | | 48 | allowance_20 | | 49 | retirement_ordinary | | 50 | aid_sickness_extinct_basic_plan | | 51 | retirement_invalidity_extinct_basic_plan | | 52 | retirement_by_age_extinct_basic_plan | | 53 | aid_time_off_extinct_basic_plan | | 54 | pension_indemnity_federal | | 55 | pension_by_death_extinct_basic_plan | | 56 | pension_lifetime_syndrome_thalidomide | | 57 | retirement_by_teacher_labor_time | | 58 | retirement_anisty | | 59 | pension_by_death_amnesty | | 60 | indemnity | | 61 | aid_birth | | 62 | aid_funeral | | 63 | aid_funeral_rural_worker | | 64 | aid_funeral_rural_employer | | 65 | savings_special_autarchy | | 67 | savings_mandatory_ipase_law5128 | | 68 | savings_special_retirement_ps_affiliated_upper60 | | 69 | savings_student_law7004 | | 70 | restitution | | 71 | monthly_income | | 72 | retirement_by_time_of_service_law1756 | | 73 | monthly_income_family_statute | | 74 | complement_pension_federal | | 75 | complement_retirement_federal | | 76 | monthly_income_statute | | 77 | monthly_income_sinpas_family_statute | | 78 | retirement_by_age_law1756 | | 79 | advantage | | 80 | monthly_income_maternity | | 81 | compulsory_retirement | | 82 | retirement_by_time_of_service_sasse | | 83 | retirement_invalidity_ex_sasse | | 84 | pension_by_death_sasse | | 85 | pension_lifetime_rubber_tapper_law7986 | | 86 | pension_lifetime_rubber_tapper_dependent_law7986 | | 87 | continuous_aid_physical_disabilities | | 88 | continuous_aid_eldness | | 89 | pension_special_hemodialysis_victim_caruaru | | 90 | medic_assistency_work_accident | | 91 | aid_sickness_by_work_accident | | 92 | retirement_invalidity_work_accident | | 93 | pension_by_death_work_accident | | 94 | aid_work_accident | | 95 | aid_additional_work_accident | | 96 | pension_special_leprosy_law11520 | | 97 | savings_by_death_work_accident | | 98 | aid_longshoreman | | 99 | time_off_15 | --- # Averbação e Desaverbação URL: /zh-Hans/documentation/guides/INSS/reservations/averbacao-e-desaverbacao Averbação e Desaverbação A constituição da garantia na Dataprev depois da formalização: os webhooks de sucesso e falha, a retentativa automática ("teimosinha"), a correção de dados e a desaverbação. A garantia só está de fato constituída (`collateral_constituted: true`) depois da averbação aceita. Para os motivos de falha, veja [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_errors). :::caution Atenção Para que o pedido de averbação seja criado com sucesso, é preciso que seja feita uma consulta de dados válida para o benefício **previamente**. Para isso basta seguir os passos do item [2 - Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio). ::: ## Falha na averbação por margem exedida Se uma reserva com categoria de novo beneficiário ou de aumento salarial receber margem excedida na tentativa de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro", e será enviado um webhook no seguinte formato para informar o ocorrido: WEBHOOK_TYPE social_security_margin_exceeded_for_new_beneficiary ou social_security_margin_exceeded_for_minimum_wage_increase STATUS Pending requester action Webhook Body **Novo Beneficiario** ```json { "webhook": { "key": "", "data": { "enumerator": "margin_exceeded_for_new_beneficiary", "description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18", }, "status": "pending_requester_action", "webhook_type": "social_security_margin_exceeded_for_new_beneficiary", "event_datetime": "2024-10-15T15:33:59" } } ``` **Aumento Salarial** ```json { "webhook": { "key": "", "data": { "enumerator": "margin_exceeded_for_minimum_wage_increase", "description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18", }, "status": "pending_requester_action", "webhook_type": "social_security_margin_exceeded_for_minimum_wage_increase", "event_datetime": "2024-10-15T15:33:59" } } ``` ## Falha na averbação por falta de uma consulta de dados válida do benefício Se uma consulta dos dados do benefício não for realizada com sucesso antes do pedido de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro" e será enviado um webhook no seguinte formato para informar o ocorrido: WEBHOOK_TYPE social_security_success_balance_request_not_found STATUS Pending requester action Webhook Body ```json { "webhook": { "key": "", "data": { "enumerator": "success_balance_request_not_found", "description": "Success balance request not found for the specified benefit number" }, "status": "pending_requester_action", "webhook_type": "social_security_success_balance_request_not_found", "event_datetime": "2024-10-15T15:33:59" } } ``` Para prosseguir, as seguintes ações deverão ser tomadas: 1. Realizar a consulta dos dados do benefício em questão seguindo os passos do item 2 - [Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio); 2. Enviar uma requisição no formato abaixo para informar que a consulta foi realizada. ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /validate_reservation MÉTODO POST Testar no Playground :::info Importante Essa requisição não apenas confirma a existência de uma consulta válida dos dados do benefício, mas também verifica se as informações enviadas para a criação da averbação estão corretas, permitindo assim a continuidade do processo. ::: ## Sistema de priorização de requisições (Fura fila) Devido à limitação da Dataprev, que permite no máximo **25 requisições por segundo**, o sistema de requisições opera de maneira assíncrona, ou seja, as tentativas de averbação são organizadas em uma fila para processamento. Dessa forma, as requisições são priorizadas com base no tipo de operação e probabilidade de sucesso. Nesse contexto, pensando em evitar a perda de margem em situações em que há alta probabilidade de sucesso na averbação, mas ainda vai demorar para ocorrer a próxima tentativa de averbação, foi desenvolvido esse sistema que permite realizar uma requisição de forma síncrona, ou seja, sem precisar esperar passar pela fila. Todavia, para garantir o controle adequado e evitar o uso indevido desse sistema, foi implementado um mecanismo de **balde de fichas**, que funciona da seguinte forma: - Cada requisição consome uma ficha para ser realizada; - Se a requisição resultar em uma averbação bem-sucedida, a ficha é devolvida ao balde; - Caso contrário, a ficha é perdida; - Existe um limite máximo de fichas por balde; - Uma rotina de reposição de fichas é ativada periodicamente, para reabastecer as fichas perdidas até atingir o limite máximo; - Se as fichas se esgotarem, novas requisições não poderão ser feitas até que a rotina reponha uma nova ficha. Exemplo Sistema de Balde Nesse exemplo, a configuração do balde é: - **Número máximo de fichas:** 10 - **Tempo de reposição:** 30min **HORA 0:** O balde é criado com sua capacidade máxima; **9min:** Uma requisição é feita, mas o contrato não é averbado (erro), ocasionando na perda de 1 ficha; **17min:** Uma requisição é feita e o contrato é averbado (sucesso), mantendo inalterado o número de fichas; **30min:** Ocorre a primeira reposição de fichas, levando o balde a sua capacidade máxima novamente; **47min:** 10 requisições são realizadas com sucesso e nenhuma ficha é perdida; **1h:** Ocorre a segunda reposição de fichas, mas como o balde já está cheio, o número de fichas permanece inalterado; **1:12h:** 5 requisições são realizadas com erro, levando a perda de 5 fichas; **1:30h:** Ocorre a terceira reposição de fichas, deixando o balde com 6 fichas; **1:38h:** 6 requisições são realizadas com erro, esgotando todas as fichas; **1:51h:** Uma tentativa de requisição é feita, mas como o balde não possui nenhuma ficha, a requisição é barrada; **2h:** Ocorre a quarta reposição de fichas, levando a balde a 1 ficha e permitindo novas tentativas de requisições; Para fazer a requisição prioritária, basta bater no seguinte endpoint utilizando a DEBT-KEY correspondente à operação que deseja averbar: ### Request ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /priority_request MÉTODO POST Testar no Playground ### Response Response Body - Sucesso ```json { "max_bucket_capacity": 10, "bucket_fill_rate_minutes": 30, "available_tokens": 7, "status": "pending_document_submission", "next_refill_at": "2025-02-04T20:28:35Z" } ``` Response Body - Erros ```json Erro na averbação: { "title": "Reservation Failed", "description": "Last Response: consignable_margin_excceded, Tokens Available: 9, Next Refill At: 2025-02-04T20:18:35Z", "translation": "Ultima resposta: consignable_margin_excceded, Fichas disponiveis: 9, Proxima Recarga: 2025-02-04T20:18:35Z", "extra_fields": {}, "code": "SSC000083" } Erro de nenhuma ficha disponível: { "title": "Rate limit exceeded", "description": "Request limit exceeded. No tokens available, next refill in 8 minutes.", "translation": "Limite de solicitacoes excedido. Nenhuma ficha disponivel, proxima recarga em 8 minutos.", "extra_fields": {}, "code": "SSC000080" } ``` Por fim, é possível consultar as configurações atuais do balde sem a necessidade de realizar uma requisição no endpoint de priorização. Para isso, disponibilizamos o seguinte endpoint para consulta: ### Request ENDPOINT /social_security/bucket_configuration MÉTODO GET Testar no Playground ### Response Response Body ```json { "max_bucket_capacity": 10, "bucket_fill_rate_minutes": 30, "available_tokens": 7, "next_refill_at": "2025-02-04T20:08:35Z" } ``` ## Sucesso na averbação Em caso de sucesso na averbação o parceiro receberá o seguinte webhook: WEBHOOK_TYPE credit_operation.collateral STATUS Success Webhook Body ```json { "key": "", "data": { "collateral_type": "social_security", "collateral_constituted": true }, "event_time": "2022-10-31 15:23:46", "webhook_type": "credit_operation.collateral" } ``` ## Correção de dados no caso de falha na averbação É possível corrigir os dados bancários, número do benefício e o nome do contrato em tentativa de averbação. Para isso basta utilizar a seguinte chamada: ENDPOINT /debt/ DEBT-KEY /collateral MÉTODO PATCH Testar no Playground Request Body **Dados Bancários** ```json { "disbursement_bank_account": { "bank_code": "123", "account_digit": "1", "account_branch": "1234", "account_number": "5678", "document_number": "12345678901" } } ``` **Número do Benefício** ```json { "benefit_number": 1234567890 } ``` **Nome** ```json { "name": "Nome do Beneficiário" } ``` ## Desaverbação A desaverbação de um contrato é realizada através da rota de cancelamento permanente. Essa rota coloca um status final no contrato, o qual não é passível de retentativa e dispara a desaverbação da margem averbada. Para realizar o cancelamento definitivo, deve ser utilizado o seguinte endpoint: ENDPOINT /debt/ DEBT-KEY /cancel_permanently MÉTODO POST Testar no Playground ### Webhooks WEBHOOK_TYPE debt STATUS canceled_permanently Webhook Body ```json { "key": "", "data": {}, "status": "canceled_permanently", "webhook_type": "debt", "event_datetime": "2022-11-01 03:46:31" } ``` --- # Fura-fila (priority request) URL: /zh-Hans/documentation/guides/INSS/reservations/priority-request Fura-fila (priority request) Mecanismo para tentar uma **averbação de forma síncrona**, sem esperar a fila assíncrona da Dataprev, usando um **balde de fichas** por requester. Cada chamada consome uma ficha; em caso de sucesso na averbação a ficha pode ser devolvida; em falha, a ficha é perdida até a próxima reposição periódica. :::info Não confunda com reserva prioritária (fixed rate) Este guia trata de **`POST …/priority_request`** e **`GET /social_security/bucket_configuration`** (balde de fichas / fura-fila). É **diferente** da marcação de reserva **`fixed_rate`** em [Reserva prioritária (fixed rate)](/documentation/guides/INSS/reservations/priority-reservation) (`PATCH` / `DELETE` em `/priority_reservation`). ::: ## Contexto A Dataprev limita o throughput (**ordem de 25 requisições por segundo**). Por isso as tentativas de averbação costumam ser processadas em **fila**. O endpoint `priority_request` permite pular essa fila quando há **ficha disponível** no balde. **Resumo do balde:** - Cada requisição **consome** uma ficha. - Averbação **bem-sucedida** → a ficha pode ser **devolvida** ao balde. - Averbação com **erro** → a ficha é **perdida** até a reposição. - Existe **capacidade máxima** e **intervalo de reposição** configurados para o seu requester. - Sem fichas → nova tentativa falha até a próxima reposição. **Exemplo ilustrativo do balde** Configuração de exemplo: **10 fichas** máximas, **30 minutos** entre reposições. **Hora 0:** balde criado na capacidade máxima. **9 min:** uma requisição falha na averbação → perde 1 ficha. **17 min:** uma requisição tem sucesso → número de fichas inalterado. **30 min:** primeira reposição → balde volta ao máximo. **47 min:** dez requisições com sucesso → nenhuma ficha perdida. **1 h:** segunda reposição; se o balde já estiver cheio, nada muda. **1 h 12 min:** cinco falhas → perda de 5 fichas. **1 h 30 min:** terceira reposição → ex.: 6 fichas disponíveis. **1 h 38 min:** seis falhas → balde esgota. **1 h 51 min:** tentativa sem fichas → barrada. **2 h:** quarta reposição → novas tentativas liberadas. Para o passo a passo completo da operação (validação de reserva, webhooks de sucesso, correção de dados), veja o [Fluxo completo — crédito novo e refinanciamento](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end#sistema-de-priorização-de-requisições-fura-fila). --- ## Disparar requisição prioritária Request ENDPOINT /social_security/reservation/external_key/ EXTERNAL_KEY /priority_request MÉTODO POST Path params external_key string obrigatório Chave da operação no fluxo (mesmo conceito de DEBT-KEY nos roteiros INSS ou payroll_card_reservation_key nos fluxos de cartão consignado INSS). **Body:** não há corpo na requisição. Testar no Playground **Python** ```python title="ENDPOINT" POST /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_request ``` **curl** ```bash title="ENDPOINT" curl -X POST \ 'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_request' \ -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \ -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \ -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \ -H 'Content-Type: application/json' ``` Response (sucesso) STATUS 200 Atributos max_bucket_capacity integer Capacidade máxima do balde (fichas). bucket_fill_rate_minutes integer Intervalo de reposição, em minutos. available_tokens integer Fichas disponíveis após a operação. status string Status da reserva após a tentativa (ex.: pending_document_submission ). next_refill_at string Próximo instante de reposição do balde (ISO 8601). :::tip Webhook de sucesso Se a averbação for concluída com sucesso, o parceiro recebe o webhook credit_operation.collateral com status de sucesso. Detalhes no [mesmo capítulo do fluxo completo](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end#sucesso-na-averbação). ::: ```json title="RESPONSE BODY" { "max_bucket_capacity": 10, "bucket_fill_rate_minutes": 30, "available_tokens": 7, "status": "pending_document_submission", "next_refill_at": "2025-02-04T20:28:35Z" } ``` --- ## Consultar configuração do balde Permite ver capacidade, fichas disponíveis e próxima reposição **sem** disparar uma requisição prioritária. Request ENDPOINT /social_security/bucket_configuration MÉTODO GET Sem path params nem query obrigatórios. Testar no Playground **Python** ```python title="ENDPOINT" GET /social_security/bucket_configuration ``` **curl** ```bash title="ENDPOINT" curl -X GET \ 'https://api-auth.sandbox.qitech.app/social_security/bucket_configuration' \ -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \ -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \ -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \ -H 'Content-Type: application/json' ``` Response STATUS 200 Atributos max_bucket_capacity integer Capacidade máxima do balde. bucket_fill_rate_minutes integer Intervalo de reposição, em minutos. available_tokens integer Fichas disponíveis no momento. next_refill_at string Próxima reposição (ISO 8601). ```json title="RESPONSE BODY" { "max_bucket_capacity": 10, "bucket_fill_rate_minutes": 30, "available_tokens": 7, "next_refill_at": "2025-02-04T20:08:35Z" } ``` --- ## Erros | HTTP | Código | Título (exemplo) | Quando ocorre | |------|--------|------------------|---------------| | 400 / 4xx | SSC000083 | Reservation Failed | Tentativa prioritária executada, mas a averbação falhou (mensagem costuma citar última resposta da Dataprev, fichas restantes e próxima reposição). | | 429 / 4xx | SSC000080 | Rate limit exceeded | Nenhuma ficha disponível; aguardar a próxima reposição do balde. | **Exemplos de corpo de erro (JSON)** ```json { "title": "Reservation Failed", "description": "Last Response: consignable_margin_excceded, Tokens Available: 9, Next Refill At: 2025-02-04T20:18:35Z", "translation": "Ultima resposta: consignable_margin_excceded, Fichas disponiveis: 9, Proxima Recarga: 2025-02-04T20:18:35Z", "extra_fields": {}, "code": "SSC000083" } ``` ```json { "title": "Rate limit exceeded", "description": "Request limit exceeded. No tokens available, next refill in 8 minutes.", "translation": "Limite de solicitacoes excedido. Nenhuma ficha disponivel, proxima recarga em 8 minutos.", "extra_fields": {}, "code": "SSC000080" } ``` --- # Fila prioritária URL: /zh-Hans/documentation/guides/INSS/reservations/priority-reservation Fila prioritária (fixed rate) Marca a reserva INSS como `fixed_rate`, respeitando o **limite de reservas prioritárias ativas**. **Quando usar** - **Desbloqueio:** o benefício está em liberação. - **Concorrência por margem:** operações concorridas e críticas (ex.: novo entrante). **Antes de priorizar múltiplas reservas:** `GET /social_security/priority_reservation_configuration` mostra uso atual e limite. ## Status da reserva permitidos Só é possível **definir** ou **remover** prioridade `fixed_rate` quando a reserva está em um destes status: | Status | Descrição resumida | |--------|-------------------| | `pending_reservation` | Reserva pendente | | `in_queue_pending_reservation` | Na fila, aguardando reserva | | `pending_balance_request` | Aguardando consulta de saldo | | `in_queue_pending_balance_request` | Na fila, aguardando consulta de saldo | Fora desses status, a API retorna erro indicando status não permitido. :::tip Limite simultâneo Se o número de reservas já marcadas como prioritárias atingir o máximo configurado, um novo `PATCH` retorna erro de limite excedido. Use o `GET` de configuração para acompanhar o uso atual sem priorizar outra reserva. ::: --- ## Definir prioridade Request ENDPOINT /social_security/reservation/external_key/ EXTERNAL_KEY /priority_reservation MÉTODO PATCH Path params external_key string obrigatório Identificador externo da reserva no seu fluxo (mesmo conceito de DEBT-KEY nos roteiros de crédito consignado INSS). **Python** ```python title="ENDPOINT" PATCH /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation ``` **curl** ```bash title="ENDPOINT" curl -X PATCH \ 'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation' \ -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \ -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \ -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \ -H 'Content-Type: application/json' ``` Response STATUS 200 Atributos external_key string Chave externa da reserva. reservation_priority_type string Tipo de prioridade; em sucesso, fixed_rate . current_number_of_priority_reservations integer Quantidade atual de reservas prioritárias do requester após a operação. max_number_of_priority_reservations integer Limite máximo configurado. ```json title="RESPONSE BODY" { "external_key": "550e8400-e29b-41d4-a716-446655440000", "reservation_priority_type": "fixed_rate", "current_number_of_priority_reservations": 1, "max_number_of_priority_reservations": 10 } ``` --- ## Remover prioridade Request ENDPOINT /social_security/reservation/external_key/ EXTERNAL_KEY /priority_reservation MÉTODO DELETE Path params external_key string obrigatório Identificador externo da reserva. Remove a prioridade da reserva (`reservation_priority_type` passa a `null`). Exige que a prioridade atual seja `fixed_rate` (se houver outro tipo, a API retorna erro). Status da reserva deve continuar na lista permitida. **Python** ```python title="ENDPOINT" DELETE /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation ``` **curl** ```bash title="ENDPOINT" curl -X DELETE \ 'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation' \ -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \ -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \ -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \ -H 'Content-Type: application/json' ``` Response STATUS 200 Atributos external_key string Chave externa da reserva. reservation_priority_type null Sem prioridade após a remoção. current_number_of_priority_reservations integer Contagem após a remoção. max_number_of_priority_reservations integer Limite máximo configurado. ```json title="RESPONSE BODY" { "external_key": "550e8400-e29b-41d4-a716-446655440000", "reservation_priority_type": null, "current_number_of_priority_reservations": 0, "max_number_of_priority_reservations": 10 } ``` --- ## Consultar limite e uso atual Request ENDPOINT /social_security/priority_reservation_configuration MÉTODO GET Retorna o resumo de quantas reservas prioritárias o requester tem no momento, o máximo permitido e a lista completa das reservas atualmente na fila prioritária. **Python** ```python title="ENDPOINT" GET /social_security/priority_reservation_configuration ``` **curl** ```bash title="ENDPOINT" curl -X GET \ 'https://api-auth.sandbox.qitech.app/social_security/priority_reservation_configuration' \ -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \ -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \ -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \ -H 'Content-Type: application/json' ``` Response STATUS 200 Atributos current_number_of_priority_reservations integer Reservas prioritárias ativas no momento. max_number_of_priority_reservations integer Teto configurado para o requester. reservations array of objects Lista das reservas atualmente na fila prioritária, ordenadas por fixed_rate_set_at crescente. Máximo de 100 itens. **Atributos de reservations** credit_operation_key string Chave externa da reserva. contract_number string Número do contrato. status string Status atual da reserva. Valores possíveis: pending_reservation , in_queue_pending_reservation , pending_balance_request , in_queue_pending_balance_request . type string Enumerador do tipo da reserva. fixed_rate_set_at string (ISO 8601) Data e hora em que a reserva foi adicionada à fila prioritária. ```json title="RESPONSE BODY" { "current_number_of_priority_reservations": 2, "max_number_of_priority_reservations": 10, "reservations": [ { "credit_operation_key": "550e8400-e29b-41d4-a716-446655440000", "contract_number": "BYX2000013373", "status": "pending_reservation", "type": "new", "fixed_rate_set_at": "2026-04-13T14:00:00Z" } ] } ``` --- ## Erros ### PATCH — definir prioridade | HTTP | Código | Título (exemplo) | Quando ocorre | |------|--------|------------------|---------------| | 400 | QIT000006 | Priority reservation configuration not set | Requester sem configuração de prioridade de reserva | | 400 | QIT000006 | Reservation status not allowed | Status da reserva fora da lista permitida | | 400 | QIT000006 | Priority reservation limit exceeded | Limite simultâneo atingido | | 404 | SSC000035 | Reservation not Found | Reserva inexistente para requester + `external_key` | | 409 | QIT000008 | Priority reservation already fixed_rate | Já está `fixed_rate` | ### DELETE — remover prioridade | HTTP | Código | Título (exemplo) | Quando ocorre | |------|--------|------------------|---------------| | 400 | QIT000006 | Reservation priority type not fixed_rate | Há prioridade, mas não é `fixed_rate` | | 400 | QIT000006 | Reservation status not allowed | Status não permitido | | 404 | SSC000035 | Reservation not Found | Reserva não encontrada | ### GET — configuração | HTTP | Código | Título (exemplo) | Quando ocorre | |------|--------|------------------|---------------| | 404 | QIT000007 | Priority reservation configuration not found | Sem configuração para o requester | **Exemplos de corpo de erro (JSON)** ```json { "title": "Reservation not Found", "description": "...", "translation": "...", "code": "SSC000035" } ``` ```json { "title": "Priority reservation already fixed_rate", "description": "...", "translation": "...", "code": "QIT000008" } ``` --- # Assinatura em grupo (INSS) URL: /zh-Hans/documentation/guides/INSS/signatures/batch-group-signature :::caution Disponibilidade Este fluxo está em implantação. Por ora, ele cobre operações **INSS** (`social_security`) com o certificador **`qi_sign`**. Alinhe com o time de integração da QI Tech a liberação para o seu requester antes de iniciar a integração em produção. ::: O fluxo de **assinatura em grupo** agrupa **várias operações** em **uma única pasta de assinatura** do QI Sign. O beneficiário faz **uma única jornada de assinatura** (prova de vida, documento e OTP) e assina **todas as operações do grupo de uma só vez**, com **um único link**. :::info Fluxo 0. (opcional) Faça upload do [documento de identificação](#documento-de-identificacao-pre-coletado) do beneficiário, para que ele não precise fotografá-lo durante a assinatura 1. Abra o grupo com `POST /document/document_batch_group` e guarde a `document_batch_group_key`. 2. Crie cada operação (`/debt`, `/v2/credit_transfer/proposal`, etc) enviando `document_batch_group_key` na raiz do payload. 3. (Opcional) Consulte o grupo e remova operações antes do envio. 4. Envie o grupo para assinatura com `PUT /document/document_batch_group/{key}/send_to_signature` e obtenha o **link único** do beneficiário. 5. O beneficiário assina todas as operações de uma vez; cada operação evolui individualmente e o grupo é concluído quando todas chegam a um status terminal. ::: :::info Grupo × lote Cada operação (dívida, proposta de portabilidade/refin ou reserva de cartão) continua sendo **um lote** (envelope). O **grupo** é a camada acima dos lotes (pasta), responsável por reunir os envelopes e disparar **uma única assinatura**. Se você ainda utiliza o fluxo de [lote externo](/documentation/guides/INSS/signatures/batch-signature), consulte a [tabela de migração](#migracao) ao final desta página. ::: :::caution Regras do grupo - **Assinante único:** o grupo suporta **apenas um assinante** (o beneficiário). Não é possível informar múltiplos assinantes na pasta. - **Mesma titularidade:** o assinante informado na abertura do grupo deve ser **o mesmo** de todas as operações anexadas. Operação com assinante divergente retorna **erro síncrono** (`DOC000121`). - **Tipos permitidos:** o grupo aceita operações INSS de Crédito Novo, Portabilidade/Refinanciamento e Cartão Consignado, desde que compartilhem o mesmo assinante. - **Limite de operações:** o grupo aceita **no máximo 7 operações** (lotes). A inclusão de uma operação além do limite retorna **erro síncrono** (`DOC000127`). - **Contato obrigatório:** informe `signer_email` e/ou `signer_phone` no assinante. Sem um meio de contato, não é possível gerar o link de assinatura. - **Certificador:** derivado automaticamente da configuração do requester (`qi_sign`); não é enviado na requisição. ::: :::info Convivência com os fluxos atuais (período de transição) O fluxo de grupo é **opcional e aditivo**: ele só é acionado quando `document_batch_group_key` é enviado na criação da operação. Os fluxos existentes — assinatura individual por operação com o certificador configurado para o requester (inclusive certificadores externos, como `client_side`) e o [lote externo](/documentation/guides/INSS/signatures/batch-signature) — **continuam funcionando sem alteração** durante o período de transição. Dentro do grupo, a assinatura é sempre coletada via **QI Sign**, mesmo que o requester utilize outro certificador nos fluxos regulares. ::: --- ## 1. Abrir o grupo ENDPOINT /document/document_batch_group MÉTODO POST Request Body ```json { "batch_group_type": "social_security", "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696", "signer": { "signer_document_number": "14471835092", "signer_name": "Nome devedor", "signer_email": "maria.silva@email.com", "signer_phone": { "country_code": "55", "area_code": "11", "number": "999538380" }, "signer_role": "issuer", "signature_method": "whatsapp" }, "personal_document": { "type": "rg", "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0", "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b" } } ``` ### Body Params :::info Certificador O certificador (`qi_sign`) é **derivado** da configuração do requester e **não** é enviado na requisição. Requesters cuja configuração não use `qi_sign` recebem `DOC000118`. ::: | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `batch_group_type` | string | Tipo do grupo. Atualmente o único valor é `social_security`. | **[Batch Group Type](#batch-group-type)** | | `request_control_key` | string | Chave de **idempotência** (UUID v4), **obrigatória**. Reenviar o mesmo valor retorna o grupo já existente (evita grupos/pastas duplicados em retentativas). Não reutilize entre grupos distintos. | 36 | | `signer` | object | Dados do beneficiário que assinará todas as operações do grupo. | **[Signer Object](#signer-object)** | | `personal_document` | object | (Opcional) Documento de identificação do beneficiário coletado previamente, para dispensar a foto do documento durante a jornada de assinatura. | **[Documento pré-coletado](#documento-de-identificacao-pre-coletado)** | ### Signer Object | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `signer_document_number` | string | CPF/CNPJ do assinante (apenas dígitos). | 11 a 14 | | `signer_name` | string | Nome do assinante. | 100 | | `signer_email` | string | E-mail para envio do link de assinatura. (opcional) | 255 | | `signer_phone.country_code` | string | Código do país (ex.: `"55"`). (opcional) | 5 | | `signer_phone.area_code` | string | DDD do assinante. (opcional) | 5 | | `signer_phone.number` | string | Número de telefone do assinante. (opcional) | 15 | | `signer_role` | string | Papel do assinante (ex.: `issuer`). **Deve ser igual ao papel do assinante nas operações anexadas**, caso contrário a inclusão retorna `DOC000121`. | 100 | | `signature_method` | string | Canal de envio do link de assinatura. (opcional) | **[Signature Method](#signature-method)** | | `birth_date` | string | Data de nascimento do assinante (`AAAA-MM-DD`). (opcional) | 10 | ### Documento de identificação pré-coletado {#documento-de-identificacao-pre-coletado} Se o seu fluxo já coleta o documento de identificação do beneficiário (RG, CNH etc.) antes da assinatura, envie-o na abertura do grupo pelo objeto **`personal_document`**. As imagens são encaminhadas ao QI Sign junto com a criação da pasta e a etapa de captura do documento chega **pré-atendida** na jornada — o beneficiário não precisa fotografar o documento novamente durante a assinatura. O envio acontece em duas etapas: 1. **Faça o upload dos arquivos previamente** pelo [fluxo de upload de documentos](../../../upload_de_documentos/upload_de_documentos.md) e guarde a `document_key` de cada arquivo (um arquivo por lado do documento, ou um arquivo único no caso de documento digital). 2. **Referencie as chaves** no objeto `personal_document` da abertura do grupo. ```json title="Trecho ilustrativo (raiz do payload de abertura do grupo)" { "personal_document": { "type": "rg", "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0", "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b" } } ``` #### Personal Document Object | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `type` | string | Tipo do documento de identificação. | **[Personal Document Type](#personal-document-type)** | | `document_identification_front_key` | string | `document_key` do arquivo com a **frente** do documento. Obrigatório no modo frente e verso (junto com `..._back_key`). | 36 | | `document_identification_back_key` | string | `document_key` do arquivo com o **verso** do documento. Obrigatório no modo frente e verso (junto com `..._front_key`). | 36 | | `document_identification_full_key` | string | `document_key` do arquivo **único** com o documento completo (documento digital). Não pode ser combinado com as chaves de frente/verso. | 36 | :::caution Regras do documento pré-coletado - Envie **frente + verso** (`document_identification_front_key` + `document_identification_back_key`) **ou** o **arquivo único** (`document_identification_full_key`) — nunca os dois modos juntos. - Cada `type` suporta modos específicos — veja **[Personal Document Type](#personal-document-type)**. Combinação inválida retorna `DOC000128`. - Os documentos referenciados devem pertencer ao seu requester e já ter o **arquivo enviado** (upload concluído). Chave inexistente ou de outro requester retorna `DOC000004`; documento sem arquivo retorna `DOC000049`. - O envio é feito **apenas na abertura do grupo** — não é possível adicionar ou trocar o documento depois que o grupo foi criado. Se algum arquivo for rejeitado, a criação do grupo falha por inteiro (nenhum grupo é criado). ::: O objeto `personal_document` enviado é ecoado nas [consultas do grupo](#3-consultar-o-grupo). --- ### Response STATUS 201 Response Body ```json { "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc", "status": "pending_batches" } ``` | Campo | Tipo | Descrição | |---|---|---| | `document_batch_group_key` | string | Identificador do grupo. Guarde para os próximos passos. | | `status` | string | Status inicial do grupo: `pending_batches`. Veja **[Status do grupo](#status-do-grupo)**. | --- ## 2. Incluir operações no grupo Ao criar cada operação, envie **`document_batch_group_key` na raiz do JSON** (mesmo nível dos demais campos principais do produto). A operação é criada normalmente, mas a sua assinatura fica **vinculada à pasta do grupo** — não é gerado link de assinatura individual. Crédito Novo / Refin POST /debt Portabilidade / Refin POST /v2/credit_transfer/proposal Cartão POST /payroll_card_reservation/social_security | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `document_batch_group_key` | string | A `document_batch_group_key` retornada na abertura do grupo; enviada na raiz do payload de criação da operação. Obrigatório no fluxo com grupo. | 36 | ```json title="Trecho ilustrativo (raiz do payload)" { "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc" } ``` O restante do body segue o contrato de cada endpoint. Consulte os [roteiros de crédito consignado INSS](/documentation/guides/INSS/intro) conforme o produto. :::info Resposta da operação no fluxo com grupo Como o link de assinatura passa a ser **único e no nível do grupo**, a resposta de criação da operação **não retorna** dados de assinatura individuais (ex.: `signature_information` na proposta de portabilidade/refin). O link é obtido apenas no [envio do grupo para assinatura](#5-enviar-para-assinatura). ::: --- ## 3. Consultar o grupo ENDPOINT /document/document_batch_group/{document_batch_group_key} MÉTODO GET Recomendado antes de enviar para assinatura, para conferir as operações agrupadas e seus status. ### Path Params | Campo | Tipo | Descrição | |---|---|---| | `document_batch_group_key` | string | Chave do grupo. | :::info Consulta por idempotência Também é possível consultar pela `request_control_key`: `GET /document/document_batch_group/request_control_key/{request_control_key}`. ::: ### Exemplo de chamada ``` GET /document/document_batch_group/17f35e19-a039-468f-aaa7-84aa8edec3dc ``` --- ### Response STATUS 200 Response Body ```json { "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc", "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696", "external_key": "c109d589-ae18-4f4f-ad31-2879bf714c71", "group_name": "Assinatura de operações INSS", "batch_group_type": "social_security", "status": "pending_batches", "signature_url": null, "personal_document": { "type": "rg", "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0", "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b" }, "batches": [ { "document_batch_key": "5cca1dad-28fe-4f19-8bbb-0edd6f042384", "origin_key": "324caa35-ba10-4590-ae2b-5efef71709c3", "origin_type": "credit_operation", "status": "pending_signature" }, { "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53", "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497", "origin_type": "credit_transfer_proposal", "status": "pending_signature" } ] } ``` | Campo | Tipo | Descrição | |---|---|---| | `document_batch_group_key` | string | Identificador do grupo. | | `request_control_key` | string | Chave de idempotência informada na abertura do grupo. | | `external_key` | string | Identificador da pasta no QI Sign. | | `group_name` | string | Nome gerado para o grupo (ex.: `Assinatura de operações INSS`). | | `batch_group_type` | string | Tipo do grupo. Veja **[Batch Group Type](#batch-group-type)**. | | `status` | string | Status do grupo. Veja **[Status do grupo](#status-do-grupo)**. | | `signature_url` | string | Link único de assinatura do beneficiário. Disponível após o envio para assinatura. Com o [preenchimento automático do login](#5-enviar-para-assinatura) habilitado, retorna o link já autenticado. | | `personal_document` | object | [Documento de identificação pré-coletado](#documento-de-identificacao-pre-coletado) informado na abertura do grupo (`null` se não enviado). | | `batches` | array | Operações anexadas ao grupo. **[Batch Object](#batch-object)** | ### Batch Object | Campo | Tipo | Descrição | |---|---|---| | `document_batch_key` | string | Chave do lote (envelope) da operação. | | `origin_key` | string | Chave da operação de origem. Veja **[Origin Type](#origin-type)**. | | `origin_type` | string | Tipo da operação de origem. Veja **[Origin Type](#origin-type)**. | | `status` | string | Status da operação dentro do grupo. Veja **[Status da operação](#status-da-operação)**. | --- ## 4. Remover operação do grupo Desvincula e cancela uma operação específica antes do envio para assinatura (para reagrupar, se necessário). Só é permitido enquanto o grupo está em `pending_batches`. ENDPOINT /document/document_batch_group/{document_batch_group_key}/remove_batch MÉTODO PUT ### Path Params | Campo | Tipo | Descrição | |---|---|---| | `document_batch_group_key` | string | Chave do grupo. | Request Body ```json { "origin_key": "324caa35-ba10-4590-ae2b-5efef71709c3" } ``` ### Body Params | Campo | Tipo | Descrição | |---|---|---| | `origin_key` | string | Chave da operação a remover (a mesma `origin_key` retornada na consulta do grupo). | --- ### Response STATUS 201 Retorna o grupo atualizado, já sem a operação removida em `batches` (mesmo formato da [consulta do grupo](#3-consultar-o-grupo)). Response Body ```json { "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc", "status": "pending_batches", "signature_url": null, "batches": [ { "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53", "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497", "origin_type": "credit_transfer_proposal", "status": "pending_signature" } ] } ``` --- ## 5. Enviar para assinatura Fecha o grupo e dispara a pasta para assinatura no QI Sign. Retorna o **link único** (`signature_url`) que o beneficiário usa para assinar todas as operações de uma só vez. ENDPOINT /document/document_batch_group/{document_batch_group_key}/send_to_signature MÉTODO PUT ### Path Params | Campo | Tipo | Descrição | |---|---|---| | `document_batch_group_key` | string | Chave do grupo. | **Body:** objeto JSON vazio `{}`. :::caution Pré-condições do envio - O grupo precisa estar em `pending_batches`. - Deve haver **ao menos uma** operação anexada (`DOC000120`). - Todas as operações devem ter o **mesmo assinante** do grupo (`DOC000121`). ::: --- ### Response STATUS 201 O grupo passa para `pending_signature` e a `signature_url` é preenchida. Response Body ```json { "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc", "status": "pending_signature", "signature_url": "https://sign.sandbox.qitech.app/f/17f35e19-a039-468f-aaa7-84aa8edec3dc", "batches": [ { "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53", "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497", "origin_type": "credit_transfer_proposal", "status": "pending_signature" } ] } ``` | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status do grupo após o envio: `pending_signature`. | | `signature_url` | string | Link único de assinatura do beneficiário. | | `batches` | array | Operações do grupo. **[Batch Object](#batch-object)** | :::info Link com preenchimento automático do login Sob demanda, é possível habilitar o **preenchimento automático do login**. Com a opção habilitada, a `signature_url` retornada no envio para assinatura e nas [consultas do grupo](#3-consultar-o-grupo) passa a ser um **link autenticado**: a tela de login da jornada de assinatura já vem preenchida com os dados do beneficiário. ::: --- ## Acompanhamento Após o envio, o beneficiário assina todas as operações com **um único link**. Na jornada de assinatura, o beneficiário pode **aceitar ou recusar cada operação individualmente** — desfechos parciais são normais (ex.: duas operações assinadas e uma recusada no mesmo grupo). Cada operação evolui de forma independente e o grupo é concluído (`completed`) quando **nenhuma** operação permanece em `pending_signature`, independentemente da combinação de desfechos. Acompanhe o desfecho de cada operação pelos webhooks do respectivo produto (abaixo) ou pela [consulta do grupo](#3-consultar-o-grupo). :::info Submissão automática (Portabilidade/Refin) No fluxo com grupo, após a assinatura da proposta de portabilidade/refin a submissão à registradora é feita **automaticamente** — a proposta avança para `pending_response` sem necessidade do `PATCH` manual de submissão. ::: ### Webhook de operação assinada Cada operação assinada segue o **mesmo fluxo de webhooks do produto** (dívida emitida, proposta submetida etc.) — nenhum campo muda em relação ao fluxo sem grupo. Consulte os webhooks de cada produto nos [roteiros INSS](/documentation/guides/INSS/intro). ### Webhook de assinatura recusada Quando o beneficiário **recusa** uma operação do grupo, a operação é **cancelada** no respectivo produto e o parceiro recebe o webhook de mudança de status com o motivo `signature_rejected`: **Crédito Novo / Refin (dívida):** ```json { "key": "324caa35-ba10-4590-ae2b-5efef71709c3", "data": { "cancel_reason": "Operação cancelada porque o assinante recusou a assinatura.", "cancel_reason_enumerator": "signature_rejected" }, "status": "canceled", "webhook_type": "debt", "event_datetime": "2026-07-06 14:30:00" } ``` **Portabilidade / Refin (proposta):** ```json { "webhook_type": "credit_transfer.proposal", "proposal_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497", "event_datetime": "2026-07-06T14:30:00", "proposal_status": "canceled", "cancel_reason": "signature_rejected" } ``` | Produto | `webhook_type` | Campo de status | Motivo da recusa | |---|---|---|---| | Crédito Novo / Refin | `debt` | `status: "canceled"` | `data.cancel_reason_enumerator: "signature_rejected"` | | Portabilidade / Refin | `credit_transfer.proposal` | `proposal_status: "canceled"` | `cancel_reason: "signature_rejected"` | Na [consulta do grupo](#3-consultar-o-grupo), a operação recusada aparece com status `sign_rejected`. --- ## Erros | HTTP | Código | Quando ocorre | |---|---|---| | 400 | `DOC000118` | O certificador configurado para o requester não é suportado (apenas `qi_sign`). | | 404 | `DOC000117` | Grupo não encontrado para a chave informada. | | 409 | `DOC000119` | Grupo não está em `pending_batches` e não pode ser modificado. | | 400 | `DOC000120` | Envio para assinatura sem nenhuma operação anexada. | | 400 | `DOC000121` | Assinante de uma operação difere do assinante do grupo. | | 400 | `DOC000122` | `origin_key` não informado na remoção. | | 404 | `DOC000123` | `origin_key` não encontrado entre as operações do grupo. | | 400 | `DOC000127` | O grupo já possui o número máximo de operações (5). | | 400 | `DOC000128` | O `type` do documento pré-coletado não suporta o modo enviado (frente e verso × arquivo único). Veja **[Personal Document Type](#personal-document-type)**. | | 400 | `DOC000129` | A jornada de assinatura configurada para o requester não coleta documento de identificação — o envio de documento pré-coletado não se aplica. | | 400 | `DOC000130` | O `type` do documento pré-coletado não está entre os tipos aceitos pela configuração do requester. | | 404 | `DOC000004` | `document_key` do documento pré-coletado não encontrada (inclui documento pertencente a outro requester). | | 400 | `DOC000049` | Documento pré-coletado sem arquivo — o upload não foi concluído antes da abertura do grupo. | | 400 | `DOC000126` | Configuração do requester incompleta. | | 404 | `DOC000091` | Configuração de certificador não encontrada para o requester. | --- ## Enumeradores ### Batch Group Type | Enumerador | Descrição | |---|---| | `social_security` | Operações de crédito consignado INSS. | ### Signature Method | Enumerador | Descrição | |---|---| | `email` | Link de assinatura enviado por e-mail. | | `sms` | Link de assinatura enviado por SMS. | | `whatsapp` | Link de assinatura enviado por WhatsApp. | ### Personal Document Type Tipos aceitos no [documento de identificação pré-coletado](#documento-de-identificacao-pre-coletado) e os modos de envio suportados por cada um: | Enumerador | Documento | Frente e verso | Arquivo único | |---|---|---|---| | `rg` | Registro Geral (RG) | ✔ | — | | `cnh` | Carteira Nacional de Habilitação | ✔ | ✔ | | `cin` | Carteira de Identidade Nacional | — | ✔ | - **Frente e verso:** envie `document_identification_front_key` + `document_identification_back_key`. - **Arquivo único:** envie apenas `document_identification_full_key` (documento digital, ex.: CNH digital). ### Origin Type | Enumerador | Operação | `origin_key` | |---|---|---| | `credit_operation` | Crédito Novo / Refin (`POST /debt`) | `credit_operation_key` | | `credit_transfer_proposal` | Portabilidade / Refin (`POST /v2/credit_transfer/proposal`) | `proposal_key` | | `payroll_card_reservation` | Cartão Consignado (`POST /payroll_card_reservation/social_security`) | chave da reserva | ### Status do grupo | Status | Descrição | |---|---| | `pending_batches` | Grupo aberto, recebendo operações. Permite incluir/remover operações. | | `pending_signature` | Enviado para assinatura; aguardando o beneficiário assinar. | | `completed` | Todas as operações do grupo chegaram a um status terminal. | | `canceled` | Grupo cancelado. | ### Status da operação | Status | Descrição | |---|---| | `pending_signature` | Operação anexada ao grupo, aguardando assinatura. | | `signed` | Operação assinada com sucesso. | | `sign_rejected` | Beneficiário recusou a assinatura da pasta. | | `canceled` | Operação/pasta cancelada. | --- ## Migração do lote externo para o grupo {#migracao} O fluxo de [lote externo](/documentation/guides/INSS/signatures/batch-signature) (`document_batch_key`) é substituído pelo fluxo de grupo (`document_batch_group_key`). Principais diferenças: - Você **não** cria mais o lote e adiciona documentos manualmente: cada operação (`/debt`, `/v2/credit_transfer/proposal`, cartão) já é um lote, e o **grupo** apenas os reúne. - O link de assinatura passa a ser **único e no nível do grupo**, retornado no envio para assinatura — não há link por operação. | Antigo (lote externo) | Novo (grupo) | |---|---| | `POST /document/document_batch` (`type: social_security_external_batch`) | `POST /document/document_batch_group` | | `document_batch_key` na raiz da operação | `document_batch_group_key` na raiz da operação | | `GET /document/document_batch/{key}` | `GET /document/document_batch_group/{key}` | | `DELETE /document/document_batch/{key}/documents` (limpar tudo) | `PUT /document/document_batch_group/{key}/remove_batch` (remover uma operação) | | `PUT /document/document_batch/{key}/send_to_signature` | `PUT /document/document_batch_group/{key}/send_to_signature` |