Skip to main content

Empréstimos

Módulo do empréstimo, a entidade central da plataforma LaaS. Nesta jornada ele é usado para emitir o contrato de consignado privado a partir dos parâmetros aprovados na simulação, formalizá-lo (geração da CCB e assinatura eletrônica pelo tomador) e conduzi-lo pelas transições de averbação e desembolso.

Rota base v5/loans.

Toda criação recalcula a simulação

A API converte o payload em parâmetros de simulação e executa o cálculo completo antes de persistir. Os valores do payload são entradas para o cálculo, não valores gravados literalmente: principal, IOF, CET, parcelas, datas e cenários de desembolso vêm do resultado. Na criação, o contrato nasce com status = draft (código 0) e stage = proposal.

Autenticação​

Todos os endpoints exigem API Key. A emissão exige permissão de criação de empréstimos; formalização, assinatura, desembolso e averbação exigem permissão de edição; as rotas GET exigem permissão de consulta. O nível de acesso do usuário (unidade, parceiro, agência, agente, usuário) limita quais contratos ele enxerga. Ver Autenticação.

Rotas implementadas​

RotaVerboResumo
/v5/loansPOSTEmite o contrato (recalcula a simulação a partir do payload).
/v5/loans/{id}GETObtém o contrato.
/v5/loans/{loanId}/signature-requestsPOSTSolicita a formalização: enfileira a geração da CCB e do link de assinatura eletrônica. Processado em segundo plano.
/v5/loans/{id}/document-requests/currentGETAcompanha a última geração de documento solicitada para o contrato.
/v5/loans/{loanId}/signature-requests/currentGETObtém a assinatura eletrônica mais recente do contrato, com o link do tomador e a jornada de formalização.
/v5/loans/{loanId}/signature-requests/current/syncPOSTAtualiza a assinatura mais recente consultando o provedor de assinatura.
/v5/loans/{loanId}/signature-requests/current/journeysPOSTGera uma nova jornada de formalização para a assinatura em andamento. Ver Jornadas.
/v5/loans/{id}/signaturesPUTRegistra a assinatura manualmente (status = signed).
/v5/loans/{id}/endorsementsPUTRegistra a averbação (status = endorsement). No consignado privado, a averbação na Dataprev é feita em segundo plano (status = endorsement_processing até a confirmação).
/v5/loan-private-payrolls/{loanId}/contract-informationGETMostra os documentos e dados da assinatura que serão enviados à Dataprev.
/v5/loan-private-payrolls/{loanId}/contract-informationPOSTEnvia à Dataprev a CCB assinada e as evidências da formalização, tiradas da assinatura concluída, depois da averbação. Processado em segundo plano.
/v5/loans/{id}/disbursementsPUTRegistra o desembolso, integra com o banco liquidante e gera as cobranças (status = integrated).
/v5/loans/{loanId}/disbursementsGETLista os comandos de desembolso enviados ao pagador para o contrato.

O recurso expõe ainda rotas de ajuste e reapresentação do desembolso e as rotas usadas pelo pagador para validar e confirmar o comando de desembolso, que não fazem parte desta jornada e não estão documentadas aqui. As consultas externas vinculadas ao contrato (bureau, autorregulação) ficam em Consultas.

Convenções gerais reutilizadas nesta página: Tratamento de erros, Objeto de domínio, Campo de status, Referências organizacionais. Valores fixos em Domínios › Empréstimos.

Ciclo de vida nesta jornada​

POST /v5/loans ──────────────► status = draft, stage = proposal
   │
   ├─ 1. POST /{loanId}/signature-requests ─► gera CCB + link de assinatura em segundo plano
   │        └─► status = awaiting_formalization  (evento loan.signature_requested)
   │              └─ tomador assina ──► status = signed (grava signatureDate, evento loan.signed)
   │     (alternativa: PUT /{id}/signatures registra a assinatura manualmente)
   ├─ 2. PUT /{id}/endorsements ─► status = endorsement_processing (consignado privado, Dataprev em segundo plano)
   │                                 └─► status = endorsement (grava endorsementDate)
   └─ 3. PUT /{id}/disbursements ► status = integrated    (banco liquidante + cobranças)
                                      └─ bloqueia qualquer nova transição (1010002)
O desembolso vem por último

As três rotas de transição recusam contratos já integrated (1010002). Por isso a sequência é formalizar (assinar) → averbar → desembolsar, a mesma ordem das requisições da collection (Assinar, Averbar e Desembolsar Operação). Assinatura manual e averbação não exigem status anterior específico, então podem ser repetidas para corrigir a data enquanto o contrato não for desembolsado.

Contrato averbado e não desembolsado

No consignado privado, a empresa pode configurar um prazo para a desaverbação automática: um contrato averbado que não foi desembolsado dentro desse prazo tem a averbação excluída na Dataprev e é cancelado. Ver Desaverbação automática.

Campos da entidade​

O empréstimo contém todos os campos financeiros documentados em Simulações › Campos da entidade (valores, taxas, IOF, CET, regras do produto, installments[], disbursementOptions[]) e acrescenta os campos abaixo. A coluna "Entrada" indica o campo equivalente no payload de POST /v5/loans.

Identificação e ciclo de vida​

CampoEntradaTipoDescrição
id—string (uuid)Identificador do contrato. É o {id} das rotas de transição.
code—integerCódigo sequencial por empresa.
key—string (uuid)Chave pública.
contractNumbercontractNumberstringNúmero do contrato. Se omitido, gerado com o prefixo do produto + code (ex.: SM00000001).
stagestageobject (code/key/name)proposal até o desembolso; passa a contract quando o desembolso altera a data e recalcula as parcelas. Ver LoanStage.
step—object (code/key/name)Etapa operacional (formalization). Passa a awaiting_sync (1830) se o envio ao banco falhar no desembolso. Ver LoanStep.
status—object (Status)Nasce draft. Ver LoanStatus.
statusReason—object (code/key/name)Motivo do status, quando aplicável (cancelamento).
issueDate—string (date)Data de emissão (dia da criação).
signatureDate—string (date-time) | nullPreenchido por PUT /{id}/signatures.
disbursementDatedisbursementDatestring (date)Prevista na criação; efetiva após PUT /{id}/disbursements.
endorsementDateendorsementDatestring (date) | nullPreenchido por PUT /{id}/endorsements.
payoffDate—string (date) | nullData de liquidação total (fluxos de pagamento).

Tomador e partes​

CampoEntradaTipoDescrição
parties[]borrower (objeto único) e/ou parties[]arrayPartes envolvidas. borrower é adicionado com type = borrower. Cada item: id, nid, name, tradeName, birthDate, type, personType, documentType, documentNumber, registrationType, registrationNumber, motherName, fatherName, profession, nationality, maritalStatus, gender, income, address, phone, email, refCode, note.
parties[].addressborrower.addressobjectid, prefix, street, number, complement, district, city, state, country, postalCode, note, type, status. Informe o CEP em postalCode e o bairro em district.
parties[].phoneborrower.phoneobjectid, countryCode, areaCode, number, fullNumber (montado), extension, note, type, status.

