# QI Tech — Crédito Consignado › INSS Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 13 página(s). Índice: - Consulta Offline de Saldo (/documentation/guides/INSS/inquiries/offline-balance-request) - Mocks (Sandbox) (/documentation/guides/INSS/mocks-sandbox) - Novo e Refin Puro (/documentation/guides/INSS/new-credit-and-refinancing/end-to-end) - Recálculo (/documentation/guides/INSS/new-credit-and-refinancing/recalculate) - Anuência (pending confirmation) (/documentation/guides/INSS/pending_confirmation) - Alterando o Cessionário (/documentation/guides/INSS/portability+refinancing/alterando-cessionario) - Consultas e Enumeradores (/documentation/guides/INSS/portability+refinancing/consultas-e-enumeradores) - Portabilidade + Refin (/documentation/guides/INSS/portability+refinancing/end-to-end) - Máquinas de Status (/documentation/guides/INSS/portability+refinancing/maquinas-de-status) - Recálculo e Reformalização do Refinanciamento (/documentation/guides/INSS/portability+refinancing/reformalization) - Fura-fila (priority request) (/documentation/guides/INSS/reservations/priority-request) - Fila prioritária (/documentation/guides/INSS/reservations/priority-reservation) - Assinatura em grupo (INSS) (/documentation/guides/INSS/signatures/batch-group-signature) --- # Consulta Offline de Saldo URL: /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" } ``` --- # Mocks (Sandbox) URL: /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 --- # Novo e Refin Puro URL: /documentation/guides/INSS/new-credit-and-refinancing/end-to-end Fluxo Completo - Crédito Novo e Refinanciamento Puro :::danger Atenção! Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs. ::: :::info Reenvio de Webhooks Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes). ::: :::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. ::: ## 1 - Consulta da lista de benefícios com formalização do Termo de Autorização realizada através do parceiro: ### 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). 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" } ``` 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_status | Status do beneficio | [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](#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 | ::: --- ## 2 - Consulta de dados do benefício: {#consulta-de-dados} ### Caso 1 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 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](#benefit_type_enumerator) | | benefit_status | Status do beneficio | [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](#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](#block_type_enumerator) | politically_exposed.type | Pessoa politicamente exposta | [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](#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](#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). --- ## 3 - Simulação da dívida: ### 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 } } ] } } ``` --- ## 4 - Emissão de Operação: :::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](#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 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" } }, { "disbursement_date": "2024-11-09", "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": 915.28, "issue_amount": 910.73, "cet": "2,0200%", "annual_cet": "27,0599%", "base_iof": 16.115620969325082, "additional_iof": 3.460774, "total_iof": 19.58, "total_pre_fixed_amount": 107.6655097248, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 72, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 910.73, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 36.1935236262, "principal_amortization_amount": 65.6464763738, "tax_amount": 0.3875767965109152, "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.0835236262, "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.7393648365913253, "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.5432872313, "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.9696956848062798, "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.2718587444, "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.207818878655416, "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.4578433774, "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.4645309277209473, "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.4363159561, "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.7123515150140312, "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.7935556469, "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.983394052470154, "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.5662629414, "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.2589659165472766, "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.5649783078, "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.554203783920473, "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.3036955533, "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.837718577088265, "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-10", "contract_fees": [ { "fee_type": "spread", "fee_amount": 4.56 }, { "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.06, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "assignment_amount": 915.79, "issue_amount": 911.23, "cet": "2,0200%", "annual_cet": "27,0635%", "base_iof": 16.0438115087348, "additional_iof": 3.462674, "total_iof": 19.51, "total_pre_fixed_amount": 107.1724201311, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 71, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 911.23, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 35.7004340324, "principal_amortization_amount": 66.1395659676, "tax_amount": 0.3850645530633672, "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.0904340324, "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.7321865372069436, "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.5501976375, "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.962293427670354, "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.2787691506, "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.200454129395322, "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.4647537836, "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.4569031624724007, "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.4432263623, "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.7046728086686769, "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.8004660531, "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.975585414468303, "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.5731733476, "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.2510118112073214, "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.571888714, "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.546146358734604, "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.3106059595, "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.829493305847507, "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-11", "contract_fees": [ { "fee_type": "spread", "fee_amount": 4.56 }, { "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.06, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "assignment_amount": 916.28, "issue_amount": 911.72, "cet": "2,0200%", "annual_cet": "27,0698%", "base_iof": 15.971922713858204, "additional_iof": 3.464536, "total_iof": 19.44, "total_pre_fixed_amount": 106.6790635687, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 70, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 911.72, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 35.2070774702, "principal_amortization_amount": 66.6329225298, "tax_amount": 0.382472975321052, "total_amount": 101.84, "workdays": 47.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.0870774702, "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.7250082378225619, "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.5468410753, "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.9548911705344282, "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.2754125884, "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.193089380135228, "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.4613972214, "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.449275397223854, "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.4398698001, "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.6969941023233224, "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.7971094909, "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.967776776466452, "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.5698167854, "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.243057705867366, "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.5685321518, "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.538088933548735, "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.3072493973, "fine_amount": null, "has_interest": true, "installment_number": 10, "post_fixed_amount": null, "pre_fixed_amount": 1.5318141714, "principal_amortization_amount": 100.3081858286, "tax_amount": 2.8212680346152035, "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-12", "contract_fees": [ { "fee_type": "spread", "fee_amount": 4.56 }, { "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.06, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "assignment_amount": 916.77, "issue_amount": 912.21, "cet": "2,0200%", "annual_cet": "27,0762%", "base_iof": 15.899954519820076, "additional_iof": 3.466398, "total_iof": 19.37, "total_pre_fixed_amount": 106.1854398936, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 69, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 912.21, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 34.7134537949, "principal_amortization_amount": 67.1265462051, "tax_amount": 0.3798019984284558, "total_amount": 101.84, "workdays": 46.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.0834537949, "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.71782993843818, "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.5432174, "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.9474889133985024, "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.2717889131, "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.185724630875134, "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.4577735461, "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.4416476319753073, "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.4362461248, "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.689315395977968, "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.7934858156, "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.959968138464601, "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.5661931101, "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.2351036005274114, "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.5649084765, "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.530031508362866, "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.303625722, "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.8130427633716497, "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-13", "contract_fees": [ { "fee_type": "spread", "fee_amount": 4.56 }, { "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.06, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "assignment_amount": 917.27, "issue_amount": 912.71, "cet": "2,0200%", "annual_cet": "27,0802%", "base_iof": 15.827906861727051, "additional_iof": 3.468298, "total_iof": 19.3, "total_pre_fixed_amount": 105.691548961, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 68, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 912.71, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 34.2195628621, "principal_amortization_amount": 67.6204371379, "tax_amount": 0.3770515574809304, "total_amount": 101.84, "workdays": 45.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.0895628621, "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.7106516390537982, "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.5493264672, "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.9400866562625766, "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.2778979803, "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.17835988161504, "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.4638826133, "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.4340198667267607, "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.442355192, "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.6816366896326136, "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.7995948828, "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.95215950046275, "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.5723021773, "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.227149495187456, "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.5710175437, "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.521974083176997, "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.3097347892, "fine_amount": null, "has_interest": true, "installment_number": 10, "post_fixed_amount": null, "pre_fixed_amount": 1.5318141718, "principal_amortization_amount": 100.3081858282, "tax_amount": 2.8048174921281284, "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-14", "contract_fees": [ { "fee_type": "spread", "fee_amount": 4.57 }, { "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.07, "external_contract_fee_amount": 0.0, "net_external_contract_fee_amount": 0.0, "assignment_amount": 917.77, "issue_amount": 913.2, "cet": "2,0200%", "annual_cet": "27,0870%", "base_iof": 15.755779674642707, "additional_iof": 3.47016, "total_iof": 19.23, "total_pre_fixed_amount": 105.1973906257, "installments": [ { "additional_costs": [], "business_due_date": "2025-01-20", "calendar_days": 67, "due_date": "2025-01-20", "due_interest": 0.0, "due_principal": 913.2, "fine_amount": null, "has_interest": true, "installment_number": 1, "post_fixed_amount": null, "pre_fixed_amount": 33.7254045271, "principal_amortization_amount": 68.1145954729, "tax_amount": 0.3742215875281126, "total_amount": 101.84, "workdays": 44.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.0854045271, "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.7034733396694164, "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.5451681322, "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.9326843991266508, "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.2737396453, "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.170995132354946, "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.4597242783, "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.4263921014782142, "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.438196857, "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.6739579832872593, "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.7954365478, "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.944350862460899, "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.5681438423, "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.219195389847501, "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.5668592087, "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.513916657991128, "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.3055764542, "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.79659222089858, "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 | ::: ## 5 - 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](../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** ::: ## 6 - 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)](#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" } ``` ## 7 - Averbação e Desaverbação :::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](#consulta-de-dados). ::: ### 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](#consulta-de-dados); 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" } ``` ## 8 - Falha no desembolso ### 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" } ``` ## 9 - 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) ## 10 - Recuperar resposta da última request 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](#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](#dataprev_response_enumerator_errors)| | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ## 11 - Recuperar ú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" } ``` ## 12 - Webhook de resposta 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: 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. Mapeamento de enumeradores ### 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 | Cancelar | | 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 | ### 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} | Enumerador | Descrição | |------------|-----------------------------------------------------| | not_blocked | Sem bloqueio | | blocked_by_benefitiary | Bloqueado pelo Segurado | | blocked_by_tbm | Bloqueado por TBM | | 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 | --- # Recálculo URL: /documentation/guides/INSS/new-credit-and-refinancing/recalculate Recálculo Recalcula as condições financeiras de uma operação de crédito existente a partir de um **novo valor de parcela**. Ideal para quando a margem consignável do beneficiário muda e o valor da parcela precisa ser ajustado. ## Request ENDPOINT /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate MÉTODO POST ### Path Params credit_operation_key string (UUID) obrigatório Chave única da operação de crédito a ser recalculada. ### Body Params installment_face_value number obrigatório Novo valor de face da parcela. Deve ser menor ou igual ao valor original e acima do mínimo permitido (20.00). ```python { "installment_face_value": 180.50 } ``` :::caution Atenção O novo `installment_face_value` precisa ser **menor** que o valor original. O endpoint rejeita valores superiores ao original ou fora da redução máxima permitida (30%). ::: ### Pré-condições A operação deve 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) | | Garantia do tipo `social_security` | [`COP000276`](#COP000276) | | Status: `waiting_signature`, `issued` ou `canceled` | [`COP000489`](#COP000489) | | Garantia ainda não constituída | [`COP000489`](#COP000489) | | Tipo de operação: `structured_operation` | [`COP000489`](#COP000489) | | Data limite de desembolso não expirada | [`COP000489`](#COP000489) | | Operação original possui `installment_face_value` | [`COP000489`](#COP000489) | | Novo valor dentro dos limites permitidos | [`COP000490`](#COP000490) | ## Response STATUS 200 Retorna o objeto completo da operação de crédito recalculada — mesma estrutura da [consulta por credit_operation_key](/documentation/emissao_de_divida/consulta_por_credit_operation_key). ## Erros | Código HTTP | Código QI | Descrição | Tradução | |-------------|-----------|-----------|----------| | 404 | `COP000027` | Credit Operation not found | Operação não encontrada | | 403 | `QIT000005` | Selected agent does not own this item | O agente selecionado não é dono do item | | 400 | `COP000276` | Collateral type doesn't allow recalculation | Garantia do contrato não permite que a operação seja recalculada | | 400 | `COP000335` | Assignment amount exceeds operation 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` | Operation not allowed to be recalculated | A operação de crédito não está permitida para ser recalculada | | 400 | `COP000490` | Installment face value variance not allowed | A variação do valor da parcela não está permitida | 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 | |--------|-----------| | Status inválido | O status da operação de crédito não permite ser recalculada | | Garantia já constituída | A operação de crédito já possui garantia constituída | | Tipo de operação inválido | O tipo de operação de crédito não permite ser recalculada | | Data de desembolso expirada | A data de término do desembolso da operação de crédito está no passado | | Valor de parcela ausente | O valor da parcela não foi informado na operação original | --- # Anuência (pending confirmation) URL: /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: /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: /documentation/guides/INSS/portability+refinancing/consultas-e-enumeradores Consultas e Enumeradores Endpoints auxiliares e tabelas de referência para o fluxo de Port+Refin INSS. ## 9 - Consulta de Lista de Participantes do CTC - CIP: **Request** - MÉTODO GET - ENDPOINT /v2/credit_transfer/participants Testar no Playground *Response:* **response.json** ```json [ { "name": "\", "bank_code": "\", "ispb": "\" } ] ``` ## 10 - Recuperar resposta da última request 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 - 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 | 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](#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](#dataprev_response_enumerator_errors) | | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ## 11 - Webhook de resposta 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](#dataprev_response_enumerator_errors) | | reservation_method | Método de averbação da reserva | portability, new_credit, refinancing| ## 12 - Consulta de portabilidade de origem É 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" } } ``` ## 13. Diminuir o valor das parcelas 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 } ``` ## 14. Mapeamento de enumeradores ### 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 | Teimosinha | | 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 | 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 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} | Enumerador | Descrição | |------------|-----------------------------------------------------| | 0 | Sem bloqueio | | 1 | Bloqueado pelo Segurado | | 2 | Bloqueado por TBM | | 3 | 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 | --- # Portabilidade + Refin URL: /documentation/guides/INSS/portability+refinancing/end-to-end Fluxo Completo - Portabilidade + Refinanciamento :::danger Atenção! Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs. ::: :::info Reenvio de Webhooks Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes). ::: Para iniciar o processo de Portabilidade + Refinanciamento - INSS, primeiramente é necessário coletar os dados do benefício para checagem da elegibilidade como também os dados da conta de pagamento do benefício. Os itens 1 e 2, descrevem o procedimento para consulta da lista de benefícios de um determinado beneficiário e procedimento para consulta dos dados do benefício. Para acompanhamento dos status após a formalização, consulte [Máquinas de Status](./maquinas-de-status). ## 1 - Consulta da lista de benefícios com formalização do Termo de Autorização realizada através do parceiro: **1.1.** Titular do benefício é o assinante do Termo de Autorização. **Request** - 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.** Titular do benefício **não** é o assinante do Termo de Autorização (com representante legal). :::caution Atenção Como o assinante do termo nesse caso é o representante legal, os dados que preenchem o objeto **signer**, são os dados do representante legal. ::: **Request** - 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 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 :::info **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** - 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" } ] } ``` Em caso de sucesso na consulta da lista de benefícios: **Webhook** - WEBHOOK_TYPE social_security_benefits_request - STATUS Success **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" } } ``` | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | benefit_number | Número do beneficio | - | | benefit_status | Status do beneficio | [Enumeradores](#benefit_status_enumerator) | Em caso de falha na consulta da lista de benefícios: **Webhook** - WEBHOOK_TYPE social_security_benefits_request - STATUS Failure **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" } } ``` ### Detalhamento de campos no webhook de falha | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [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 | ::: --- ## 2 - Consulta de dados do benefício {#consulta-de-dados} **2.1.** Consulta de dados do benefício com o Termo de Autorização previamente enviado. **Request** - MÉTODO POST - ENDPOINT /social_security/balance_request Testar no Playground *Payload:* **payload.json** ```json { "document_number": "16514548091", "benefit_number": 2052711150 } ``` **Response** - MÉTODO POST - ENDPOINT /social_security/balance_request **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.** Consulta de dados do benefício com envio do Termo de Autorização. **Request** - 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 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** - MÉTODO POST - ENDPOINT /social_security/balance_request **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" } ] } ``` Em caso de sucesso na consulta de dados do benefício **Webhook** - WEBHOOK_TYPE /social_security/balance_request - STATUS Success **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" } } ``` ### Detalhamento de campos no webhook de sucesso | Campo | Descrição | Valores | |---------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| | assistance_type | Tipo do benefício | [Enumeradores](#benefit_type_enumerator) | | benefit_status | Status do beneficio | [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](#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](#block_type_enumerator) | politically_exposed.type | Pessoa politicamente exposta | [Enumeradores](#politically_exposed_enumerator) | is_politically_exposed | Pessoa politicamente exposta | True ou False Em caso de falha na consulta da lista de benefícios **Webhook** - WEBHOOK_TYPE /social_security/balance_request - STATUS Failure **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" } } ``` ### Detalhamento de campos no webhook de falha | Campo | Descrição | Valores | |---------------------------|-------------------------------------|----------------------------------| | enumerator | Retorno mapeado do código Dataprev | [Enumeradores](#dataprev_balance_errors_enumerators) | ### Simulando cenários de sucesso e insucesso na consulta de dados do 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). --- ## 3 - Simulando Proposta de Portabilidade e/ou Refinanciamento: :::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 }] } } ``` --- ## 4 - Digitação da Proposta: :::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](#consulta-de-dados). ::: :::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](#consulta-de-dados); 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:** - MÉTODO GET - STATUS /v2/credit_transfer/proposal/PROPOSAL-KEY ou REQUESTER_CONTROL_KEY ## 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 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" } ``` ### 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 | ::: --- ## 5 - 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.](../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. ::: --- ## 6 - 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: /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](#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" } } ``` --- # Recálculo e Reformalização do Refinanciamento URL: /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. | --- # Fura-fila (priority request) URL: /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: /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: /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` |