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
Campo | Descrição | Tipo |
---|---|---|
taxpayer_id | CPF do tomador (somente números) | String |
product.id | ID 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
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": "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
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 | Valor de empréstimos suspensos | string |
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 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
}
}
Updated 1 day ago