Pagamento e desembolso​

CampoEntradaTipoDescrição
paymentMethodpaymentMethodobject (code/key/name)Método de pagamento das parcelas. Padrão do produto: direct_loan. Ver LoanPaymentMethod.
paymentBankAccount, paymentPixidemobject | nullConta/Pix de pagamento, quando aplicável.
disbursementMethoddisbursementMethodobject (code/key/name)Padrão do produto: ted. Ver LoanDisbursementMethod.
disbursementBankAccountdisbursementBankAccountobject | nulltype, bank, branch, number, digit. Informe a conta separada em number e digit, e o tipo em type com a chave checking_account ou savings_account. Ver BankAccountType.
disbursementPixdisbursementPixobject | nullChave Pix de desembolso, para disbursementMethod = pix.

Acompanhamento financeiro (zerados na emissão)​

CampoTipoDescrição
totalReceivedAmount, overdueAmount, lateDays, lastPaymentDatedecimal / decimal / integer / date | nullEvoluem com os pagamentos.
accruedInterestAmount, unearnedInterestAmountdecimalJuros apropriados e a apropriar.
latePenaltyAmount, lateInterestAmount, latePenaltyRate, lateInterestRatedecimalMulta e mora acumuladas em atraso e as taxas aplicadas.
presentValueAmount, writtenOffAmount, chargeDiscountAmount, insuranceAmount, simulationAmountdecimalValores auxiliares de gestão da carteira.
isRenegotiated, isDefault, defaultDate, recoveryAmountboolean / boolean / date | null / decimalRenegociação e inadimplência.
riskRating, riskRatingDate, eclStage, probabilityOfDefault, lossGivenDefault, exposureAtDefaultAmount, expectedCreditLossAmount—Risco e perda esperada (processos de crédito).
isAssigned, assignmentDate, assigneeboolean / date | null / ReferênciaCessão do contrato.
receivableRegistryId, receivableRegistryStatusstring | null / CodeKeyNameRegistro em registradora de recebíveis.
collateralType, collateralAmountCodeKeyName / decimalGarantia vinculada (ex.: FGTS).
employerDocumentType, employerDocumentNumber, correspondentDocumentType, correspondentDocumentNumber—Empregador e correspondente, quando informados (o payload aceita employerDocumentType/employerDocumentNumber).
files[], currency, batch, refCode, salesChannel, lastCalculatedAt, note—Anexos, moeda (BRL), lote, referência externa, canal de vendas, último recálculo e observações.

POST /v5/loans​

Emite o contrato. O payload aceita os mesmos parâmetros financeiros da simulação (e os mesmos dois modos: fixar installmentAmount ou disbursementAmount), mais o tomador (borrower) e a conta de desembolso.

Autenticação: API Key. Exige permissão de criação de empréstimos.

Payload de entrada​

Campos enviados pelas quatro requisições de emissão da collection (por Valor de Parcela, por Valor de Parcela com garantia, por Valor do Desembolso e por Valor do Principal). Elas diferem só no valor de referência (installmentAmount, disbursementAmount ou principalAmount, envie apenas um) e no bloco privatePayroll, que na emissão com garantia traz também fgtsBalanceId, hasCollateral, fgtsWithdrawalType e collateralSeveranceRate. As datas vêm do script de pré-requisição: desembolso hoje e primeiro vencimento um mês depois.

Visualizar parâmetros
CampoTipoObrigatórioDescrição
borrower.namestringSimNome completo.
borrower.birthDatestring (date)SimData de nascimento.
borrower.personTypestringSimnatural_person. O tomador do consignado privado é sempre gravado como pessoa física.
borrower.documentTypestringSimcpf.
borrower.documentNumberstringSimCPF, somente dígitos. Deve ser o mesmo do termo e do vínculo consultados.
borrower.identityDocumentNumberstring | nullNãoNúmero do documento de identidade (RG).
borrower.identityIssuingAgencystring | nullNãoÓrgão emissor do documento de identidade.
borrower.identityIssuingStatestring | nullNãoUF de emissão do documento de identidade.
borrower.motherNamestring | nullNãoNome da mãe.
borrower.professionstring | nullNãoProfissão.
borrower.nationalitystring | nullNãoNacionalidade.
borrower.maritalStatusstring | nullNãokey de MaritalStatus.
borrower.genderstring | nullNãokey de Gender.
borrower.incomedecimal | nullNãoRenda declarada.
borrower.address.postalCodestring | nullNãoCEP.
borrower.address.streetstring | nullNãoLogradouro.
borrower.address.numberstring | nullNãoNúmero.
borrower.address.complementstring | nullNãoComplemento.
borrower.address.districtstring | nullNãoBairro.
borrower.address.citystring | nullNãoCidade.
borrower.address.statestring | nullNãoUF.
borrower.address.countrystring | nullNãoPaís.
borrower.phone.countryCodestring | nullNãoCódigo do país (55).
borrower.phone.areaCodestring | nullNãoDDD.
borrower.phone.numberstring | nullNãoNúmero do telefone.
borrower.phone.typestring | nullNãoTipo do telefone (mobile).
borrower.emailstring | nullNãoE-mail do tomador. Obrigatório para gerar o link de assinatura eletrônica (1010026).
productstringSimkey do produto de empréstimo. Use private_payroll. Alternativa: productId (uuid). Desconhecido → 1010003.
disbursementDatestring (date)SimData prevista do desembolso.
firstDueDatestring (date)SimPrimeiro vencimento desejado. Ajustado pelas regras do produto (ver Simulações).
numberOfInstallmentsintegerSimQuantidade de parcelas. Inválido → 1010004.
installmentAmountdecimalUm dos trêsValor fixo da parcela (modo term_rate_installment).
disbursementAmountdecimalUm dos trêsValor líquido em conta (modo term_rate_disbursement).
principalAmountdecimalUm dos trêsValor contratado (modo term_rate_principal).
monthlyRatedecimalSimTaxa mensal em fração (0.018 = 1,8%). Inválida → 1010005.
privatePayroll.employeeDataIdstring (uuid)Simid da consulta de dados do trabalhador. Copia para o contrato a matrícula, o empregador, a elegibilidade e a margem. Não encontrada → 9504102. Ver bloco privatePayroll.
privatePayroll.fgtsBalanceIdstring (uuid) | nullCom garantiaid da consulta de saldo FGTS, base da garantia. Não encontrada → 9504104.
privatePayroll.hasCollateralboolean | nullNãotrue declara a garantia de FGTS. Os valores dados em garantia são calculados pela API; sem cobertura de 100% do valor contratado → 9504106.
privatePayroll.fgtsWithdrawalTypestring | nullNãoseverance_withdrawal (saque-rescisão) ou birthday_withdrawal (saque-aniversário, sem o saldo do FGTS na garantia). Ver LoanPrivatePayrollFgtsWithdrawalType.
privatePayroll.collateralSeveranceRatedecimal | nullNãoPercentual das verbas rescisórias dado em garantia, em fração. null usa o percentual disponível da consulta de dados do trabalhador. Acima do disponível → 9504105.
disbursementBankAccount.bankstringSimCódigo do banco (001).
disbursementBankAccount.branchstringSimAgência, sem dígito.
disbursementBankAccount.numberstringSimNúmero da conta, sem dígito.
disbursementBankAccount.digitstringSimDígito da conta.
disbursementBankAccount.typestringSimchecking_account (conta corrente) ou savings_account (poupança). Ver BankAccountType.
refCodestring | nullNãoReferência externa do contrato no seu sistema.
notestring | nullNãoObservação.
Outros campos aceitos (não usados na collection)
CampoTipoObrigatórioDescrição
disbursementMethodstring | nullNãoted (padrão do produto), pix, tef, card.
disbursementPixobject | nullNãoChave Pix, quando disbursementMethod = pix. No consignado privado, chave CNPJ é recusada (9504107) e chave CPF precisa ser o CPF do tomador (9504108).
descriptionstring | nullNãoDescrição do contrato.
resultOptions.disableInstallmentsboolean | nullNãotrue omite installments[] da resposta.
Demais campos—NãocontractNumber, type, operationType, payrollEntity, parties[], graceType, graceDays, iofIsFinanced, interestType, interestBase, amortizationSystem, paymentFrequencyType, fees[], originContracts[], numberOfDisbursementOptions, paymentMethod, paymentBankAccount, paymentPix, employerDocumentType, employerDocumentNumber, files[], currency, batch, salesChannel, unitId, partnerId, branchId, agentId, userId. Em geral desnecessários no consignado privado, pois o produto define os padrões.
borrower.fatherNamestring | nullNãoNome do pai.
borrower.refCode, borrower.notestring | nullNãoReferência externa e observação do tomador.

