Criar Proposta
Cria uma proposta de empréstimo para um trabalhador, em um de dois modos:
Com
simulationPublicId: bastasimulationPublicId+employmentRelationshipPublicId. Valores e parcelas vêm da simulação, que precisa estar emEPHEMERALe passa aCONVERTED_TO_PROPOSAL.Sem
simulationPublicId: todos os campos financeiros einstallmentssã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
publicId
path
string
Sim
Identificador público do employee
Corpo
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
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.
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
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.
Cria uma nova proposta de empréstimo. Dois modos de criação:
Com simulationPublicId: apenas o identificador da simulação +
employmentRelationshipPublicIdsão necessários. Dados financeiros e parcelas são derivados automaticamente da simulação.Sem identificador de simulação: todos os campos financeiros e
installmentssão obrigatórios.
JWT token fornecido pelo administrador
Identificador público do employee (16 caracteres)
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.
Cria uma proposta de empréstimo. Dois modos de criação:
- Com simulationPublicId: apenas
simulationPublicId+employmentRelationshipPublicIdsã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
installmentssão obrigatórios.
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.
0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b05Identificador público opaco do vínculo empregatício.
0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02Valor do empréstimo em reais. Obrigatório sem simulationPublicId.
Valor financiado em reais. Obrigatório sem simulationPublicId.
Juros totais em reais. Obrigatório sem simulationPublicId.
Taxa de juros mensal em percentual. Obrigatório sem simulationPublicId.
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.
CET mensal em percentual. Obrigatório sem simulationPublicId.
CET anual em percentual. Obrigatório sem simulationPublicId.
Valor a desembolsar em reais. Obrigatório sem simulationPublicId.
Valor do seguro em reais. Obrigatório sem simulationPublicId.
IOF em reais. Obrigatório sem simulationPublicId.
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".
Número de parcelas. Obrigatório sem simulationPublicId.
Data de vencimento da primeira parcela. Obrigatório sem simulationPublicId. Não pode ser no passado.
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.
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.
Indica se a proposta carrega garantia FGTS. Opcional; quando true, os campos warranty* são propagados para a averbação Dataprev.
Saldo disponível de garantia FGTS em reais. Opcional (fluxo de leilão com garantia).
Multa rescisória da garantia FGTS em reais. Opcional (fluxo de leilão com garantia).
Percentual da verba rescisória dado em garantia. Opcional (fluxo de leilão com garantia).
Proposta criada com sucesso
Identificador público (16 caracteres Base64 URL-safe). Ex. Kj8mP2xQ9nR4sT6v
Kj8mP2xQ9nR4sT6vIdentificador público opaco do employee (16 caracteres Base64 URL-safe). Pode vir ausente em registros antigos.
Kj8mP2xQ9nR4sT6vIdentificador público opaco da simulação de referência, quando houver.
0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b05Valor do empréstimo em reais (decimal com 2 casas decimais).
5750Valor financiado em reais (decimal com 2 casas decimais).
5935.64Juros totais em reais (decimal com 2 casas decimais).
1189.72Total repayment amount (installmentCount × installmentAmount) in reais (decimal with 2 decimal places).
7125.36Taxa mensal em percentual (decimal com 4 casas decimais).
1.97Taxa de juros anual em percentual (snapshot da proposta).
33.18CET mensal em percentual (decimal com 4 casas decimais).
2.43CET anual em percentual (decimal com 4 casas decimais).
33.18Valor a desembolsar em reais (decimal com 2 casas decimais).
5627.78Seguro em reais (decimal com 2 casas decimais).
87.3IOF em reais (decimal com 2 casas decimais).
63.42TAC em reais. Sempre 0; valor diferente responde 400 TAC_NOT_ALLOWED.
0Saldo devedor em reais (decimal com 2 casas decimais).
7125.36122024-04-28Status da proposta.
| Valor | Significado |
|---|---|
| PENDING | Aguardando aceite do trabalhador |
| ACCEPTED | Aceita pelo trabalhador |
| REJECTED | Rejeitada pelo trabalhador |
| EXPIRED | Expirada (prazo de aceite) |
| CONVERTED_TO_CONTRACT | Convertida em contrato |
PENDINGValores possíveis: 2024-02-08T10:00:00Z2024-02-01T10:00:00ZDados inválidos, corpo ilegível, regra de negócio ou CET acima do teto.
Não autenticado
Permissão insuficiente
Employee não encontrado ou de outro originador.
Simulação antiga com TAC, ou mesma Idempotency-Key ainda em processamento.
Cobertura de garantia fora da regra, ou proposalNumber que não é oferta de leilão sua.
Mais de 75 requisições por segundo. Aguarde o header Retry-After e reenvie com nova Idempotency-Key — com a mesma chave, o 429 gravado é repetido.
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