Visão geral

A API Semear LCP não é um CRUD livre: é uma sequência de chamadas encadeadas, em que cada resposta devolve o identificador exigido pela chamada seguinte. Esta página mostra a sequência completa e quais campos encaminhar.

Diagrama do fluxo

 Autenticação (header X-Api-Key em todas as chamadas)
     │
     ▼
 1. Termo de autorização ───► termId, termKey (status "pending")
 2. Aceite do trabalhador ──► envelope de assinatura concluído
 3. Termo autorizado ───────► status "active" + token Dataprev
     │
     ▼
 4. Consulta de vínculos ───► relationshipQueryId
 5. Leitura dos vínculos ───► items[].id = employmentRelationshipId
     │
     ├──► 6. Dados do trabalhador ──► employeeDataId (margem, renda, alertas)
     └──► 7. Saldo FGTS ────────────► fgtsBalanceId (saldo e multa para garantia)
     │
     ▼
 8. Simulação ──────────────► condições (parcela, desembolso, custo efetivo, IOF)
     │
     ▼
 9. Emissão ────────────────► loanId (status "draft")
10. Consulta do contrato
     │
     ├──► 11. Formalização ─► status "signed"
     ├──► 12. Averbação ────► "endorsement_processing" → "endorsement"
     │       └─ envio da CCB assinada à Dataprev
     ├──► 13. Desembolso ───► "disbursement_processing" → "integrated"
     └──► 14. Comandos de desembolso ► disbursementKey

As etapas 6 e 7 são independentes entre si e podem ser chamadas em qualquer ordem, ou em paralelo, para o mesmo vínculo.

Chamadas à Dataprev são assíncronas

O termo, as três consultas, a formalização e a averbação não terminam na chamada: a API valida, grava o registro como pendente e responde na hora; o processamento acontece em segundo plano. Antes de seguir para a próxima etapa, acompanhe o resultado pelos eventos de webhook correspondentes ou, onde existe, pela rota de leitura do recurso (GET /{id} do termo, dos vínculos e do empréstimo; document-requests/current da formalização). Dados do trabalhador e saldo FGTS só são entregues por evento. Ver Processamento assíncrono.

Passo a passo

O roteiro abaixo segue as requisições da collection Semear LCP - Loan Private Payroll - Docs, na mesma ordem e com os mesmos payloads. Os exemplos usam o trabalhador de referência da massa de teste de homologação (CPF 11107543029). Os bodies são os da collection, com as mesmas variáveis: {{termId}}, {{employeeDataId}} etc. são os identificadores devolvidos pelas etapas anteriores, preenchidos pelos scripts de teste. O CPF e o nome do trabalhador vêm das variáveis {{workerCpf}} e {{workerName}}.

0. Autenticar

Envie a API Key do usuário de integração da sua empresa no header X-Api-Key de todas as chamadas. Na collection, a autenticação de cada requisição é do tipo API Key, com a variável {{x_api_key}}. Veja Autenticação.

X-Api-Key: {api_key}
Content-Type: application/json

1. Criar o termo de autorização

Collection: Criar Termo de Autorização — POST /v5/loan-private-payrolls/terms

O mínimo é o titular. Sem document, a API gera o texto do termo a partir do modelo padrão da empresa (ou do texto padrão da plataforma):

{
  "subject": {
    "documentNumber": "{{workerCpf}}",
    "name": "{{workerName}}"
  }
}

A resposta (201) traz o termo em status = pending, sem token. Guarde: id → termId e key → termKey.

2. Registrar o aceite do trabalhador

Collection: Assinar Termo — POST /v5/authorization-terms/{termId}/sign

O termo só vai à Dataprev depois do aceite. Envie as evidências de como o trabalhador aceitou:

{
  "signer": {
    "name": "{{workerName}}",
    "documentType": "cpf",
    "documentNumber": "{{workerCpf}}",
    "email": "trabalhador@exemplo.com",
    "phone": "+5511900000000"
  },
  "signerRole": "owner",
  "authenticationType": "opt_in",
  "location": "São Paulo/SP",
  "signedAt": "2026-10-19T12:05:00Z",
  "authenticity": {
    "timestamp": "2026-10-19T12:05:00Z",
    "ipAddress": "203.0.113.10",
    "sessionId": "sess-8f3a2c",
    "userAgent": "Mozilla/5.0 (Linux; Android 14) Chrome/128",
    "deviceId": "dev-a1b2c3",
    "fingerprint": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
    "channel": "mobile",
    "data": [
      {
        "key": "latitude",
        "value": "-23.5505"
      },
      {
        "key": "longitude",
        "value": "-46.6333"
      },
      {
        "key": "nsu",
        "value": "123456988"
      }
    ]
  }
}

Só signer.documentNumber é obrigatório; signedAt e authenticity.timestamp assumem o momento da chamada quando omitidos. latitude e longitude em authenticity.data viram as coordenadas da evidência; os demais pares ficam como dados adicionais. A resposta traz o termo com o aceite em signatures[] (envelope internal, completed). O termo continua pending até a Dataprev responder.

O aceite também pode ir no próprio POST .../terms, no campo signatures, ou ser colhido do trabalhador por uma jornada de aceite.

3. Acompanhar o termo

Collection: Consultar Termo por ID — GET /v5/authorization-terms/{termId} · Consultar Termo pela Chave — GET /v5/authorization-terms/key/{termKey}

Em segundo plano, a plataforma registra a autorização na Dataprev. Quando ela responde, o termo passa a active, com token e expiresAt (evento authorization_term.activated); se recusar, passa a rejected (evento authorization_term.rejected). Siga para a próxima etapa quando o termo estiver active.

Reaproveite o termo

Um termo active vale para todas as consultas seguintes até expiresAt. Não crie um termo por consulta.

4. Listar os vínculos empregatícios

Collection: Consultar vínculos com um termo já criado — POST /v5/private-payroll-employment-relationships

{
  "authorizationTermId": "{{termId}}"
}

A resposta traz a consulta em status = pending, ainda sem itens. Guarde: id → relationshipQueryId.

Alternativamente, envie os dados do termo no mesmo corpo (subject, signatures...) e a API cria o termo e consulta os vínculos em uma única chamada; nesse caso a consulta aguarda a autorização do termo antes de ir à Dataprev.

5. Ler os vínculos

Collection: Consultar vínculos por ID da Consulta — GET /v5/private-payroll-employment-relationships/{relationshipQueryId}

Repita até o status sair de pending, ou aguarde o evento private_payroll_employment_relationship.completed. Para cada item de items[], observe:

Campo	Significado
id	Identificador do vínculo. É o employmentRelationshipId das etapas 6 e 7.
isEligible	Se o vínculo pode receber consignado.
isBlockedForLoan	Se o trabalhador bloqueou empréstimos nesse vínculo.
ineligibilityReason	Motivo, quando não elegível.

Selecione um vínculo elegível e não bloqueado. Guarde: items[].id → employmentRelationshipId (a collection escolhe o primeiro elegível e não bloqueado).

6. Consultar os dados do trabalhador

Collection: Consulta dados do trabalhador — POST /v5/private-payroll-employee-data

{
  "authorizationTermId": "{{termId}}",
  "employmentRelationshipId": "{{employmentRelationshipId}}"
}

Guarde: id → employeeDataId. A resposta volta em status = pending; o resultado é entregue pelo evento private_payroll_employee_data.completed. Os campos decisivos para a análise são availableMarginAmount (limite da parcela), totalEarningsAmount, isEligible, loanBlockType, legacyLoans[] e alerts[].

7. Consultar o saldo de FGTS

Collection: Consulta de garantias FGTS — POST /v5/private-payroll-fgts-balances

Mesmo corpo da etapa 6:

{
  "authorizationTermId": "{{termId}}",
  "employmentRelationshipId": "{{employmentRelationshipId}}"
}