Bloco privatePayroll​

Liga o contrato às consultas feitas na Dataprev e declara se a operação tem garantia de FGTS. É este bloco — e não collaterals[] — que alimenta a averbação; sem ele o contrato não passa da validação 9503102.

Visualizar parâmetros
CampoTipoObrigatórioDescrição
employeeDataIdstring (uuid)Simid da consulta de dados do trabalhador. Copia para o contrato o CPF, a matrícula, a inscrição do empregador, a elegibilidade, a margem, o motivo de desligamento e o percentual de verba rescisória disponível. Não encontrada → 9504102.
fgtsBalanceIdstring (uuid) | nullCom garantiaid da consulta de saldo FGTS. Copia o saldo disponível e a multa rescisória apurados, que são a base da garantia. Não encontrada → 9504104.
hasCollateralboolean | nullNãotrue declara que a operação tem garantia de FGTS. Sem ele (ou com false), o contrato é averbado sem garantia e os demais campos de garantia são ignorados.
fgtsWithdrawalTypestring | nullNãoModalidade de saque do FGTS do trabalhador: severance_withdrawal (saque-rescisão) ou birthday_withdrawal (saque-aniversário). No saque-aniversário o saldo do FGTS não entra na garantia, só a multa rescisória. Valor desconhecido é ignorado. Ver LoanPrivatePayrollFgtsWithdrawalType.
collateralSeveranceRatedecimal | nullNãoPercentual das verbas rescisórias dado em garantia, em fração (0.35 = 35%). Sem ele, a API usa o percentual disponível apurado na consulta de dados do trabalhador. Acima do disponível (ou de 35%) → 9504105.
A API calcula a garantia

Os valores de saldo do FGTS e de multa rescisória dados em garantia não são enviados: com hasCollateral = true, a API os apura a partir da consulta de saldo FGTS (fgtsBalanceId), respeitando a modalidade de saque, o motivo de desligamento do vínculo e os limites legais de cada garantia, e os distribui até cobrir o valor contratado (principalAmount). Se as garantias disponíveis não cobrirem 100% do valor contratado, a emissão é recusada com 9504106. Ver Garantia de FGTS na averbação.

O bloco é gravado como um registro próprio do contrato (o registro de consignado privado), e é lá que ficam o resultado da averbação, do envio do contrato e da desaverbação. Ele não aparece no corpo de resposta de /v5/loans; nesta API, ele é devolvido por POST /v5/loan-private-payrolls/{loanId}/contract-information e exibido na aba Consignado Privado do portal.

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "borrower": {
    "name": "{{workerName}}",
    "birthDate": "1985-08-19",
    "personType": "natural_person",
    "documentType": "cpf",
    "documentNumber": "{{workerCpf}}",
    "identityDocumentNumber": "12342323",
    "identityIssuingAgency": "SSP",
    "identityIssuingState": "SP",
    "motherName": "Maria Inclusao Massa Extra",
    "profession": "Programador",
    "nationality": "Brasileiro",
    "maritalStatus": "married",
    "gender": "male",
    "income": 15000.00,
    "address": {
      "postalCode": "01310-100",
      "street": "Avenida Paulista",
      "number": "1578",
      "complement": "Apto 101",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "Brasil"
    },
    "phone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "987654321",
      "type": "mobile"
    },
    "email": "trabalhador@exemplo.com"
  },
  "product": "private_payroll",
  "disbursementDate": "{{disbursementDate}}",
  "firstDueDate": "{{firstDueDate}}",
  "numberOfInstallments": 96,
  "installmentAmount": 100,
  "monthlyRate": 0.018,
  "privatePayroll": {
    "employeeDataId": "{{employeeDataId}}"
  },
  "disbursementBankAccount": {
    "bank": "001",
    "branch": "1234",
    "number": "123456",
    "digit": "6",
    "type": "checking_account"
  },
  "refCode": "",
  "note": ""
}

GET /v5/loans/{id}​

Obtém o contrato, no mesmo formato da resposta de POST /v5/loans. É a forma de acompanhar o contrato depois das etapas processadas em segundo plano (formalização, averbação e desembolso), como alternativa aos eventos de webhook.

Autenticação: API Key. Exige permissão de consulta de empréstimos.

curl --request GET \
  --url 'https://{base-url}/v5/loans/01a0c239-c330-7361-ad20-fbeb57e97322' \
  --header 'X-Api-Key: {api_key}'

Formalização: CCB e assinatura eletrônica​

A formalização gera a Cédula de Crédito Bancário (CCB) do contrato e um envelope de assinatura eletrônica em que o tomador é o signatário. As duas etapas são processadas em segundo plano: a chamada só registra o pedido e responde na hora.

POST /v5/loans/{loanId}/signature-requests ──► pedido de documento (status = pending)
   │
   │  em segundo plano
   ├─ cancela assinaturas ainda abertas do contrato ("Substituída por um novo link de assinatura")
   ├─ gera a CCB em PDF e anexa ao contrato (files[]) ──────────► evento loan.document_created
   ├─ cria o envelope de assinatura com o tomador e obtém o link de assinatura
   ├─ gera a jornada de formalização do tomador
   └─ contrato passa a status = awaiting_formalization ──────────► evento loan.signature_requested
          │
          └─ tomador conclui a assinatura ──► status = signed, signatureDate = conclusão ──► evento loan.signed

