Visão Geral

O Crédito do Trabalhador é uma modalidade de crédito consignado privado com desconto em folha de pagamento. O fluxo sem leilão segue as etapas abaixo, do consentimento do tomador até a formalização da CCB.

AGREEMENT_RENDERING → KYC_PROCESSING → PENDING_SIGNATURE → PENDING_GUARANTEE → PENDING_DISBURSEMENT → ISSUED
                                ↑
                    (pula se KYC já aprovado)
                    AGREEMENT_RENDERING → PENDING_SIGNATURE


Em caso de erro/cancelamento: qualquer status → CANCELED

Passo 1 — Termo de Consentimento

Antes de qualquer consulta de margem, o tomador deve autorizar o acesso aos seus dados junto ao Dataprev. Existem duas formas de coletar esse consentimento.

Opção A — Pela Esteira Celcoin

A plataforma envia o termo de consentimento diretamente ao tomador via WhatsApp ou e-mail.

POST /banking/originator/guarantee/authorization-permission

Authorization: Bearer {originator_access_token}
Content-Type: application/json

{
  "taxpayer_id": "48123456789",
  "product_id": "87a3767c-8d12-4164-80bf-5aa0ae796f06",
  "name": "Felipe Tavares",
  "mode": "WHATSAPP",
  "email": "felipe@email.com",
  "phone": {
    "country_code": "+55",
    "area_code": "11",
    "number": "948891456"
  }
}

Campo	Tipo	Obrigatório	Descrição
`taxpayer_id`	string	Sim	CPF do tomador
`product_id`	string (UUID)	Sim	ID do produto de crédito
`name`	string	Sim	Nome completo do tomador
`mode`	string	Sim	Canal de envio: `WHATSAPP` ou `EMAIL`
`email`	string	Sim	E-mail do tomador (obrigatório mesmo quando `mode: WHATSAPP`)
`phone.country_code`	string	Sim	Código do país (ex: `+55`)
`phone.area_code`	string	Sim	DDD
`phone.number`	string	Sim	Número do telefone

Após o tomador assinar o termo, você receberá a confirmação via webhook previamente cadastrado.

Para mais informações sobre o webhook de consentimento, clique aqui.

Opção B — Consentimento Coletado pelo Originador

O originador coleta o consentimento do lado dele e envia apenas a evidência (string) para a plataforma.

POST /banking/originator/guarantee/authorization-file-permission-async

Authorization: Bearer {originator_access_token}
Content-Type: multipart/form-data

Campo	Tipo	Obrigatório	Descrição
`taxpayer_id`	string	Sim	CPF do tomador
`product_id`	string (UUID)	Sim	ID do produto de crédito
`authorization`	string	Sim	Evidência do consentimento coletado pelo originador

Retorno: 202 Accepted

A confirmação do processamento é enviada via webhook previamente cadastrado com o seguinte payload:

{
  "event": "GuaranteeAuthorizationUpdate",
  "payload": "{\"id\":\"247aabd3-255c-4c2e-9b06-2f6c943401d5\",\"status\":\"AUTHORIZED\",\"taxpayer_id\":\"08652947392\",\"valid_date\":\"2026-05-22T19:33:56.224117\",\"authorization_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RpZ29Tb2xpY2l0YW50ZSI6IjY2OCIsImNwZiI6Ijg2NTI5NDczOTIiLCJkYXRhSW5jbHVzYW8iOjE3NzY4ODY0MzgsImV4cCI6MTc3OTUwNTE5OX0.nMPl0XVRrXamahNY0MW_2mBhISXTZbOFg09AM2ORWFk\"}"
}

Para mais informações sobre o webhook de consentimento, clique aqui.

Passo 2 — Consulta do Token de Autorização

Após receber a confirmação do consentimento via webhook, consulte o token de autorização que será necessário para as próximas etapas.

POST /banking/originator/guarantee/authorization

Authorization: Bearer {originator_access_token}
Content-Type: application/json

{
  "taxpayer_id": "20634897500",
  "product": {
    "id": "87a3767c-8d12-4164-80bf-5aa0ae796f06"
  }
}

Exemplo de resposta:

{
  "authorization_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authorization_validity_date": "2026-05-19T00:00:00Z",
  "status": "AUTHORIZED"
}

Campo

Descrição

authorization_token

Token JWT de autorização. Utilizado internamente pela plataforma nas consultas ao Dataprev

authorization_validity_date

Data de validade da autorização

status

Status da autorização:

AUTHORIZED : Consentimento autorizado.
NOT_AUTHORIZED : Consentimento não autorizado.
NOT_AVAILABLE: CPF não consta na base da Dataprev.

Passo 3 — Consulta de Margem Consignável

Consulta a margem disponível do tomador junto ao Dataprev.

GET /banking/originator/guarantee/{product_id}/get-balance?taxpayer_id={taxpayer_id}

Authorization: Bearer {originator_access_token}

Exemplo de requisição:

curl --location 'https://sandbox.platform.flowfinance.com.br/banking/originator/guarantee/87a3767c-8d12-4164-80bf-5aa0ae796f06/get-balance?taxpayer_id=20634897500' \
--header 'Authorization: Bearer {originator_access_token}'

Exemplo de resposta:

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

Campos importantes para a próxima etapa:

Campo	Descrição
`products[].balance_check_id`	ID da consulta de margem. Obrigatório na criação da CCB
`products[].available_balance`	Margem disponível do tomador por parcela em R$
`products[].authorization.details[].authorized`	Indica se o tomador está autorizado para o tipo de produto (`LOAN`)

Comportamento assíncrono: Esta rota é síncrona por padrão. Caso o rate limit do Dataprev seja atingido, a resposta será entregue de forma assíncrona no webhook previamente cadastrado. Para mais informações, clique aqui.

Erros possíveis:

400 — CPF em formato inválido


{
  "message": "400 - Document Invalid field. Check the length and only numbers are allowed.",
  "is_retryable": false
}

400 — Token não informado ou inválido

{
  "message": "400 - Token não informado ou é inválido",
  "is_retryable": false
}

>

Passo 4 — Cadastro do Tomador

Cadastre o tomador na plataforma antes de prosseguir para a simulação. As informações de nome e CPF devem ser consistentes com os dados retornados na consulta de margem.

Para detalhes completos sobre o cadastro de tomador, clique aqui.

POST /banking/originator/persons

Authorization: Bearer {originator_access_token} Content-Type: application/json

{
  "taxpayer_id": "20634897500",
  "full_name": "Srta. Alexia Cavalcante",
  "nationality": "Brasileiro",
  "pep": false,
  "birth_date": "1990-08-15",
  "sex": "MALE",
  "marital_status": "MARRIED",
  "marital_property_system": "PARTIAL_COMMUNION",
  "mothers_name": "Ana Lúcia Pereira",
  "email_address": "alexia.cavalcante@email.com",
  "occupation": "Analista de Sistemas",
  "monthly_income": 5500,
  "education_level": "HIGHER_COMPLETE",
  "phone": {
    "country_code": "55",
    "area_code": "11",
    "number": "987654321"
  },
  "id_document": {
    "number": "45.678.912-3",
    "issuer": "SSP/SP",
    "issue_date": "2015-03-20",
    "type": "RG"
  },
  "address": {
    "street_name": "Avenida Presidente Vargas",
    "street_number": 300,
    "postal_code": "01010000",
    "district": "Centro",
    "city": "São Paulo",
    "state_code": "SP",
    "country_code": "BRA",
    "extra_info": "Apartamento 42 – Bloco B"
  },
  "pix": {
    "key": "4ca519ef-0ccc-4c41-b58b-c88f1f47d8ab",
    "key_type": "ALEATORY_KEY"
  }
}

Passo 5 — Simulação da Operação

O available_balance retornado na consulta de margem representa a margem disponível por parcela. Por isso, recomendamos o uso da simulação com payment_value (valor da parcela) como parâmetro principal.

⚠️
Atenção:
A data do primeiro pagamento (1ª parcela) deve seguir o calendário operacional do Dataprev. Para mais informações,
clique aqui.
O limite máximo de parcelas permitido no Crédito do trabalhador é de 96
Para detalhes completos sobre a simulação, clique aqui.

POST /banking/originator/products/{product_id}/preview

Authorization: Bearer {originator_access_token} Content-Type: application/json

{
  "payment_value": 454,
  "interest_rate": 0.04,
  "tac_amount": 0,
  "finance_fee": 0,
  "iofType": "PERSON",
  "num_payments": 12,
  "first_payment_date": "2026-07-28",
  "disbursement_date": "2026-04-18",
  "borrower_type": "PERSON",
  "schedule_type": "MONTHLY",
  "interest_pre_type": "BASE_360",
  "insurance_amount": 100
}

Campo	Descrição
`payment_value`	Valor da parcela mensal. Deve ser ≤ `available_balance` retornado na consulta de margem
`interest_pre_type`	Base de cálculo dos juros: `BASE_360` ou `BASE_365`
`insurance_amount`	Valor do seguro por parcela, se aplicável

📘
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.

Passo 6 — Formalização da CCB

Com o balance_check_id (consulta de margem) e o simulation_id (simulação) em mãos, crie a CCB.

POST /banking/originator/applications

Authorization: Bearer {originator_access_token} Content-Type: application/json

{
  "borrower": {
    "id": "d43cb69e-aaad-4392-9781-ac441196175b"
  },
  "product": {
    "id": "87a3767c-8d12-4164-80bf-5aa0ae796f06"
  },
  "funding": {
    "id": "e746ba58-8cfe-48e0-872a-a4109baba935"
  },
  "balance_check_id": "be20ac27-a93c-41c9-9cdf-e3a92a13c49d",
  "simulation_id": "56ec99c0-04ea-4571-ba4f-3859c9b3cced",
  "signature_collect_method": "LINK",
  "signature_provider": "UNICO",
  "signature_authentication_options": {
    "mode": "DOC_SIGN"
  }
}

Campo	Descrição
`borrower.id`	`person_id` retornado no cadastro do tomador
`balance_check_id`	ID retornado na consulta de margem (Passo 3)
`simulation_id`	ID retornado na simulação (Passo 5)
`signature_collect_method`	Método de coleta de assinatura: `LINK`, `EMAIL`, `WHATSAPP`, `NONE`
`signature_provider`	Provedor de assinatura: `UNICO`, `CLICKSIGN`, `ZAPSIGN`, `CELCOIN`

Para detalhes sobre os métodos e provedores de assinatura disponíveis, [clique aqui](https://developers.celcoin.com.br/reference/modalidades-de-assinaturas

Diagrama de sequencial - Sem Leilão