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"
    ]
  }
}

Validação da CET (Custo Efetivo Total)

Em conformidade com as regras operacionais vigentes do ecossistema Crédito do Trabalhador, será aplicada uma validação obrigatória da variação do CET em relação à taxa de juros nominal da operação.

O objetivo dessa validação é garantir que o custo efetivo mensal da operação permaneça dentro do limite permitido durante o processo de simulação e contratação.

Para essa validação, comparamos os campos:

monthly_effective_interest_rate → representa o CET mensal da operação
interest_rate → representa a taxa de juros nominal mensal da operação

Regra aplicada

O valor de monthly_effective_interest_rate não poderá exceder em mais de 1 ponto percentual o valor de interest_rate.

monthly_effective_interest_rate \leq interest_rate + 1%

Etapas onde a validação será aplicada

Essa validação será executada nas seguintes etapas da API:

Requisições de simulação
Requisições de criação de CCB

Exemplo

interest_rate	monthly_effective_interest_rate	Resultado
3.00%	3.80%	Operação válida
3.00%	4.20%	Operação rejeitada

Retorno de erro

Caso a operação ultrapasse o limite permitido, a requisição será rejeitada e a API retornará o seguinte erro:

{
  "message": "O CET mensal calculado excede o limite legal de 1 p.p. sobre a taxa de juros da operação."
}

Importante

Essa validação complementa as regras já existentes relacionadas ao cálculo da taxa de juros e do CET, passando a ser um critério obrigatório para aprovação das operações.

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\"}"
}

Atenção: o campo payload é entregue como uma string JSON serializada. É necessário fazer JSON.parse(event.payload) antes de acessar os campos internos.

Campos do JSON

Campo	Tipo	Descrição	Exemplo
`event`	`string`	Identificador do tipo de evento disparado	`GuaranteeBalanceUpdate`
`payload`	`string` (JSON serializado)	JSON serializado como string contendo os dados do evento. Deve ser parseado separadamente.	`"{...}"`

payload (após parse) — objeto raiz

Campo	Tipo	Descrição	Exemplo
`id`	`string` (UUID)	Identificador único da requisição de consulta de margem	`655e18fc-a964-426e-827c-01907f9fe677`
`status`	`string`	Status do processamento da consulta. Valores possíveis: `SUCCESS`, `ERROR`	`SUCCESS`
`links`	`array`	Lista de vínculos empregatícios consultados, cada um com seus dados de margem e metadados	—

links[] — cada vínculo

employer — dados do empregador

Campo	Tipo	Descrição	Exemplo
`employer.code`	`string`	Código interno do empregador	`1`
`employer.document`	`string`	CNPJ do empregador (somente dígitos)	`12690785000150`
`employer.name`	`string`	Razão social do empregador	`da Mota - ME`

employee — dados do colaborador

Campo	Tipo	Descrição	Exemplo
`employee.code`	`string`	Matrícula / código do funcionário	`6672271467`
`employee.document`	`string`	CPF do colaborador (somente dígitos)	`71643905252`
`employee.name`	`string`	Nome completo do colaborador	`Jade Cavalcante`

config — configurações da conta

Campo	Tipo	Descrição	Exemplo
`config.agency`	`string` (UUID)	Identificador da agência configurada	`3a7e1beb-c64f-4936-8555-b9edb42c3328`
`config.consignee`	`string` (UUID)	Identificador da consignatária	`3b9be0e7-3af9-4ca4-ad31-26233a58486a`

Campos gerais do vínculo

Campo	Tipo	Descrição	Exemplo
`balance_check_date`	`string` (ISO 8601)	Data e hora em que a consulta de margem foi realizada	`2026-04-07T19:41:34.417+00:00`
`products`	`array`	Produtos elegíveis para o vínculo, com autorização e saldo disponível	—

links[].products[] — cada produto

Campo	Tipo	Descrição	Exemplo
`balance_check_id`	`string` (UUID)	Identificador único desta consulta de saldo	`7761d327-d726-45f7-9a5d-c69c84624629`
`available_balance`	`number`	Saldo / margem disponível para o produto, em reais	`1909.25`
`authorization`	`object`	Resultado da autorização para os produtos do vínculo	—
`authorization.details`	`array`	Lista de autorizações por tipo de produto	—
`authorization.details[].type_product`	`string`	Tipo de produto avaliado. Ex.: `LOAN`, `CREDIT_CARD`	`LOAN`
`authorization.details[].authorized`	`boolean`	Indica se o colaborador está autorizado para este tipo de produto	`true`

links[].meta_data — dados cadastrais do colaborador

Campo	Tipo	Descrição	Exemplo
`nationality_country.description`	`string`	Nome do país de nascimento	`BRASIL`
`nationality_country.code`	`string`	Código BACEN do país de nascimento	`76`
`termination_reason_code`	`string`	Código do motivo de rescisão. `"0"` = ativo / sem rescisão	`0`
`birth_date`	`string` (YYYY-MM-DD)	Data de nascimento do colaborador	`2002-10-16`
`admission_date`	`string` (YYYY-MM-DD)	Data de admissão na empresa	`2018-11-10`
`worker_category_code`	`string`	Código da categoria do trabalhador (tabela eSocial)	`101`
`gender.description`	`string`	Descrição do gênero	`Masculino`
`gender.code`	`number`	Código do gênero: `1` = Masculino, `2` = Feminino	`1`
`job_code.description`	`string`	Descrição da ocupação (CBO)	`AGENTE DE VIAGEM`
`job_code.code`	`string`	Código CBO da ocupação	`354815`
`economic_activity_code.description`	`string`	Descrição da atividade econômica (CNAE)	`CNAE não identificado`
`economic_activity_code.code`	`string`	Código CNAE do empregador	`6391100`
`politically_exposed_person.description`	`string`	Descrição da condição de PEP	`Pessoa Não Exposta Politicamente`
`politically_exposed_person.code`	`number`	Código PEP: `0` = não exposta	`0`
`base_margin_value`	`string`	Valor da margem base do colaborador, em reais	`5455`
`total_earnings`	`string`	Total de rendimentos brutos do colaborador, em reais	`5642`
`amount_loans_assets_suspended`	`string`	Valor total de empréstimos com parcelas suspensas	`0`
`employer_activity_start_date`	`string` (YYYY-MM-DD)	Data de início das atividades do empregador	`2021-02-11`
`mother_name`	`string`	Nome da mãe do colaborador	`Catarina Inclusao Massa Extra`
`has_disregarded_balance`	`boolean`	Indica se há saldo desconsiderado no cálculo de margem disponível	`false`

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 about 1 hour ago