Para acompanhar:

  1. Consulte GET /v5/loans/{id}/document-requests/current até o pedido sair de pending/processing/retrying — ou assine os eventos loan.signature_requested e loan.document_failed.
  2. Com o pedido em succeeded, obtenha o link do tomador e a jornada em GET /v5/loans/{loanId}/signature-requests/current.
  3. Quando o tomador assina, o contrato passa sozinho a signed e o evento loan.signed é publicado. Não é preciso chamar PUT /{id}/signatures.

A jornada de formalização é a página que o tomador abre para revisar e assinar a CCB; ela é criada junto com a assinatura e devolvida em journeyUrl. Os detalhes das jornadas estão em Jornadas.

Gerar só a CCB

A geração da CCB sem assinatura eletrônica é uma operação do portal e segue o mesmo modelo: cria um pedido de documento do tipo ccb, acompanhado pela mesma rota document-requests/current.

Pedido de documento​

Objeto devolvido por POST /v5/loans/{loanId}/signature-requests e por GET /v5/loans/{id}/document-requests/current.

CampoTipoDescrição
idstring (uuid)Identificador do pedido.
nidintegerIdentificador numérico do pedido.
typeobject (code/key/name)signature_request (CCB e link de assinatura) ou ccb (só a CCB). Ver LoanDocumentRequestType.
loanIdstring (uuid)Contrato do pedido.
statusobject (Status)pending, processing, succeeded, retrying ou failed. Em failed, status.note traz o motivo. Ver LoanDocumentRequestStatus.
attemptCount / maxAttemptsintegerTentativas feitas e limite de tentativas.
nextAttemptAtstring (date-time) | nullPróxima tentativa, quando o pedido está aguardando processamento ou reagendado.
lastErrorstring | nullÚltimo erro registrado. Quando há mais de um motivo, vêm separados por |.
completedAtstring (date-time) | nullConclusão do pedido, com sucesso ou falha.
fileIdstring (uuid) | nullArquivo da CCB gerada.
signatureIdstring (uuid) | nullEnvelope de assinatura criado (só em signature_request).
createdAtstring (date-time)Registro do pedido.
openbooleantrue enquanto o pedido ainda não terminou.

Falhas inesperadas durante o processamento são repetidas automaticamente, com espera crescente, até maxAttempts; nesse intervalo o pedido fica em retrying. Recusas de regra (por exemplo, configuração ausente ou provedor de assinatura que não devolve o link) encerram o pedido em failed na hora. Ao chegar a failed, o evento loan.document_failed é publicado.

POST /v5/loans/{loanId}/signature-requests​

Solicita a formalização do contrato: enfileira a geração da CCB e do link de assinatura eletrônica e responde 201 com o pedido de documento, sem aguardar o processamento.

Autenticação: API Key. Exige permissão de edição de empréstimos.

Comportamento​

  1. Valida que o contrato pode ser assinado: ainda sem signatureDate, e não integrated nem canceled (1010027).
  2. Valida o tomador: precisa existir com CPF (1010025) e ter e-mail (1010026), usado pelo provedor de assinatura.
  3. Se já houver um pedido do mesmo tipo em aberto para o contrato, devolve esse pedido em vez de criar outro. Caso contrário, registra um novo pedido com status = pending.
  4. Em segundo plano, executa as etapas do diagrama acima. Uma nova solicitação substitui a assinatura anterior que ainda estiver aberta: o link antigo deixa de valer.

Erros do processamento em segundo plano — por exemplo, o endereço da página da jornada não configurado para a empresa (1174005) ou o provedor de assinatura não devolver o link (1010028) — não voltam nesta resposta: o texto do erro fica em lastError e em status.note do pedido.

Exemplo de Requisição e Resposta​

Não há corpo.

curl --request POST \
  --url 'https://{base-url}/v5/loans/01a0c239-c330-7361-ad20-fbeb57e97322/signature-requests' \
  --header 'X-Api-Key: {api_key}'

GET /v5/loans/{id}/document-requests/current​

Devolve o último pedido de documento do contrato, de qualquer tipo, no formato de Pedido de documento. Use para acompanhar a formalização por consulta periódica, com intervalo de alguns segundos, até open = false.

Autenticação: API Key. Exige permissão de consulta de empréstimos.

curl --request GET \
  --url 'https://{base-url}/v5/loans/01a0c239-c330-7361-ad20-fbeb57e97322/document-requests/current' \
  --header 'X-Api-Key: {api_key}'

GET /v5/loans/{loanId}/signature-requests/current​

Devolve a assinatura eletrônica mais recente do contrato, com o link do tomador e a jornada de formalização. Responde 404 (corpo vazio) quando o contrato ainda não tem assinatura.

Autenticação: API Key. Exige permissão de consulta de empréstimos.

Resposta​

CampoTipoDescrição
signatureIdstring (uuid)Envelope de assinatura.
codeintegerCódigo do envelope.
providerobject (code/key/name)Provedor de assinatura (ex.: unico_sign).
statusobject (Status)Situação do envelope: running (aguardando assinatura), partially_signed, completed, refused, canceled, expired ou failed. Ver Domínios › Assinatura Eletrônica.
completedAtstring (date-time) | nullConclusão do envelope.
ccbFileId / ccbFileUrlstring | nullCCB enviada para assinatura.
signers[]arraySignatários: id, name, documentNumber, email, signUrl (link de assinatura), status, expiresAt, signedAt, refusedAt, refusalReason, verification (resultado da verificação de identidade, quando o provedor faz) e identityDocuments[].
documents[]arrayDocumentos devolvidos pelo provedor ao final (CCB assinada, evidências, selfie, documento com foto): id, title, role, origin, fileId, fileName, fileExtension.
journeyIdstring (uuid) | nullJornada de formalização ligada à assinatura.
journeyUrlstring | nullEndereço da jornada, para enviar ao tomador.
journeyStatusobject (Status) | nullSituação da jornada. Ver Jornadas.
Visualizar Response
{
  "signatureId": "01a1f0d2-5c90-7d21-b6a3-9e8f7a6b5c4d",
  "code": 418,
  "provider": { "code": 400, "key": "unico_sign", "name": "Unico Sign" },
  "status": { "code": 2, "key": "running", "name": "Em Assinatura", "date": "2026-10-17T13:02Z", "color": "#2196F3", "note": null },
  "completedAt": null,
  "ccbFileId": "01a1f0d2-5b7e-7a10-8c44-0f1e2d3c4b5a",
  "ccbFileUrl": "https://{storage-url}/ccb-SM00030515.pdf",
  "signers": [
    {
      "id": "01a1f0d2-5c91-7e02-a1b2-c3d4e5f60718",
      "name": "JOAO TESTE ELEGIVEL PADRAO",
      "documentNumber": "99900010140",
      "email": "joao.teste@email.com",
      "signUrl": "https://{provedor-assinatura}/sign/abc123",
      "status": { "code": 2, "key": "sent", "name": "Notificado", "date": "2026-10-17T13:02Z", "color": "#2196F3", "note": null },
      "expiresAt": "2026-10-24T13:02Z",
      "signedAt": null,
      "refusedAt": null,
      "refusalReason": null,
      "verification": null,
      "identityDocuments": []
    }
  ],
  "documents": [],
  "journeyId": "01a1f0d2-5d12-7f33-b4c5-d6e7f8091a2b",
  "journeyUrl": "https://{journey-url}/j/Xk3pQ9",
  "journeyStatus": { "code": 1, "key": "pending", "name": "Aguardando Acesso", "date": "2026-10-17T13:02Z", "color": "#9E9E9E", "note": null }
}

