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

Este documento descreve os passos para consultar a margem consignável e realizar simulações de crédito no contexto do produto Crédito do Trabalhador.

Geração de token para consulta dos dados do tomador

Antes de consultar a margem consignável do tomador, é obrigatório obter token de autorização.


POST: /banking/originator/guarantee/authorization

Content-Type: application/json

Parâmetros

CampoDescriçãoTipo
taxpayer_idCPF do tomador (somente números)String
product.idID do produto (UUID do crédito do trabalhador)String (UUID)

{
 "authorization_validity_date": "string",
 "authorization_token": "string",
 "status": "AUTHORIZED"
}

{
 "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "status": "WAITING_SIGNATURE"
}

{
 "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "status": "NOT_AUTHORIZED"
}

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


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

CampoDescriçãoTipo
taxpayer_idCPF 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": "1500.00",
        "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

CampoDescriçãoTipo
employer.documentDocumento (CNPJ) do empregadorString
employer.nameNome do empregadorString
employee.codeCódigo do empregadoString
employee.documentDocumento (CPF) do empregadoString
employee.nameNome do empregadoString
config.agencyIdentificador da agência ou origem da consultaString
config.consigneeIdentificador da consignatáriaString
products[].balance_check_idID da verificação de saldoString
products[].authorization.details[].type_productTipo de produto autorizadoString
products[].authorization.details[].authorizedIndica se está autorizadoboolean
products[].authorization.details[].validityData de validade da autorizaçãodate
products[].authorization.portability[].authorizedIndica se a portabilidade está autorizadaboolean
products[].authorization.portability[].available_balanceSaldo disponível para portabilidadenumber
products[].authorization.portability[].type_productTipo de produto de portabilidadestring
products[].authorization.portability[].validityValidade da portabilidadedate
products[].authorization.portability[].contract_port.contract_idID do contrato de portabilidadestring
products[].authorization.portability[].contract_port.documentDocumento da instituição portadorastring
products[].authorization.portability[].contract_port.name_consigneeNome da instituição portadorastring
products[].rubric.codeCódigo da rubricastring
products[].rubric.descriptionDescrição da rubricastring
products[].agreementCódigo do convêniostring
products[].available_balanceSaldo disponível para créditonumber
meta_data.nationality_country.descriptionDescrição da nacionalidadestring
meta_data.nationality_country.codeCódigo da nacionalidadestring
meta_data.termination_reason_codeCódigo do motivo de desligamentostring
meta_data.birth_dateData de nascimentodate
meta_data.worker_category_codeCódigo da categoria do trabalhadorstring
meta_data.termination_dateData de desligamentodate
meta_data.prior_notice_dateData do aviso préviodate
meta_data.prior_notice_end_dateData fim do aviso préviodate
meta_data.gender.descriptionDescrição do gênerostring
meta_data.gender.codeCódigo do gêneronumber
meta_data.job_code.descriptionDescrição do cargostring
meta_data.job_code.codeCódigo do cargostring
meta_data.economic_activity_code.descriptionDescrição da atividade econômicastring
meta_data.economic_activity_code.codeCódigo da atividade econômicastring
meta_data.politically_exposed_person.descriptionPessoa politicamente expostastring
meta_data.politically_exposed_person.codeCódigo PEPnumber
meta_data.unauthorization_reason.descriptionDescrição da razão de não autorizaçãostring
meta_data.unauthorization_reason.codeCódigo da razão de não autorizaçãonumber
meta_data.base_margin_valueValor base da margem consignávelstring
meta_data.alerts[].absence_reason_codeCódigo do motivo de ausênciastring
meta_data.alerts[].alert_type.descriptionDescrição do tipo de alertastring
meta_data.alerts[].alert_type.codeCódigo do tipo de alertanumber
meta_data.alerts[].absence_dateData de início da ausênciadate
meta_data.alerts[].absence_end_dateData de fim da ausênciadate
meta_data.alerts[].reference_dateData de referência do alertastring
meta_data.alerts[].event_idID do eventostring
meta_data.alerts[].termination_reason_codeCódigo do motivo de desligamento no alertastring
meta_data.amount_loans_assets_suspendedValor de empréstimos suspensosstring
meta_data.admission_dateData de admissãodate
meta_data.total_earningsTotal de rendimentosstring
meta_data.legacy_loans[].financial_institution_codeCódigo da instituição financeiranumber
meta_data.legacy_loans[].contractNúmero do contratostring
meta_data.legacy_loans[].contract_start_dateData de início do contratodate
meta_data.legacy_loans[].contract_end_dateData de fim do contratodate
meta_data.legacy_loans[].installment_amountValor da parcelanumber
meta_data.legacy_loans[].loan_amountValor total do empréstimonumber
meta_data.legacy_loans[].net_amountValor líquido do empréstimonumber
meta_data.legacy_loans[].update_date_timeData/hora da última atualizaçãodatetime
meta_data.legacy_loans[].interest_taxTaxa de jurosnumber
meta_data.legacy_loans[].monthly_cetCET mensalnumber
meta_data.legacy_loans[].installment_quantityQuantidade de parcelasnumber
meta_data.legacy_loans[].paid_installments_quantityQuantidade de parcelas pagasnumber
meta_data.legacy_loans[].debtor_balance_amountSaldo devedornumber
meta_data.legacy_loans[].contract_type.descriptionDescrição do tipo de contratostring
meta_data.legacy_loans[].contract_type.codeCódigo do tipo de contratonumber
meta_data.employer_activity_start_dateData de início da atividade do empregadordate
meta_data.mother_nameNome da mãe do trabalhadorstring
balance_check_dateData da verificação de margemdate

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 no volume de requisições por segundo. Caso, no momento da requisição, a Dataprev retorne que o limite de volume 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": {
    "links": [
      {
        "employer": {
          "code": "1",
          "document": "38645962000170",
          "name": "EMPREGADOR TESTE"
        },
        "employee": {
          "code": "MATR8289",
          "document": "79017995017",
          "name": "TESTE HELLEN"
        },
        "config": {
          "agency": "3a7e1beb-c64f-4936-8555-b9edb42c3328",
          "consignee": "3b9be0e7-3af9-4ca4-ad31-26233a58486a"
        },
        "products": [
          {
            "balanceCheckId": "ef45bbfe-9f9e-403d-91c3-0e8b6d5f01aa",
            "authorization": {
              "details": [
                {
                  "typeProduct": "LOAN",
                  "authorized": true
                }
              ]
            },
            "availableBalance": 449.34
          }
        ],
        "metaData": {
          "nationalityCountry": {
            "description": "TURQUIA",
            "code": "792"
          },
          "terminationReasonCode": "0",
          "birthDate": "1990-01-01",
          "workerCategoryCode": "101",
          "gender": {
            "description": "Masculino",
            "code": 1
          },
          "jobCode": {
            "description": "AGENTE DE VIAGEM",
            "code": "354815"
          },
          "politicallyExposedPerson": {
            "description": "Pessoa Não Exposta Politicamente",
            "code": 0
          },
          "baseMarginValue": "1500",
          "amountLoansAssetsSuspended": "2",
          "admissionDate": "2020-01-01",
          "totalEarnings": "5000"
        }
      }
    ]
  }
}




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.