Guarde: id → fgtsBalanceId. O resultado chega pelo evento private_payroll_fgts_balance.completed, com availableBalanceAmount, severanceFineAmount e totalAvailableAmount. Depende de o trabalhador ter autorizado o acesso ao saldo no aplicativo da Carteira de Trabalho Digital. Só é necessária quando a operação terá garantia de FGTS.

As etapas 6 e 7 são independentes e podem ser chamadas em paralelo.

8. Simular

Collection: Simulação por Valor de Parcela · Simulação por Valor do Desembolso — POST /v5/loan-simulations

Envie um valor de referência: installmentAmount fixa a parcela (tipicamente a margem disponível) e disbursementAmount fixa o valor em conta.

{
  "product": "private_payroll",
  "disbursementDate": "2026-10-16",
  "firstDueDate": "2026-10-16",
  "numberOfInstallments": 96,
  "installmentAmount": 100.00,
  "monthlyRate": 0.018,
  "resultOptions": {
    "disableInstallments": true
  }
}

Na Simulação por Valor do Desembolso, a collection troca installmentAmount por "disbursementAmount": 5000.00 (e usa outras datas de exemplo). resultOptions.disableInstallments = true omite a tabela de parcelas da resposta. A resposta traz principal, líquido, IOF, custo efetivo e as datas ajustadas pelas regras do produto: use sempre as datas devolvidas ao emitir. A simulação não exige termo nem consultas.

9. Emitir o contrato

Collection: Emissão da operação por Valor de Parcela · por Valor de Parcela (COM GARANTIA) · por Valor do Desembolso · por Valor do Principal — POST /v5/loans

Envie os parâmetros financeiros da simulação, o tomador, o bloco privatePayroll e a conta de desembolso. A collection calcula as datas no script de pré-requisição: desembolso hoje e primeiro vencimento um mês depois.

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

As quatro variantes da collection mudam só o valor de referência e o bloco privatePayroll:

Variante	Valor de referência	privatePayroll
Por Valor de Parcela	"installmentAmount": 100	{ "employeeDataId": "{{employeeDataId}}" }
Por Valor de Parcela (com garantia)	"installmentAmount": 100	{ "employeeDataId": "{{employeeDataId}}", "fgtsBalanceId": "{{fgtsBalanceId}}", "hasCollateral": true, "fgtsWithdrawalType": "severance_withdrawal", "collateralSeveranceRate": null }
Por Valor do Desembolso	"disbursementAmount": 8705.00	{ "employeeDataId": "{{employeeDataId}}" }
Por Valor do Principal	"principalAmount": 8705.00	{ "employeeDataId": "{{employeeDataId}}" }

Com garantia, os valores de saldo do FGTS e de multa rescisória comprometidos são calculados pela API a partir da consulta de saldo FGTS, até cobrir o valor contratado; se não cobrirem, a emissão é recusada (9504106). Ver bloco privatePayroll.

O contrato nasce em status = draft. Guarde: id → loanId.

Emita depois que as consultas concluírem

O employeeDataId e o fgtsBalanceId copiam para o contrato a matrícula, o empregador, a margem e os valores de FGTS que a averbação exige. Emita só depois de receber os eventos .completed das etapas 6 e 7: uma consulta ainda pendente ou com erro não tem esses dados.

10. Consultar o contrato

Collection: Consultar Operação por ID — GET /v5/loans/{loanId}

Devolve o contrato com status, valores e parcelas. Use para acompanhar as transições das próximas etapas.

11. Formalizar (assinar)

Collection: Assinar Operação — PUT /v5/loans/{loanId}/signatures

{
  "signatureDate": "{{signatureDate}}"
}

Registra a assinatura feita fora da plataforma: grava signatureDate e leva o contrato a signed.

Para que a plataforma gere a CCB e colha a assinatura eletrônica do tomador, use POST /v5/loans/{loanId}/signature-requests no lugar desta chamada: o contrato vai a awaiting_formalization, a CCB e o link de assinatura são gerados em segundo plano (document-requests/current e signature-requests/current) e, quando o tomador assina pela jornada, o contrato passa a signed (evento loan.signed).