POST /v5/loans/{loanId}/signature-requests/current/sync​

Consulta o provedor de assinatura e atualiza a assinatura mais recente do contrato (status do envelope, dos signatários e documentos devolvidos). Se a consulta mostrar a assinatura concluída, o contrato passa a signed como descrito na formalização. Normalmente desnecessário: as atualizações do provedor chegam sozinhas. Use quando o status parecer parado.

Não há corpo. Responde 200 no formato de GET .../signature-requests/current. Assinaturas em rascunho ou canceladas são devolvidas sem consulta ao provedor.

Autenticação: API Key. Exige permissão de edição de empréstimos.

SituaçãoCódigo
Empréstimo não encontrado1010001
Contrato sem assinatura eletrônica1010029

POST /v5/loans/{loanId}/signature-requests/current/journeys​

Gera uma nova jornada de formalização para a assinatura em andamento — por exemplo, quando a jornada anterior expirou ou foi cancelada — sem gerar nova CCB nem novo envelope. Responde 201 no formato de GET .../signature-requests/current, com o novo journeyId/journeyUrl. Não há corpo.

Autenticação: API Key. Exige permissão de edição de empréstimos.

SituaçãoCódigo
Empréstimo não encontrado1010001
Contrato sem assinatura eletrônica1010029
Assinatura não está aguardando assinatura (concluída, recusada, cancelada ou expirada)1010033
Nenhum signatário pendente com link de assinatura1010028

Quando a assinatura não está mais aberta, solicite uma nova formalização com POST /v5/loans/{loanId}/signature-requests. O funcionamento das jornadas está em Jornadas.

PUT /v5/loans/{id}/signatures​

Registra a data de assinatura do contrato e define status = signed (com status.date = signatureDate).

Use esta rota quando a assinatura acontece fora da plataforma. Quando a formalização é feita por POST /v5/loans/{loanId}/signature-requests, a conclusão da assinatura eletrônica já grava signatureDate e define status = signed sozinha.

Autenticação: API Key. Exige permissão de edição de empréstimos.

Parâmetros de rota​

Visualizar parâmetros
ParâmetroTipoObrigatórioDescrição
idstring (uuid)SimIdentificador do empréstimo devolvido em POST /v5/loans.

Payload de entrada​

Campos enviados pela requisição Assinar Operação da collection, na mesma ordem.

Visualizar parâmetros
CampoTipoObrigatórioDescrição
signatureDatestring (date-time) | nullNãoData/hora da assinatura. Gravada em signatureDate e usada como status.date.
Outros campos aceitos (não usados na collection)
CampoTipoObrigatórioDescrição
notestring | nullNãoObservação. Não é gravada pela assinatura.

A assinatura grava signatureDate, define status = signed e atualiza o log. Única validação de negócio: bloqueio se já integrated (1010002). Não há checagem do status anterior, então a chamada pode ser repetida para corrigir a data.

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "signatureDate": "{{signatureDate}}"
}

PUT /v5/loans/{id}/disbursements​

Registra o desembolso: fixa a data efetiva, recalcula o cronograma se a data mudou, integra com o banco liquidante e gera as cobranças de cada parcela. Define status = integrated.

Autenticação: API Key. Exige permissão de edição de empréstimos.

Parâmetros de rota​

Visualizar parâmetros
ParâmetroTipoObrigatórioDescrição
idstring (uuid)SimIdentificador do empréstimo.

Payload de entrada​

Campos enviados pela requisição Desembolsar Operação da collection, na mesma ordem.

Visualizar parâmetros
CampoTipoObrigatórioDescrição
disbursementDatestring (date) | nullNãoData efetiva do desembolso. Se omitida ou vazia, a API apenas define status = integrated com a data já prevista.
Outros campos aceitos (não usados na collection)
CampoTipoObrigatórioDescrição
notestring | nullNãoObservação.

Comportamento​

recebe disbursementDate
   │
   ├─ contrato já integrated ────────────► 400  1010002
   ├─ contrato já em stage = contract ───► 400  1010014
   │
   ├─ data vazia ou igual à prevista ────► status = integrated
   │
   └─ data diferente (e numberOfDisbursementOptions > 1)
        ├─ procura o cenário em disbursementOptions[] com essa data
        │     └─ não existe ──► 400  1010015 (nenhuma data de desembolso encontrada)
        ├─ aplica os valores do cenário (principal, IOF, líquido, taxas, tarifas)
        ├─ recalcula installments, firstDueDate, lastDueDate, calendarDays, businessDays
        ├─ stage = contract
        └─ status = integrated
   │
   ▼
envia a ordem de desembolso ao banco liquidante
   ├─ sucesso ──► gera as cobranças (uma por parcela; idempotente) ──► grava ──► 200
   └─ falha ────► step = awaiting_sync (1830) ──► 400 (contrato fica pendente de sincronização)
Por que os cenários de desembolso importam

Na emissão a API já calculou numberOfDisbursementOptions cenários, um por dia a partir da data prevista. Se o dinheiro sair em outro dia dentro dessa janela, a API adota o cenário daquele dia em vez de recalcular do zero, garantindo que os valores apresentados ao tomador sejam exatamente os praticados. Fora da janela, o desembolso é recusado com 1010015.

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "disbursementDate": "{{disbursementDate}}"
}
Falha de sincronização

Se o banco liquidante falhar, o contrato fica com step = awaiting_sync. Trate esse caso na integração: consulte o contrato e repita o desembolso quando o banco estiver disponível. As cobranças são geradas uma única vez, então a repetição é segura.

GET /v5/loans/{loanId}/disbursements​

Lista os comandos de desembolso do contrato. Quando o desembolso é feito por um pagador externo, cada envio do desembolso gera um comando com uma chave própria (key), que o pagador valida antes de pagar e confirma depois de pagar. A lista permite acompanhar esse ciclo e auditar as tentativas.

Autenticação: API Key. Exige permissão de consulta de empréstimos.

Ciclo do comando​

desembolso enviado ao pagador ──► status = pending ──► sent
   │
   ├─ pagador valida a chave e as condições ──► validated
   │     └─ condições alteradas, valor ou documento divergentes ──► rejected
   │
   └─ pagador confirma ──► completed (contrato desembolsado, evento loan.disbursed)
                       └─► failed    (evento loan.disbursement_failed)
  • Um novo envio cancela os comandos ainda abertos do mesmo contrato (canceled, nota "Substituído por nova solicitação de desembolso"). Depois que um comando é validated ou completed, não é possível enviar outro.
  • O cancelamento do contrato, inclusive pela desaverbação automática, cancela os comandos abertos.

Resposta​

Lista (vazia quando não houve desembolso), da mais recente para a mais antiga. Cada item:

