Pular para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Criar Proposta

Cria uma proposta de empréstimo para um trabalhador, em um de dois modos:

  • Com simulationPublicId: basta simulationPublicId + employmentRelationshipPublicId. Valores e parcelas vêm da simulação, que precisa estar em EPHEMERAL e passa a CONVERTED_TO_PROPOSAL.

  • Sem simulationPublicId: todos os campos financeiros e installments são obrigatórios e devem ser consistentes com a simulação de referência; divergências significativas podem levar à rejeição.

A proposta usa tacAmount (sempre 0) e insuranceAmount separados; o feesAmount da simulação está deprecated. O feesAmount de cada parcela em installments não está deprecated.

Request

POST /api/v1/originator/employees/{publicId}/proposals

Autenticação: Authorization: Bearer {originatorToken}.

Parâmetros

Parâmetro
Local
Tipo
Obrigatório
Descrição

publicId

path

string

Sim

Identificador público do employee

Corpo

Campo
Tipo
Obrigatório
Descrição

simulationPublicId

string (uuid)

Não

ID da simulação. Define o modo (ver acima).

employmentRelationshipPublicId

string (uuid)

Sim

ID do vínculo empregatício

loanAmount

decimal

Condicional

Valor do empréstimo em reais. Obrigatório sem simulationPublicId.

financedAmount

decimal

Condicional

Valor financiado em reais (principal + juros + encargos). Obrigatório sem simulationPublicId.

totalInterestAmount

decimal

Condicional

Valor total de juros em reais. Obrigatório sem simulationPublicId.

monthlyInterestRate

decimal

Condicional

Taxa de juros mensal (%). Obrigatório sem simulationPublicId.

monthlyEffectiveCost

decimal

Condicional

CET mensal (%). Obrigatório sem simulationPublicId.

annualEffectiveCost

decimal

Condicional

CET anual (%). Obrigatório sem simulationPublicId.

disbursementAmount

decimal

Condicional

Valor líquido a receber pelo trabalhador. Obrigatório sem simulationPublicId.

insuranceAmount

decimal

Condicional

Valor do seguro prestamista. Obrigatório sem simulationPublicId.

iofAmount

decimal

Condicional

Valor total de IOF. Obrigatório sem simulationPublicId.

tacAmount

decimal

Opcional

TAC (Taxa de Abertura de Crédito). Deve ser 0 ou null; valor positivo dá 400 (Produto não permite TAC (Taxa de Abertura de Crédito) conforme legislação vigente).

installmentCount

integer

Condicional

Número de parcelas. Obrigatório sem simulationPublicId.

dueDate

string (date)

Condicional

Data de vencimento da primeira parcela. Obrigatório sem simulationPublicId.

installments

array

Condicional

Parcelas. Obrigatório sem simulationPublicId.

Objeto de cada item de installments

Campo
Tipo
Descrição

installmentNumber

integer

Número da parcela (1-based)

installmentAmount

decimal

Valor da parcela (desconto em folha)

dueDate

string (date)

Data de vencimento (yyyy-MM-dd)

amortizationAmount

decimal

Amortização (principal) da parcela

interestAmount

decimal

Juros da parcela

iofAmount

decimal

IOF da parcela

feesAmount

decimal

Taxas da parcela

outstandingBalance

decimal

Saldo devedor após a parcela

daysToCompensate

integer

Dias para compensação

documentNumber

string (máx. 10)

Número identificador do vencimento. Opcional

ourNumber

string (máx. 32)

Nosso número do documento no banco emissor. Opcional

ourNumberBankCode

string (máx. 3)

Código do banco do nosso número. Opcional

participantControl

string (máx. 25)

Controle do participante. Opcional

As parcelas da proposta são as do contrato.

Campos de leilão

Informe só quando a proposta materializa uma oferta de leilão aceita pelo trabalhador.

Campo
Tipo
Descrição

proposalNumber

string (máx. 20)

Número da oferta (GT-{prefixo}-{único}). É o que classifica a operação como leilão: com ele, a CCB é formalizada no programa de leilão do originador; sem ele, a operação é tratada como originação ativa. Vazio equivale a ausente.

solicitationId

integer

Identificador Dataprev da solicitação. Opcional: com proposalNumber, a Giro grava o da oferta (um valor diferente retorna 422); sem proposalNumber, é ignorado.

Campos bancários do documento

documentNumber, ourNumber, ourNumberBankCode e participantControl são opcionais e repassados ao banco emissor na formalização da CCB, para você reconciliar a parcela com o documento bancário. A Giro só valida o tamanho.

Quando omitidos, dois deles são gerados a partir do número da CCB e da parcela com dois dígitos:

Campo

Gerado (CCB 00000001, parcela 1)