Documentação:
https://developers.celcoin.com.br/reference/post_banking-originator-applications


Importante: para o produto Crédito do Trabalhador foi adicionado um novo campo chamado:
balance_check_id


{
  "requested_amount": 100,
  "interest_rate": 0.01,
  "tac_amount": 0,
  "finance_fee": 0,
  "financed_iof": 1,
  "num_payments": 10,
  "first_payment_date": "2025-06-16",
  "disbursement_date": "2025-05-16",
  "balance_check_id": "{{balanceCheckId}}",
  "borrower": {
    "id": "df32c4f4-f1ea-47e1-ae45-7a6b0b2d92f3"
  },
  "product": {
    "id": "027b863d-8b5e-481d-af61-30e41772b777"
  },
  "signature_collect_method": "LINK",
  "signature_provider": "ZAPSIGN",
  "billets_info": null,
  "qrcode_info": null,
  "additional_installment_description": null,
  "additional_installment_fee": null,
  "funding": {
    "id": "9773c5fb-cbd7-41fa-b6b1-e9c76295259f"
  },
  "custom_variables": {
    "values": {}
  },
  "signature_authentication_options": {
    "mode": "FACIAL_BIOMETRICS"
  },
  "signature_collect_options": {
    "require_self_photo": false,
    "require_selfie_validation": false
  }
}