CampoTipoDescrição
id, nid, codestring (uuid), integer, integerIdentificadores do comando.
loan, loanIdobject (Referência), string (uuid)Contrato.
providerobject (code/key/name) | nullPagador que recebeu o comando.
keystring (uuid)Chave do comando, validada pelo pagador.
disbursementDate, disbursementAmount, principalAmount, numberOfInstallments, installmentAmount, firstDueDate—Condições do contrato no momento do envio.
borrowerName, borrowerDocumentNumberstringTomador.
disbursementMethod, disbursementBankAccount, disbursementPix—Para onde o valor deve ser pago.
expiresAtstring (date-time)Validade prevista da chave (24 horas após a criação).
sentAtstring (date-time) | nullEnvio ao pagador.
validatedAt, lastValidatedAt, lastValidationIp, validationCount—Primeira e última validação feitas pelo pagador.
disbursedAt, confirmedAt, confirmationIp—Pagamento e confirmação informados pelo pagador.
note, datastring | nullObservação e dados adicionais enviados pelo pagador na confirmação.
statusobject (Status)Ver LoanDisbursementStatus. Em rejected/failed/canceled, status.note traz o motivo.
createdAt, createdBy, updatedAt—Auditoria do comando.
Visualizar Response
[
  {
    "id": "01a1f3a0-7b2c-7d10-9e8f-0a1b2c3d4e5f",
    "nid": 2105,
    "code": 87,
    "loan": { "code": 30515, "key": null, "name": "SM00030515" },
    "loanId": "01a0c239-c330-7361-ad20-fbeb57e97322",
    "provider": { "code": 9601, "key": "pagador_exemplo", "name": "Pagador Exemplo" },
    "key": "01a1f3a0-7b2d-74c1-8a90-112233445566",
    "disbursementDate": "2026-10-17",
    "disbursementAmount": 2141.570000,
    "principalAmount": 2215.840000,
    "numberOfInstallments": 96,
    "installmentAmount": 50.000000,
    "firstDueDate": "2026-12-21",
    "borrowerName": "JOAO TESTE ELEGIVEL PADRAO",
    "borrowerDocumentNumber": "99900010140",
    "disbursementMethod": { "code": 1, "key": "ted", "name": "TED" },
    "disbursementBankAccount": {
      "type": { "code": 1, "key": "checking_account", "name": "Conta Corrente" },
      "bank": "001",
      "branch": "1234",
      "number": "12345",
      "digit": "6"
    },
    "disbursementPix": null,
    "expiresAt": "2026-10-18T14:10Z",
    "sentAt": "2026-10-17T14:10Z",
    "validatedAt": "2026-10-17T14:12Z",
    "lastValidatedAt": "2026-10-17T14:12Z",
    "lastValidationIp": "203.0.113.10",
    "validationCount": 1,
    "disbursedAt": "2026-10-17T14:15Z",
    "confirmedAt": "2026-10-17T14:15Z",
    "confirmationIp": "203.0.113.10",
    "note": null,
    "data": null,
    "status": { "code": 8, "key": "completed", "name": "Concluído", "date": "2026-10-17T14:15Z", "color": "#388E3C", "note": "Confirmado pelo provedor" },
    "createdAt": "2026-10-17T14:10Z",
    "createdBy": { "code": 19, "key": null, "name": "Integração Exemplo" },
    "updatedAt": "2026-10-17T14:15Z"
  }
]
SituaçãoCódigo
Empréstimo não encontrado ou fora do nível de acesso1010001

PUT /v5/loans/{id}/endorsements​

Registra a averbação do contrato na folha do empregador: grava endorsementDate e define status = endorsement. No consignado privado, a averbação na Dataprev é assíncrona: a chamada responde com o contrato em endorsement_processing e o resultado chega depois.

Autenticação: API Key. Exige permissão de edição de empréstimos.

Parâmetros de rota​

Visualizar parâmetros
ParâmetroTipoObrigatórioDescrição
idstring (uuid)SimIdentificador do empréstimo.

Payload de entrada​

Campos enviados pela requisição Averbar Operação da collection, na mesma ordem.

Visualizar parâmetros
CampoTipoObrigatórioDescrição
endorsementDatestring (date) | nullNãoData em que a averbação foi confirmada pelo empregador ou pelo sistema de folha.
Outros campos aceitos (não usados na collection)
CampoTipoObrigatórioDescrição
notestring | nullNãoObservação (por exemplo, o protocolo da averbação).

A averbação não altera valores nem parcelas do contrato.

Averbação na Dataprev​

Quando o empréstimo é do tipo consignado privado, esta rota não apenas registra a data: a API envia o contrato à Dataprev e só conclui a averbação com a confirmação do provedor. Esse envio é feito em segundo plano. Para os demais tipos de empréstimo, nada é enviado e a rota continua síncrona: apenas registra a averbação e responde com status = endorsement.

Comportamento​

  1. A API faz as validações que não dependem da Dataprev (ver Validações).
  2. Marca o contrato com status = endorsement_processing (código 61, "Processando Averbação"), publica o evento loan.endorsement_requested e responde 200 imediatamente, sem aguardar a Dataprev.
  3. Em segundo plano, envia o contrato à Dataprev. Falhas temporárias do provedor (tempo esgotado, indisponibilidade) são repetidas automaticamente algumas vezes, com espera crescente; quando a cota da Dataprev é excedida, o envio é adiado até o horário indicado pelo provedor. Recusas de negócio encerram o processamento na hora.
  4. Se a Dataprev confirmar, o contrato passa a status = endorsement (código 62, "Averbado"), com endorsementDate preenchida, e o evento loan.endorsed é publicado.
  5. Se a Dataprev recusar, o contrato volta ao status que tinha antes da averbação, com status.note iniciando por "Averbação recusada:" seguido do motivo, e o evento loan.endorsement_failed é publicado.

Enquanto o contrato está em endorsement_processing, uma nova chamada de averbação é recusada com 1010023 ("Averbação do empréstimo já está em processamento"). Acompanhe o resultado por GET /v5/loans/{id} ou pelos eventos loan.endorsed e loan.endorsement_failed.

São enviados o tomador (CPF, nome, matrícula), o empregador (tipo e número de inscrição), o contrato (número, datas de início e fim, competência e data do primeiro desconto), os valores (contratado, liberado, parcela, IOF), as taxas mensal e anual, o CET mensal e anual e a garantia de FGTS.

Os valores monetários e os percentuais são enviados com duas casas decimais — a Dataprev recusa precisão maior (OT, tamanho de campo incorreto).

O numeroProposta não é enviado: ele só existe quando a operação nasce de uma proposta registrada na jornada iniciada pelo trabalhador na CTPS Digital, que esta rota não usa. Enviar um número qualquer resulta em SB (proposta não existente).

Os campos exigidos por esse envio já são validados na emissão e na edição do empréstimo, com os códigos 9503102 a 9503113 — um contrato de consignado privado não chega à averbação sem eles. Ver Tratamento de erros.

Garantia de FGTS na averbação​

Os valores de garantia saem do bloco privatePayroll do contrato e da consulta de saldo FGTS ligada a ele, não de collaterals[]:

Campo enviadoOrigem
temGarantiasprivatePayroll.hasCollateral
valorSaldoDisponivelGarantiaFgtsParte do saldo do FGTS dada em garantia, apurada pela API a partir da consulta de saldo FGTS
valorMultaRescisoriaGarantiaFgtsParte da multa rescisória dada em garantia, apurada pela API a partir da consulta de saldo FGTS
percVerbaRescisoriaGarantiaprivatePayroll.collateralSeveranceRate (ou o percentual disponível da consulta), convertido de fração para percentual

Declarada a garantia, a Dataprev exige cobertura integral e exata: a soma das garantias tem de bater com o valor do empréstimo, nem a menos nem a mais. Garantia insuficiente e garantia excedente devolvem a mesma recusa (FI), informando o valor esperado:

{ "messages": [
  { "code": "FI", "text": "Valores de garantia inválidos: para cobertura de 100%, as garantias informadas (8705.00) deveriam ser 2215.84 (100% do empréstimo de 2215.84)" },
  { "code": "9503101", "text": "Erro ao averbar o empréstimo na Dataprev" }
] }

Na conta da Dataprev entram os valores enviados mais a margem que ela apura do próprio cadastro do trabalhador — por isso o total que ela informa costuma ser maior que a soma dos dois campos enviados. Se a recusa persistir, confira o valor contratado e a consulta de saldo FGTS usada na emissão.

A competência do primeiro desconto é a do mês anterior ao firstDueDate, isto é, a competência da folha cujo repasse vence no primeiro vencimento. Ela precisa cair numa folha ainda aberta: um primeiro vencimento em competência já encerrada devolve HT (competência de início de desconto inválida).

Resultado gravado​

Confirmada a averbação, o retorno da Dataprev é gravado no registro de consignado privado do contrato:

Retorno da DataprevCampo
hashOperacaoendorsementProtocol
numeroContratoendorsementContractNumber
competenciaInicioDescontoendorsementFirstDiscountPeriod
codigoSucessoendorsementSuccessCode
mensagemendorsementMessage

Junto com eles, endorsementStatus passa a endorsed e endorsementDate recebe o instante da confirmação. Uma nova averbação sobrescreve os valores anteriores.

{
  "endorsementStatus": { "code": 30, "key": "endorsed", "name": "Averbada" },
  "endorsementDate": "2026-09-21T04:52Z",
  "endorsementProtocol": "1661201801",
  "endorsementContractNumber": "SM00030523",
  "endorsementFirstDiscountPeriod": 202611,
  "endorsementSuccessCode": "BD",
  "endorsementMessage": "Inclusão efetuada com sucesso"
}
Contratos averbados antes desta mudança

Até então esses cinco dados eram gravados em additionalData do empréstimo, com as chaves dataprev_endorsement_*. Os contratos já averbados mantêm esses registros; nada os migra para a nova estrutura.

Validações​

SituaçãoCódigo
Contrato já integrated1010002
Contrato com endorsementDate preenchida ou status = endorsement1010022
Averbação já em processamento (status = endorsement_processing)1010023
Consignado privado sem provedor registrado para a processadora1010016
Contrato sem a consulta de dados do trabalhador9503102
Trabalhador inelegível para o consignado privado9503115
Trabalhador bloqueado para empréstimo consignado9503116
Falha de comunicação com a Dataprev9503101
Dataprev não confirmou a averbação9503114

No consignado privado, 9503101 e 9503114 não voltam na resposta da chamada: são registrados depois, na nota do status do contrato ("Averbação recusada: ..."), junto com o evento loan.endorsement_failed. As demais validações continuam síncronas.

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "endorsementDate": "{{endorsementDate}}"
}

GET /v5/loan-private-payrolls/{loanId}/contract-information​

Mostra o que será enviado à Dataprev antes do envio: os documentos e os dados da assinatura concluída do empréstimo. É o que a tela exibe ao clicar em Enviar contrato na aba Consignado Privado.

Autenticação: API Key. Exige permissão de consulta de empréstimos.

Parâmetros​

Visualizar parâmetros
ParâmetroOndeTipoObrigatórioDescrição
loanIdrotastring (uuid)SimIdentificador do empréstimo.
signatureIdquerystring (uuid)NãoAssinatura a usar. Sem ele, vale a assinatura concluída mais recente do empréstimo.

Origem dos dados​

Nada é digitado: tudo sai da assinatura eletrônica concluída do empréstimo, do signatário que é o tomador.

Enviado à DataprevOrigem na assinatura
Contrato (contratoEmprestimo)Documento assinado da CCB
Registro biométrico facialSelfie coletada pelo provedor
Documento oficial com foto (frente e verso)Documento de identificação coletado pelo provedor. Quando não há verso, como na CNH, o mesmo arquivo vai como frente e verso, porque a Dataprev exige os dois (GA)
Data e hora da assinaturaMomento em que o tomador assinou a CCB
IP, latitude e longitudeEvidências de autenticidade da assinatura da CCB
DispositivoIdentificação do dispositivo ou navegador registrada na assinatura

Com selfie e documento com foto, a formalização enviada é documento oficial com foto. A Dataprev só aceita imagem na selfie e no documento com foto (recusa PDF com PV). Quando o provedor entrega o documento como PDF com a foto embutida, como a CNH da Unico, a imagem é extraída do PDF antes do envio. Dossiês de evidências e demais anexos da assinatura não são enviados, porque a Dataprev não tem campo para eles.

Resposta​

CampoTipoDescrição
signatureIdstring (uuid)Assinatura usada.
signatureTitlestringTítulo do envelope de assinatura.
signatureProviderobject (code/key/name)Provedor da assinatura.
signatureCompletedAtstring (date-time) | nullConclusão do envelope.
signerName / signerDocumentNumberstringTomador que assinou.
signedAtstring (date-time) | nullMomento da assinatura da CCB.
signatureIpstring | nullIP da assinatura.
latitude / longitudenumber | nullGeolocalização da assinatura.
devicestring | nullDispositivo da assinatura.
formalizationobject (code/key/name)official_document quando há selfie e documento com foto; none quando faltam.
documents[]arrayDocumentos que serão enviados: documentId, role (papel do documento na assinatura), title, fileId, fileName, extension, size.
{
  "signatureId": "01a1232c-ee24-7c6c-be41-c5ba672bc029",
  "signatureTitle": "Assinatura CT00000003",
  "signerName": "RAFAEL CESAR SOUZA",
  "signedAt": "2026-10-10T00:19:57.107Z",
  "signatureIp": "2804:b54:2300:1bd3:a94d:fb4d:418e:ade5",
  "latitude": -19.98440314,
  "longitude": -44.05018599,
  "device": null,
  "formalization": { "code": 1, "key": "official_document", "name": "Documento oficial com foto e selfie" },
  "documents": [
    { "role": { "code": 2, "key": "signed", "name": "Documento Assinado" }, "title": "Cédula de Crédito Bancário CT00000003 - Assinado", "fileName": "ccb-assinada.pdf" },
    { "role": { "code": 10, "key": "face_image", "name": "Imagem Facial" }, "title": "Selfie - RAFAEL CESAR SOUZA", "fileName": "selfie.jpg" },
    { "role": { "code": 11, "key": "document_front", "name": "Documento de Identificação - Frente" }, "title": "CNH - RAFAEL CESAR SOUZA", "fileName": "cnh.jpg" }
  ]
}

