Averbar consignado

Registra o empréstimo na Plataforma Crédito do Trabalhador e o desconto em folha do trabalhador.

Endpoint: POST /econsigado/loans/endorsements
Scope: econsignado.write
Equivalente na Dataprev: /emprestimos/averbar-consignado-trabalhador

curl --location 'https://secureapi.onz.finance/api/v2/econsigado/loans/endorsements' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "cpf": "12345678901",
    "employee_id": "12345",
    "employer_registration_type": 1,
    "employer_registration_number": "12345678000199",
    "contract_number": "CTR0001",
    "worker_name": "Nome do Trabalhador",
    "contract_start_date": "21082026",
    "first_discount_date": "05092026",
    "contract_end_date": "05022027",
    "installments_count": 6,
    "installment_amount": 354.54,
    "loan_amount": 2000,
    "iof_amount": 15.5,
    "released_amount": 1984.5,
    "monthly_rate": 1.79,
    "annual_rate": 23.73,
    "monthly_cet": 1.92,
    "annual_cet": 25.64,
    "has_guarantees": false
  }'

Campo	Obrigatório	Descrição
cpf	Sim	CPF do trabalhador
employee_id	Sim	Matrícula do trabalhador
employer_registration_type	Sim	Código do tipo de inscrição do empregador
employer_registration_number	Sim	Número de inscrição do empregador
contract_number	Sim	Número do contrato: 2 a 15 caracteres alfanuméricos, sem hífen, espaço ou acento
worker_name	Sim	Nome do trabalhador (até 100 caracteres)
contract_start_date	Sim	Início do contrato (ddMMyyyy)
contract_end_date	Sim	Fim do contrato (ddMMyyyy), não anterior ao início
first_discount_date	Sim	Data do primeiro desconto (ddMMyyyy)
installments_count	Sim	Quantidade de parcelas (1 a 999)
installment_amount	Sim	Valor da parcela — precisa caber na margem disponível
loan_amount	Sim	Valor do empréstimo
released_amount	Sim	Valor liberado ao trabalhador
iof_amount	Sim	Valor do IOF
monthly_rate / annual_rate	Sim	Taxa de juros mensal e anual
monthly_cet / annual_cet	Sim	CET mensal e anual
has_guarantees	Sim	Indica operação com garantia FGTS
discount_start_period	Não	Competência de início do desconto (yyyyMM)
proposal_number	Não	Número da proposta (até 20 caracteres)
operator_cnpj	Não	CNPJ do operador (14 dígitos)
fgts_guarantee_balance	Condicional	Só aceito com has_guarantees: true
severance_penalty_guarantee_amount	Condicional	Só aceito com has_guarantees: true
severance_guarantee_percentage	Condicional	Só aceito com has_guarantees: true

Com has_guarantees: false, os três campos de garantia não podem ser enviados — nem zerados. Com true, pelo menos um deles é obrigatório.

Resposta

{
  "data": {
    "contract_id": "3f86668a-3548-4c9e-8c68-9433943f455c",
    "contract_number": "CTR0001",
    "dataprev": {
      "codigoSucesso": "BD",
      "mensagem": "Inclusão efetuada com sucesso",
      "numeroContrato": "CTR0001",
      "competenciaInicioDesconto": 202610,
      "hashOperacao": 1617001777
    }
  }
}

Guarde o contract_number: ele identifica o contrato nas demais operações desta seção.

O codigoSucesso é dado de rastreio, não indicador de resultado — o enum da Dataprev reúne centenas de códigos, incluindo os de erro. Quem determina o sucesso é o HTTP 200.

A competenciaInicioDesconto é definida pela Dataprev, e não pelo requisitante. Por isso vale omitir discount_start_period no envio e usar o valor devolvido na resposta.

Erros relevantes

HTTP	Situação
403	Conta sem a liberação de empréstimo consignado
409	contract_number já usado por esta conta
422	Empréstimo já cadastrado na Dataprev para o contrato informado
422	Parcela acima da margem disponível, ou vínculo divergente