documentNumber

0000000101

participantControl

00000001-01

ourNumber e ourNumberBankCode omitidos não são enviados.

A resposta devolve os quatro campos como você os enviou.

Response

Campo
Tipo
Descrição

publicId

string

Identificador público da proposta — o proposalPublicId de Criar Contrato

employeePublicId

string

Identificador público do trabalhador (16 caracteres Base64 URL-safe)

simulationPublicId

string (uuid)

Simulação de referência; null sem simulação

loanAmount

number

Valor do empréstimo em reais

financedAmount

number

Valor financiado em reais

totalInterestAmount

number

Juros totais em reais

monthlyInterestRate

number

Taxa mensal em percentual

monthlyEffectiveCost

number

CET mensal em percentual

annualEffectiveCost

number

CET anual em percentual

disbursementAmount

number

Valor a desembolsar em reais

insuranceAmount

number

Seguro em reais

iofAmount

number

IOF em reais

tacAmount

number

TAC em reais (sempre 0)

debitAmount

number

Valor total a pagar (installmentCount × installmentAmount) em reais

outstandingBalance

number

Saldo devedor em reais

installmentCount

integer

Número de parcelas

dueDate

string (date)

Data de vencimento da primeira parcela

status

string

Status da proposta: PENDING, ACCEPTED, REJECTED, EXPIRED ou CONVERTED_TO_CONTRACT

expiresAt

string (date-time)

Data e hora limite para aceite

acceptedAt

string (date-time)

Data e hora do aceite, quando aplicável

installments

array

Lista de parcelas (installmentNumber, dueDate, installmentAmount, amortizationAmount, interestAmount, iofAmount, feesAmount, outstandingBalance, daysToCompensate, documentNumber, ourNumber, ourNumberBankCode, participantControl)

createdDate

string (date-time)

Data e hora de criação da proposta (UTC)

201 Created.

Exemplo

Request com simulationPublicId

Request sem simulationPublicId

O exemplo mostra só a primeira parcela; envie uma por parcela, installmentCount no total.

Response 201 Created

Resposta ao request com simulationPublicId acima. Sem simulação, o corpo tem o mesmo formato, com simulationPublicId nulo e os valores enviados.

Próximo passo

Criar Contrato com o publicId retornado.

Erros

Código

errorCode

Situação

400

—

Payload inválido (properties.errors): informe exatamente um identificador de vínculo/simulação; proposalNumber até 20 caracteres; installmentAmount ≥ 0,01; campos de garantia

400

—

UUID ou data inválidos (type: about:blank)

400

TAC_NOT_ALLOWED

tacAmount diferente de 0 (positivo ou negativo)

400

INSTALLMENT_NOT_IN_SIMULATION

Parcela informada não existe na simulação

400

—

Simulação não encontrada: <id> ou vínculo não encontrado — inexistente ou de outro employee

400

—

Modo manual: Campos obrigatórios ausentes ou inválidos: <lista> (inclui dueDate no passado e taxa anual incoerente) ou A quantidade de parcelas (N) deve ser igual a installmentCount (M)

400

—

CET acima do teto: title: Elegibility Violation, properties.violations[].code = MAX_EFFECTIVE_COST_EXCEEDED

403

AUCTION_PARTICIPATION_DISABLED

proposalNumber de uma oferta válida, com o originador sem participação no leilão habilitada. Avaliado depois do 422 AUCTION_OFFER_NOT_FOUND; nada é gravado

404

—

Employee não encontrado ou de outro originador

409

INVALID_SIMULATION_TAC

Simulação antiga com TAC maior que 0. Refaça a simulação

422

FI

Cobertura de garantia FGTS fora da regra; a mensagem traz o valor esperado. Ver Cobertura de Garantias

422

AUCTION_OFFER_NOT_FOUND

proposalNumber que não é oferta de leilão sua para este trabalhador e esta solicitationId, ou já convertida em contrato. proposalNumber vazio equivale a ausente

429

—

Mais de 75 requisições por segundo

500

—

Simulação que não está mais disponível para virar proposta (já convertida ou expirada). Crie uma nova simulação

Erros comuns a todos os endpoints — 401, 403 de token, 409 de Idempotency-Key em processamento, 500 e 503 — e o formato ProblemDetail estão em Erros da API.

Criar Proposta

post
/api/v1/originator/employees/{publicId}/proposals

Cria uma nova proposta de empréstimo. Dois modos de criação:

  • Com simulationPublicId: apenas o identificador da simulação + employmentRelationshipPublicId são necessários. Dados financeiros e parcelas são derivados automaticamente da simulação.

  • Sem identificador de simulação: todos os campos financeiros e installments são obrigatórios.