POST /v5/loan-private-payrolls/{loanId}/contract-information​

Envia à Dataprev o contrato assinado (CCB) e as evidências da formalização de um consignado privado já averbado. Os documentos e dados são os mesmos mostrados pelo GET acima, tirados da assinatura concluída. O envio é manual, por esta rota ou pelo botão Enviar contrato da aba Consignado Privado.

Autenticação: API Key. Exige permissão de edição de empréstimos.

Payload de entrada​

Visualizar parâmetros
CampoTipoObrigatórioDescrição
signatureIdstring (uuid) | nullNãoAssinatura a usar. Sem ele, vale a assinatura concluída mais recente do empréstimo.

Comportamento​

  1. A API confere se o empréstimo está averbado (endorsementStatus = endorsed), localiza a assinatura concluída e monta o pacote do envio.
  2. Valida que a assinatura tem a CCB assinada, a data e o IP da assinatura e a selfie com o documento oficial com foto.
  3. Marca contractInformationStatus = requested, enfileira o envio e responde 200 com o registro de consignado privado, sem aguardar a Dataprev.
  4. Em segundo plano, envia à Dataprev o contrato, as imagens e as evidências, junto com CPF, matrícula, empregador e o número do contrato devolvido pela averbação. Falhas temporárias do provedor são repetidas automaticamente; quando a cota da Dataprev é excedida, o envio é adiado.
  5. Se a Dataprev aceitar, contractInformationStatus passa a sent, com contractInformationSentAt e o código devolvido em contractInformationSuccessCode, e o evento private_payroll_loan.contract_information_sent (2050) é publicado.
  6. Se a Dataprev recusar, contractInformationStatus passa a error, o motivo fica em contractInformationMessage e o evento private_payroll_loan.contract_information_failed (2051) é publicado.

Enquanto o envio está em requested, uma nova chamada é recusada com 9503137. Depois de sent ou error, a rota pode ser chamada de novo para reenviar.

Resultado gravado​

Gravado no registro de consignado privado do contrato, devolvido por esta rota:

CampoTipoDescrição
contractInformationStatusobject (code/key/name)pending (10), requested (20), sent (30) ou error (40).
contractInformationSentAtstring (date-time) | nullMomento em que a Dataprev aceitou o envio.
contractInformationSuccessCodestring | nullCódigo devolvido pela Dataprev no aceite.
contractInformationMessagestring | nullMotivo da recusa, quando houver.

Validações​

SituaçãoCódigo
Empréstimo sem registro de consignado privado1010025
Empréstimo ainda não averbado na Dataprev9503131
Nenhuma assinatura concluída para o empréstimo9503138
Envio já em processamento9503137
Assinatura sem a CCB assinada9503132
Arquivo da CCB assinada não encontrado9503133
Assinatura sem data e hora9503134
Assinatura sem IP9503135
Assinatura sem selfie e documento oficial com foto9503136
Falha de comunicação ou recusa da Dataprev9503130

9503130 não volta na resposta da chamada: é registrado depois em contractInformationMessage, junto com o evento private_payroll_loan.contract_information_failed.

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "signatureId": "01a1232c-ee24-7c6c-be41-c5ba672bc029"
}

Desaverbação automática​

No consignado privado, um contrato averbado e não desembolsado compromete a margem do trabalhador. Para liberar essa margem, a empresa pode configurar um prazo em dias: passado esse prazo desde a averbação sem que o dinheiro tenha sido pago, a plataforma exclui a averbação na Dataprev e cancela o contrato, sem nenhuma chamada do integrador.

A configuração fica no grupo de configurações da Dataprev (Crédito do Trabalhador) da empresa e é feita pela equipe da Semear:

ConfiguraçãoChaveDescrição
Dias sem Desembolso para Desaverbarendorsement_exclusion_daysPrazo, em dias contados da averbação. Vazio ou zero desliga a desaverbação automática.
Motivo da Desaverbação Automáticaendorsement_exclusion_reasonMotivo informado à Dataprev. Padrão: withdrawal. Ver LoanPrivatePayrollExclusionReason.

Quem é elegível​

Só contratos de consignado privado com a averbação confirmada (endorsementStatus = endorsed), com o contrato em status = endorsement ou awaiting_disbursement e sem comando de desembolso já validado ou concluído pelo pagador. Se o contrato mudar de situação antes do envio — por exemplo, o desembolso for validado pelo pagador — a exclusão termina com erro e o contrato segue normalmente. Uma exclusão que terminou com erro não é tentada de novo automaticamente.

Efeitos​

  1. A exclusão é enviada à Dataprev em segundo plano, com as mesmas novas tentativas e o mesmo limite de chamadas das demais operações da Dataprev. Enquanto isso, exclusionStatus = requested.
  2. Confirmada pela Dataprev:
    • o registro de consignado privado passa a endorsementStatus = excluded, com exclusionStatus = sent e os dados do retorno (ver tabela abaixo);
    • os comandos de desembolso abertos são cancelados;
    • o contrato passa a status = canceled, com status.note "Desaverbado automaticamente após N dia(s) sem desembolso";
    • são publicados os eventos private_payroll_loan.exclusion_completed (2052) e loan.canceled (1004).
  3. Recusada pela Dataprev, ou abandonada porque o contrato deixou de ser elegível: exclusionStatus = error, o motivo fica em exclusionMessage, o contrato não é cancelado e o evento private_payroll_loan.exclusion_failed (2053) é publicado.

Campos gravados no registro de consignado privado​

CampoTipoDescrição
exclusionReasonobject (code/key/name)Motivo informado à Dataprev.
exclusionStatusobject (code/key/name)requested (20), sent (30) ou error (40).
excludedAtstring (date-time) | nullMomento em que a Dataprev confirmou a exclusão.
exclusionPeriodinteger | nullCompetência da exclusão devolvida pela Dataprev (AAAAMM).
exclusionSuccessCodestring | nullCódigo devolvido pela Dataprev no aceite.
exclusionMessagestring | nullMensagem da Dataprev, ou o motivo da recusa.
Na integração

Trate o evento loan.canceled (ou private_payroll_loan.exclusion_completed) para retirar a proposta da sua esteira: depois da desaverbação, o contrato não pode mais ser desembolsado. Para manter um contrato vivo, desembolse antes do prazo configurado.

Observações​

  • Ordem averbação/desembolso: ver aviso em Ciclo de vida.
  • Conta bancária: use number, digit e type (checking_account/savings_account) em disbursementBankAccount.
  • Endereço do tomador: use postalCode e district em borrower.address.
  • Modalidade de saque do FGTS: use severance_withdrawal ou birthday_withdrawal. Outros valores (como severance-withdrawal, com hífen) não são reconhecidos e são ignorados.
  • Tipo de pessoa: o tomador do consignado privado é sempre gravado como pessoa física (natural_person).