Consulta de Margem & Simulação de Crédito

Consulta de margem

A consulta de margem permite identificar o valor máximo que o tomador pode comprometer mensalmente com um empréstimo consignado.

GET: https://platform.flowfinance.com.br/banking/originator/guarantee/{product-id}/get-balance

Parâmetros

Campo	Descrição	Tipo
taxpayer_id	CPF do tomador (somente números)	String

{
  "links": [
    {
      "employer": {
        "code": "123456", 
        "document": "95818221485", 
        "name": "Empresa Exemplo LTDA"
      },
      "employee": {
        "code": "1564882125",
        "document": "90110651669", 
        "name": "João da Silva"
      },
      "config": {
        "agency": "3a7e1beb-c64f-4936-8555-b9edb42c3328",
        "consignee": "468f5087-d35f-45dd-96db-3cf71a83fe08"
      },
      "products": [
        {
          "balance_check_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "authorization": {
            "details": [
              {
                "type_product": "LOAN",
                "authorized": true,
                "validity": "2025-12-31"
              }
            ],
            "portability": [
              {
                "authorized": false,
                "available_balance": 0,
                "type_product": "LOAN",
                "validity": "2025-12-31",
                "contract_port": {
                  "contract_id": "PORT123",
                  "document": "12345678900",
                  "name_consignee": "BANCO XYZ"
                }
              }
            ]
          },
          "rubric": {
            "code": "RUB001",
            "description": "Rubrica de Empréstimo"
          },
          "agreement": "AG001",
          "available_balance": 5000.75
        }
      ],
      "meta_data": {
        "nationality_country": {
          "description": "Brasil",
          "code": "BR"
        },
        "termination_reason_code": "TRC001",
        "birth_date": "1985-08-06",
        "worker_category_code": "101",
        "termination_date": "2025-06-01",
        "prior_notice_date": "2025-05-15",
        "prior_notice_end_date": "2025-06-15",
        "gender": {
          "description": "Masculino",
          "code": 1
        },
        "job_code": {
          "description": "Analista de Sistemas",
          "code": "21240"
        },
        "economic_activity_code": {
          "description": "Atividades de tecnologia",
          "code": "6201-5/01"
        },
        "politically_exposed_person": {
          "description": "Não",
          "code": 0
        },
        "unauthorization_reason": {
          "description": "Nenhum",
          "code": 0
        },
        "base_margin_value": "3000.00",
        "alerts": [
          {
            "absence_reason_code": "A001",
            "alert_type": {
              "description": "Licença Médica",
              "code": 1
            },
            "absence_date": "2025-01-10",
            "absence_end_date": "2025-01-25",
            "reference_date": "2025-01",
            "event_id": "EVT123",
            "termination_reason_code": "TRC001"
          }
        ],
        "amount_loans_assets_suspended": "2",
        "admission_date": "2010-03-15",
        "total_earnings": "8500.00",
        "legacy_loans": [
          {
            "financial_institution_code": 123,
            "contract": "CON123456789",
            "contract_start_date": "2021-01-01",
            "contract_end_date": "2026-01-01",
            "installment_amount": 350.25,
            "loan_amount": 10000.00,
            "net_amount": 9500.00,
            "update_date_time": "2025-08-01T10:00:00Z",
            "interest_tax": 1.85,
            "monthly_cet": 2.1,
            "installment_quantity": 60,
            "paid_installments_quantity": 30,
            "debtor_balance_amount": 5000.00,
            "contract_type": {
              "description": "Crédito Consignado",
              "code": 1
            }
          }
        ],
        "employer_activity_start_date": "2005-01-01",
        "mother_name": "Maria de Lourdes"
      },
      "balance_check_date": "2025-08-05"
    }
  ],
  "message": "Verificação de margem realizada com sucesso"
}

Parâmetros