12. Averbar

Collection: Averbar Operação — PUT /v5/loans/{loanId}/endorsements

{
  "endorsementDate": "{{endorsementDate}}"
}

O contrato passa a endorsement_processing e é enviado à Dataprev em segundo plano (evento loan.endorsement_requested). Na confirmação, vai a endorsement, com endorsementDate, e é publicado loan.endorsed; na recusa, volta ao status anterior e é publicado loan.endorsement_failed.

Depois da averbação, envie à Dataprev a CCB assinada e as evidências da assinatura com POST /v5/loan-private-payrolls/{loanId}/contract-information (eventos private_payroll_loan.contract_information_sent ou private_payroll_loan.contract_information_failed).

13. Desembolsar

Collection: Desembolsar Operação — PUT /v5/loans/{loanId}/disbursements

{
  "disbursementDate": "{{disbursementDate}}"
}

Fixa a data de desembolso, recalcula o contrato se a data mudou, envia ao banco liquidante, gera as cobranças e publica loan.disbursement_requested. Na confirmação do banco, o contrato passa a integrated e é publicado loan.disbursed; na recusa, é publicado loan.disbursement_failed.

14. Acompanhar o desembolso

Collection: Consultar Desembolso por ID da Operação — GET /v5/loans/{loanId}/disbursements

Lista os comandos de desembolso do contrato, do mais recente ao mais antigo, com o status de cada um. Guarde: [0].key → disbursementKey, a chave que o banco liquidante valida antes de pagar.

O desembolso vem por último

Depois de integrated, o contrato não aceita mais assinatura, desembolso ou averbação (1010002). Por isso a sequência é formalizar (assinar) → averbar → desembolsar, a mesma ordem da collection. Confirme com o seu convênio se a averbação é exigida antes do desembolso.

Depois de averbado, o contrato precisa ser desembolsado dentro do prazo que a empresa configurou para a desaverbação automática; passado o prazo, a averbação é excluída na Dataprev e o contrato é cancelado (evento loan.canceled).

Encadeamento de identificadores

api key ──────────────────────────────► header X-Api-Key
terms.id ─────────────────────────────► termId: {id} do sign e authorizationTermId (etapas 4, 6, 7)
terms.key ────────────────────────────► termKey: GET /v5/authorization-terms/key/{termKey}
employment-relationships.id ──────────► relationshipQueryId: GET da consulta de vínculos
employment-relationships.items[].id ──► employmentRelationshipId (etapas 6, 7)
employee-data.id ─────────────────────► privatePayroll.employeeDataId (etapa 9)
fgts-balances.id ─────────────────────► privatePayroll.fgtsBalanceId (etapa 9, com garantia)
loan-simulations.* ───────────────────► parâmetros financeiros do POST /v5/loans
loans.id ─────────────────────────────► loanId: {id} das rotas de formalização, averbação e desembolso
loans/{loanId}/disbursements[0].key ──► disbursementKey

Variáveis usadas nos exemplos

Variável	Na collection	Significado
{base-url}	{{baseUrl}}	Origem do servidor da API (ver Ambientes)
{api_key}	{{x_api_key}}	Chave de integração
{termId}	{{termId}}	id do termo de autorização
{termKey}	{{termKey}}	key do termo de autorização
{relationshipQueryId}	{{relationshipQueryId}}	id da consulta de vínculos
{employmentRelationshipId}	{{employmentRelationshipId}}	id de um item da lista de vínculos (items[].id)
{employeeDataId}	{{employeeDataId}}	id da consulta de dados do trabalhador
{fgtsBalanceId}	{{fgtsBalanceId}}	id da consulta de saldo FGTS
{loanId}	{{loanId}}	id do empréstimo emitido
{disbursementKey}	{{disbursementKey}}	key do comando de desembolso mais recente