Autorização de consulta & consulta de vículo empregatício

O consentimento para a consulta ao vinculo empregatício do tomador de crédito pode ser realizado utilizando os recursos do originador ou utilizando a solução da Celcoin.

Consentimento para consulta dos dados do trabalhador (coleta clicksign)

Para utilizar a solução integrada da Celcoin, basta utilizar requisição a seguir, onde o termo será enviado e assinado digitalmente usando o serviço Clicksign.

Envio do Termo para Assinatura

POST: /banking/originator/guarantee/authorization-permission

{
    "taxpayer_id": "123456789",
    "product_id": "UIID",
    "name": "teste teste",
    "mode": "WHATSAPP",
    "email": "[[email protected]](mailto:[email protected])",
    "phone": {
        "country_code": "+55",
        "area_code": "11",
        "number": "970291614"
    }
}

Parâmetros da requisição

CampoDescriçãoTipo
taxpayer_idCPF do tomador (somente números)String
product_idID do produto (UUID da Portabilidade do Crédito do Trabalhador)String (UUID)
nameNome completo do tomadorString
emailE-mail do tomadorString
phone.country_codeCódigo do país (ex: "55" para Brasil)String
phone.area_codeDDD do telefone (ex: "11")String
phone.numberNúmero de telefoneString
modeCanal preferencial para envio da solicitação (opções: SMS, EMAIL, WHATSAPP)String
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "NOT_AUTHORIZED"
}
  • NOT_AUTHORIZED: O tomador ainda não autorizou a consulta.
  • NOT_AVAILABLE: O tomador não está na base da Dataprev.
  • AUTHORIZED: Consentimento concedido com sucesso.
  • WAITING_SIGNATURE: A solicitação foi enviada e aguarda assinatura do tomador

{
  "message": "Erro ao processar a solicitação.",
  "detail": {
    "email": ["O e-mail informado possui um formato inválido."],
    "taxpayer_id": ["O CPF informado é inválido."],
    "mode": ["O canal de envio informado não é suportado."]
  }
}

● Retorno 400: Erro de validação / dados inválidos
● Retorno 500: Erro interno no servidor

Recuperação do link de assinatura

Caso o originador precise recuperar o link de assinatura do termo de consentimento enviado ao tomador, disponibilizamos o seguinte webhook:

Evento: GuaranteeAuthorizationRequest (Este webhook é cadastrado previamente pelo nosso time implementação, exclusivamente dedicado ao recebimento desse evento)

{
  "event": "GuaranteeAuthorizationRequest",
  "payload": "{\"sign_link\":\"https://sandbox.clicksign.com/notarial/widget/signatures/a825e8fe-635f-44be-9d0b-03c0e36cbd95/redirect\",\"authorization_id\":\"99e55a1f-5aab-4373-a2a1-dcd39d340a49\"}"
}

Parâmetros

CampoDescriçãoTipo
sign_linkLink para o tomador assinar o termostring
authorization_idIdentificador único da autorização geradastring

Confirmação da assinatura

Após o tomador assinar o termo de consentimento, enviamos um webhook de notificação ao originador com a confirmação da assinatura:

Evento: GuaranteeAuthorizationUpdate

{
  "event": "GuaranteeAuthorizationUpdate",
  "payload": "{\"id\":\"645dedf8-9cd6-4aa3-8db1-a804999bff2d\",\"status\":\"AUTHORIZED\",\"taxpayer_id\":\"36455532821\",\"valid_date\":\"2025-08-16T18:11:53.365638\",\"sign_mode\":\"EMAIL\",\"originator_id\":\"d8d5e139-9415-4861-a8c5-7b58b9dfca68\"}"
}

Parâmetros

CampoDescriçãoTipo
idIdentificador da autorização do termo.string
statusStatus da autorização (ex: AUTHORIZED)string
taxpayer_idCPF do tomador (sem formatação).string
valid_dateData e hora em que a assinatura foi concluída (formato ISO 8601).string
sign_modeCanal utilizado para assinatura (EMAIL, SMS)string
originator_idIdentificador da instituição originadorastring

Download do consentimento assinado pelo tomador via Clicksign

Caso o tomador tenha assinado o termo de consentimento por meio da Clicksign, é possível realizar o download do arquivo PDF assinado das seguintes formas:

  • Portal de Crédito

    • Acesse a tela de Detalhes da Operação.

    • Clique para baixar o arquivo assinado disponível.

  • API

    • Utilize o endpoint abaixo para realizar a requisição via API.

GET:/originator/guarantee/acceptterm/download

Parâmetros

CampoDescriçãoTipo
taxpayerIdCPF do tomador de créditostring

Headers

HeaderValor
AuthorizationBearer
Acceptaccept: /

Comportamento

  • Retorna o PDF do último termo de aceite assinado para o taxpayerId informado.

  • Se não houver registro assinado (authorizationEvidence), retorna HTTP 404.

  • Em caso de erro interno, retorna HTTP 500.

-X GET "{{api_host}}/banking/originator/guarantee/acceptterm/download?taxpayerId=55428589027" \
  -H "Authorization: Bearer eyJ..." \
  -H "Accept: */*"

Consentimento para consulta do vínculo empregatício (coleta pelo originador)

O originador pode obter o termo de consentimento diretamente do tomador (ex: assinatura física, outra plataforma) e deve enviá-lo para registro.

Envio do Termo Assinado

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

Content-Type: multipart/form-data

Parâmetros (Não é necessário encaminhar os dois parâmetros___authorization_file_ e authorization . um inválida o outro)

CampoDescriçãoTipo
taxpayer_idCPF do tomador (somente números)String
product_idID do produto (UUID da Portabilidade do Crédito do Trabalhador)String (UUID)
authorization_fileArquivo PDF do termo assinadoFile (binary)
authorizationEvidência da assinatura (hash, texto, etc.)String

Caso seja utilizado a coleta pelo fluxo do cliente, é obrigatório o envio da evidência do consentimento.

"status": "AUTHORIZED"
}

● Retorno 400: Erro de validação / dados inválidos
● Retorno 500: Erro interno no servidor

Consulta de vínculo empregatício

Após o consentimento coletado com o tomador de crédito o tomador deverá realizar a consulta ao vinculo empregatício do mesmo para validar a elegibilidade do vinculo empregatício e a que a margem do tomador de crédito não esteja comprometida.

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: /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": "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

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_suspendedQuantidade de empréstimos ativos/suspensosnumber
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"
    ]
  }
}