Campo	Descrição	Tipo
employer.document	Documento (CNPJ) do empregador	String
employer.name	Nome do empregador	String
employee.code	Código do empregado	String
employee.document	Documento (CPF) do empregado	String
employee.name	Nome do empregado	String
config.agency	Identificador da agência ou origem da consulta	String
config.consignee	Identificador da consignatária	String
products[].balance_check_id	ID da verificação de saldo	String
products[].authorization.details[].type_product	Tipo de produto autorizado	String
products[].authorization.details[].authorized	Indica se está autorizado	boolean
products[].authorization.details[].validity	Data de validade da autorização	date
products[].authorization.portability[].authorized	Indica se a portabilidade está autorizada	boolean
products[].authorization.portability[].available_balance	Saldo disponível para portabilidade	number
products[].authorization.portability[].type_product	Tipo de produto de portabilidade	string
products[].authorization.portability[].validity	Validade da portabilidade	date
products[].authorization.portability[].contract_port.contract_id	ID do contrato de portabilidade	string
products[].authorization.portability[].contract_port.document	Documento da instituição portadora	string
products[].authorization.portability[].contract_port.name_consignee	Nome da instituição portadora	string
products[].rubric.code	Código da rubrica	string
products[].rubric.description	Descrição da rubrica	string
products[].agreement	Código do convênio	string
products[].available_balance	Saldo disponível para crédito	number
meta_data.nationality_country.description	Descrição da nacionalidade	string
meta_data.nationality_country.code	Código da nacionalidade	string
meta_data.termination_reason_code	Código do motivo de desligamento	string
meta_data.birth_date	Data de nascimento	date
meta_data.worker_category_code	Código da categoria do trabalhador	string
meta_data.termination_date	Data de desligamento	date
meta_data.prior_notice_date	Data do aviso prévio	date
meta_data.prior_notice_end_date	Data fim do aviso prévio	date
meta_data.gender.description	Descrição do gênero	string
meta_data.gender.code	Código do gênero	number
meta_data.job_code.description	Descrição do cargo	string
meta_data.job_code.code	Código do cargo	string
meta_data.economic_activity_code.description	Descrição da atividade econômica	string
meta_data.economic_activity_code.code	Código da atividade econômica	string
meta_data.politically_exposed_person.description	Pessoa politicamente exposta	string
meta_data.politically_exposed_person.code	Código PEP	number
meta_data.unauthorization_reason.description	Descrição da razão de não autorização	string
meta_data.unauthorization_reason.code	Código da razão de não autorização	number
meta_data.base_margin_value	Valor base da margem consignável	string
meta_data.alerts[].absence_reason_code	Código do motivo de ausência	string
meta_data.alerts[].alert_type.description	Descrição do tipo de alerta	string
meta_data.alerts[].alert_type.code	Código do tipo de alerta	number
meta_data.alerts[].absence_date	Data de início da ausência	date
meta_data.alerts[].absence_end_date	Data de fim da ausência	date
meta_data.alerts[].reference_date	Data de referência do alerta	string
meta_data.alerts[].event_id	ID do evento	string
meta_data.alerts[].termination_reason_code	Código do motivo de desligamento no alerta	string
meta_data.amount_loans_assets_suspended	Quantidade de empréstimos ativos/suspensos	number
meta_data.admission_date	Data de admissão	date
meta_data.total_earnings	Total de rendimentos	string
meta_data.legacy_loans[].financial_institution_code	Código da instituição financeira	number
meta_data.legacy_loans[].contract	Número do contrato	string
meta_data.legacy_loans[].contract_start_date	Data de início do contrato	date
meta_data.legacy_loans[].contract_end_date	Data de fim do contrato	date
meta_data.legacy_loans[].installment_amount	Valor da parcela	number
meta_data.legacy_loans[].loan_amount	Valor total do empréstimo	number
meta_data.legacy_loans[].net_amount	Valor líquido do empréstimo	number
meta_data.legacy_loans[].update_date_time	Data/hora da última atualização	datetime
meta_data.legacy_loans[].interest_tax	Taxa de juros	number
meta_data.legacy_loans[].monthly_cet	CET mensal	number
meta_data.legacy_loans[].installment_quantity	Quantidade de parcelas	number
meta_data.legacy_loans[].paid_installments_quantity	Quantidade de parcelas pagas	number
meta_data.legacy_loans[].debtor_balance_amount	Saldo devedor	number
meta_data.legacy_loans[].contract_type.description	Descrição do tipo de contrato	string
meta_data.legacy_loans[].contract_type.code	Código do tipo de contrato	number
meta_data.employer_activity_start_date	Data de início da atividade do empregador	date
meta_data.mother_name	Nome da mãe do trabalhador	string
balance_check_date	Data da verificação de margem	date

Retorno de erro:

Caso seja realizada a consulta de margem sem ter completado com sucesso o fluxo de autorização de
consulta dos dados do tomador, será emitido um erro indicando que a autorização ainda não foi concedida.:

{
  "message": "Erro na requisição",
  "detail": {
    "authorization_file": [
      "Arquivo inválido ou ausente"
    ],
    "taxpayer_id": [
      "CPF inválido"
    ],
    "product_id": [
      "ID do produto não encontrado"
    ]
  }
}

Resposta Assíncrona (Limite de Requisição da Dataprev)

A Dataprev possui uma limitação de 25 requisições por segundo. Caso, no momento da requisição, a Dataprev retorne que o limite daquele segundo foi atingido, nosso sistema responderá a consulta de margem de forma assíncrona.

Resposta assíncrona

{
    "message": "Request accepted for asynchronous processing"
}

Isso indica que a solicitação foi aceita e será processada posteriormente.

Notificação via Webhook
Quando a consulta for concluída, o resultado será enviado ao originador por meio de um webhook com o evento GuaranteeBalanceUpdate.

{
  "event": "GuaranteeBalanceUpdate",
  "payload": "{\"id\":\"655e18fc-a964-426e-827c-01907f9fe677\",\"links\":[{\"employer\":{\"code\":\"1\",\"document\":\"12690785000150\",\"name\":\"da Mota - ME\"},\"employee\":{\"code\":\"6672271467\",\"document\":\"71643905252\",\"name\":\"Jade Cavalcante\"},\"config\":{\"agency\":\"3a7e1beb-c64f-4936-8555-b9edb42c3328\",\"consignee\":\"3b9be0e7-3af9-4ca4-ad31-26233a58486a\"},\"products\":[{\"balance_check_id\":\"7761d327-d726-45f7-9a5d-c69c84624629\",\"authorization\":{\"details\":[{\"type_product\":\"LOAN\",\"authorized\":true}]},\"available_balance\":1909.25}],\"meta_data\":{\"nationality_country\":{\"description\":\"BRASIL\",\"code\":\"76\"},\"termination_reason_code\":\"0\",\"birth_date\":\"2002-10-16\",\"worker_category_code\":\"101\",\"gender\":{\"description\":\"Masculino\",\"code\":1},\"job_code\":{\"description\":\"AGENTE DE VIAGEM\",\"code\":\"354815\"},\"economic_activity_code\":{\"description\":\"CNAE não identificado\",\"code\":\"6391100\"},\"politically_exposed_person\":{\"description\":\"Pessoa Não Exposta Politicamente\",\"code\":0},\"base_margin_value\":\"5455\",\"amount_loans_assets_suspended\":\"0\",\"admission_date\":\"2018-11-10\",\"total_earnings\":\"5642\",\"employer_activity_start_date\":\"2021-02-11\",\"mother_name\":\"Catarina Inclusao Massa Extra\",\"has_disregarded_balance\":false},\"balance_check_date\":\"2026-04-07T19:41:34.4173361+00:00\"}],\"status\":\"SUCCESS\"}"
}

Tipos de alertas que podemos receber da Dataprev na consulta de margem

Afastamento
- Motivos de afastamento: https://www.gov.br/esocial/pt-br/documentacao-tecnica/manuais/leiautes-esocial-nt-05-2022-html/tabelas.html#18
Desligamento
- Motivos de desligamento: https://www.gov.br/esocial/pt-br/documentacao-tecnica/manuais/leiautes-esocial-nt-05-2022-html/tabelas.html#19
Aviso prévio

Simulação de Crédito

Nesta etapa, o originador deverá enviar os dados necessários para realizar a simulação da operação de crédito, com base nas condições comerciais previamente configuradas no produto. Essa simulação tem como objetivo apresentar ao tomador as opções de crédito.

Comportamento da API

A API retornará a simulação, contendo:

Valor das parcelas;
CET (Custo Efetivo Total);
Valor total a pagar;
Data de vencimento;
Informações sobre carência, amortização e taxas.

📘
Validação da Data da Primeira Parcela
O campo first_payment_date é obrigatório na simulação. O valor informado será validado com base no calendário vigente da Dataprev
Regras de validação:

Caso o campo não seja informado, será retornado HTTP 400 com a mensagem: first_payment_date is required.

Caso a data informada seja incompatível com o calendário permitido para averbação, será retornado HTTP 400 com a mensagem: Incompatibility between the first installment due date and registration date. Considering the disbursement date, the first installment due date should be from XXX onwards

Recomendamos que valide previamente a data de primeira parcela conforme o calendário aplicável antes de realizar a simulação.

Updated 10 days ago