Autorizações
AuthorizationstringObrigatório

JWT token fornecido pelo administrador

Parâmetros de rota
publicIdstringObrigatório

Identificador público do employee (16 caracteres)

Parâmetros de cabeçalho
Idempotency-Keystring · máx: 255Opcional

Chave de idempotência para evitar duplicação em retentativas. Se fornecida, o servidor retornará a mesma resposta para chamadas com a mesma chave do mesmo originador. A chave é retida por 7 dias. Depois desse prazo ela é expurgada e uma requisição com a mesma chave é tratada como nova, sendo reprocessada.

Corpo

Cria uma proposta de empréstimo. Dois modos de criação:

  • Com simulationPublicId: apenas simulationPublicId + employmentRelationshipPublicId são obrigatórios; todos os dados financeiros e parcelas são derivados da simulação (status EPHEMERAL). A simulação é marcada como CONVERTED_TO_PROPOSAL.
  • Sem simulationPublicId: todos os campos financeiros e installments são obrigatórios.
simulationPublicIdstring · uuidOpcional

Identificador público opaco da simulação. Quando informado, dados financeiros e parcelas são derivados automaticamente da simulação, que deve estar no status EPHEMERAL; se não for informado, a proposta é criada manualmente a partir dos campos financeiros abaixo.

Example: 0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b05
employmentRelationshipPublicIdstring · uuidOpcional

Identificador público opaco do vínculo empregatício.

Example: 0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02
loanAmountnumber · decimal · mín: 0.01Opcional

Valor do empréstimo em reais. Obrigatório sem simulationPublicId.

financedAmountnumber · decimal · mín: 0.01Opcional

Valor financiado em reais. Obrigatório sem simulationPublicId.

totalInterestAmountnumber · decimalOpcional

Juros totais em reais. Obrigatório sem simulationPublicId.

monthlyInterestRatenumber · decimalOpcional

Taxa de juros mensal em percentual. Obrigatório sem simulationPublicId.

annualInterestRatenumber · decimalOpcional

Taxa de juros anual em percentual. Obrigatório sem simulationPublicId. Deve ser coerente com monthlyInterestRate (dentro da banda entre a taxa nominal i*12 e a efetiva composta (1+i)^12-1); valores fora dessa banda retornam 400 Bad Request.

monthlyEffectiveCostnumber · decimalOpcional

CET mensal em percentual. Obrigatório sem simulationPublicId.

annualEffectiveCostnumber · decimalOpcional

CET anual em percentual. Obrigatório sem simulationPublicId.

disbursementAmountnumber · decimalOpcional

Valor a desembolsar em reais. Obrigatório sem simulationPublicId.

insuranceAmountnumber · decimalOpcional

Valor do seguro em reais. Obrigatório sem simulationPublicId.

iofAmountnumber · decimalOpcional

IOF em reais. Obrigatório sem simulationPublicId.

tacAmountnumber · decimalOpcional

TAC em reais. Deve ser 0 ou null. Enviar valor positivo retorna 400 Bad Request com a mensagem "Produto não permite TAC (Taxa de Abertura de Crédito) conforme legislação vigente".

installmentCountinteger · mín: 1Opcional

Número de parcelas. Obrigatório sem simulationPublicId.

dueDatestring · dateOpcional

Data de vencimento da primeira parcela. Obrigatório sem simulationPublicId. Não pode ser no passado.

proposalNumberstring · máx: 20Opcional

Número da proposta do leilão Dataprev (formato GT-{prefixo}-{único}, ex. GT-XX-7K3F9Q2M1ZX4AB). Opcional; informado apenas quando a proposta materializa uma oferta de leilão vencida, para amarrar a averbação à oferta original. Precisa ser uma oferta do próprio originador, para o mesmo trabalhador (CPF), da solicitationId quando informada, e ainda não convertida em contrato; caso contrário 422 com properties.errorCode = AUCTION_OFFER_NOT_FOUND. Vazio equivale a ausente.

solicitationIdinteger · int64Opcional

Identificador Dataprev da solicitação de leilão (idSolicitacaoProposta) que originou esta proposta — o mesmo valor recebido no redirect de aceite. Opcional; presente apenas no fluxo de leilão.

hasWarrantybooleanOpcional

Indica se a proposta carrega garantia FGTS. Opcional; quando true, os campos warranty* são propagados para a averbação Dataprev.

warrantyFgtsBalancenumber · decimalOpcional

Saldo disponível de garantia FGTS em reais. Opcional (fluxo de leilão com garantia).

warrantyFgtsPenaltynumber · decimalOpcional

Multa rescisória da garantia FGTS em reais. Opcional (fluxo de leilão com garantia).

warrantySeverancePercentagenumber · decimal · máx: 35Opcional

Percentual da verba rescisória dado em garantia. Opcional (fluxo de leilão com garantia).

Respostas
201

Proposta criada com sucesso

application/json
publicIdstringOpcional

Identificador público (16 caracteres Base64 URL-safe). Ex. Kj8mP2xQ9nR4sT6v

Example: Kj8mP2xQ9nR4sT6v
employeePublicIdstring · anulávelOpcional

Identificador público opaco do employee (16 caracteres Base64 URL-safe). Pode vir ausente em registros antigos.

Example: Kj8mP2xQ9nR4sT6v
simulationPublicIdstring · uuid · anulávelOpcional

Identificador público opaco da simulação de referência, quando houver.

Example: 0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b05
loanAmountnumber · decimalOpcional

Valor do empréstimo em reais (decimal com 2 casas decimais).

Example: 5750
financedAmountnumber · decimalOpcional

Valor financiado em reais (decimal com 2 casas decimais).

Example: 5935.64
totalInterestAmountnumber · decimalOpcional

Juros totais em reais (decimal com 2 casas decimais).

Example: 1189.72
debitAmountnumber · decimalOpcional

Total repayment amount (installmentCount × installmentAmount) in reais (decimal with 2 decimal places).

Example: 7125.36
monthlyInterestRatenumber · decimalOpcional

Taxa mensal em percentual (decimal com 4 casas decimais).

Example: 1.97
annualInterestRatenumber · decimalOpcional

Taxa de juros anual em percentual (snapshot da proposta).

Example: 33.18
monthlyEffectiveCostnumber · decimalOpcional

CET mensal em percentual (decimal com 4 casas decimais).

Example: 2.43
annualEffectiveCostnumber · decimalOpcional

CET anual em percentual (decimal com 4 casas decimais).

Example: 33.18
disbursementAmountnumber · decimalOpcional

Valor a desembolsar em reais (decimal com 2 casas decimais).

Example: 5627.78
insuranceAmountnumber · decimalOpcional

Seguro em reais (decimal com 2 casas decimais).

Example: 87.3
iofAmountnumber · decimalOpcional

IOF em reais (decimal com 2 casas decimais).

Example: 63.42
tacAmountnumber · decimalOpcional

TAC em reais. Sempre 0; valor diferente responde 400 TAC_NOT_ALLOWED.

Example: 0
outstandingBalancenumber · decimalOpcional

Saldo devedor em reais (decimal com 2 casas decimais).

Example: 7125.36
installmentCountintegerOpcionalExample: 12
dueDatestring · dateOpcionalExample: 2024-04-28
statusstring · enumOpcional

Status da proposta.

ValorSignificado
PENDINGAguardando aceite do trabalhador
ACCEPTEDAceita pelo trabalhador
REJECTEDRejeitada pelo trabalhador
EXPIREDExpirada (prazo de aceite)
CONVERTED_TO_CONTRACTConvertida em contrato
Example: PENDINGValores possíveis:
expiresAtstring · date-timeOpcionalExample: 2024-02-08T10:00:00Z
acceptedAtstring · date-timeOpcional
createdDatestring · date-timeOpcionalExample: 2024-02-01T10:00:00Z
post/api/v1/originator/employees/{publicId}/proposals
POST /api/v1/originator/employees/{publicId}/proposals HTTP/1.1
Host: ingress.gtpayroll.staging.giro.tech
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "simulationPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b05",
  "employmentRelationshipPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02"
}
{
  "publicId": "Kj8mP2xQ9nR4sT6v",
  "employeePublicId": "Kj8mP2xQ9nR4sT6v",
  "simulationPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b05",
  "loanAmount": 5750,
  "financedAmount": 5935.64,
  "totalInterestAmount": 1189.72,
  "monthlyInterestRate": 1.97,
  "annualInterestRate": 33.18,
  "monthlyEffectiveCost": 2.43,
  "annualEffectiveCost": 33.18,
  "disbursementAmount": 5627.78,
  "insuranceAmount": 87.3,
  "iofAmount": 63.42,
  "tacAmount": 0,
  "outstandingBalance": 7125.36,
  "installmentCount": 12,
  "dueDate": "2024-04-28",
  "status": "PENDING",
  "expiresAt": "2024-02-08T10:00:00Z",
  "installments": [
    {
      "installmentNumber": 1,
      "dueDate": "2024-04-28",
      "installmentAmount": 593.78,
      "amortizationAmount": 481.46,
      "interestAmount": 112.32,
      "iofAmount": 15.9,
      "feesAmount": 0,
      "outstandingBalance": 6531.58,
      "daysToCompensate": 30
    }
  ],
  "createdDate": "2024-02-01T10:00:00Z"
}

Atualizado