API Docs Início Documentação Referência de API Copiar para LLM
Comece aqui

Convenções de dados

Um lugar só para as três perguntas que aparecem em todo campo: que formato de data é esse, esse valor é em centavos e essa taxa é ao mês ou ao ano.

As tabelas de campo de toda a documentação usam os rótulos definidos aqui. Quando uma tabela diz data civil ou inteiro em centavos, o significado é exatamente o desta página — não há variação por produto nem por endpoint.

Por que isso existe. Errar a unidade não devolve 400: devolve uma operação com valor cem vezes maior, ou com a primeira parcela no mês errado. É o tipo de erro que passa pela validação e aparece na liquidação. Ler esta página uma vez economiza esse retrabalho.

Datas

Três tipos, e o rótulo na tabela de campos diz qual é. Nenhum campo de data aceita formato brasileiro (DD/MM/AAAA).

Rótulo na tabela Formato aceito Tem hora? Timezone Exemplo válido
data civil AAAA-MM-DD Não Não se aplica 1990-01-01
data e hora AAAA-MM-DDTHH:MM:SSZ Sim UTC — sempre com o sufixo Z 2026-08-25T14:30:00Z
competência AAAA-MM-DD Não Não se aplica 2026-10-01

data civil — um dia do calendário

Um dia, sem hora e sem fuso: data de nascimento, data de admissão, data de emissão de documento. Não existe "meia-noite de onde" nesses campos — eles não representam um instante, representam uma data.

Envie AAAA-MM-DD. A API também aceita esses campos no formato de data e hora, e nesse caso a parte de hora é ignorada — mas mandar AAAA-MM-DD deixa a intenção explícita e evita a dúvida de fuso.

{ "birthDate": "1990-01-01", "admissionDate": "2022-03-01" }

data e hora — um instante

Um momento no tempo: quando o titular aceitou o termo, quando o documento foi assinado, quando a operação foi emitida. Aqui o fuso importa, e a convenção é UTC.

Envie sempre com o sufixo Z. Se o seu sistema trabalha em horário de Brasília, converta antes de enviar: 2026-08-25 11:30 em Brasília (UTC−3) é 2026-08-25T14:30:00Z.

{ "acceptanceDate": "2026-08-25T14:30:00Z", "emissionDate": "2026-08-25T00:00:00Z" }

O retorno da API vem no mesmo formato, em UTC. Converta para o fuso do usuário só na exibição — nunca no armazenamento.

Armadilha. Enviar 2026-08-25T14:30:00 sem o Z deixa o instante ambíguo. Enviar 2026-08-25T14:30:00-03:00 funciona, mas gera divergência entre o que você registrou e o que a UY3 exibe. Padronize em UTC com Z.

competência — um mês de referência

Competência não é um dia: é o mês ao qual um evento de folha pertence. O campo mais importante deste tipo é dataprev_DiscountStartPeriod, a competência do primeiro desconto em folha no Consignado privado.

Mesmo sendo um mês, o campo é enviado como data civil completa — dia, mês e ano — e o dia usado é o primeiro dia do mês da competência. Escrever só AAAA-MM não é aceito.

Competência Envie Não envie
Outubro de 2026 2026-10-01 2026-10, 10/2026, 2026-10-31
Janeiro de 2027 2027-01-01 2027-1-1, 01/2027 
{ "dataprev_DiscountStartPeriod": "2026-10-01" }

O dia 01 é convenção de referência, não a data do desconto: o desconto acontece no dia de repasse definido pelo produto contratado, dentro daquele mês. Quem quer saber a data efetiva da primeira parcela usa POST /v1/DataprevEmployee/FirstPaymentDate, não este campo.

Valores monetários

Dois tipos, e a regra para saber qual é depende do nome do campo.

Rótulo na tabela Tipo Como enviar Exemplo Equivale a
inteiro em centavos inteiro Multiplique o valor em reais por 100. Sem ponto, sem vírgula, sem sinal. 500000 R$ 5.000,00
decimal em reais número Reais com até duas casas decimais, separador . (ponto). 6840.00 R$ 6.840,00

Como saber qual é

  1. Nome termina em InCents → é inteiro em centavos. Ex.: installmentAmountInCents, loanAmountInCents, fgtsBalanceInCents, dataprev_WarrantyFgtsBalanceInCents.

Fora da Referência curada: requestedValue, rangePaymentAmounts, monthlyInterestRate, yearlyInterestRate, rescissionBenefitPercentage — campos das rotas do Crédito do Trabalhador, que a Referência de API não publica. A unidade deles está aqui e na página de operação do produto; não há onde conferir no contrato publicado.

  1. Nome não tem sufixo, mas a tabela de campos diz inteiro em centavos → é centavos, e a tabela sempre diz. Os casos que existem hoje nos dois módulos:

    Campo Onde Unidade
    requestedAmount objeto de cálculo, em Consignado privado e FGTS inteiro em centavos
    requestedValue simulação de ofertas, em Consignado privado inteiro em centavos
    rangePaymentAmounts simulação por valor de parcela lista de inteiro em centavos
    invoiceValue nível da operação inteiro em centavos

  2. Todo o resto é decimal em reais. Os campos de garantia e de renda são deste tipo: totalValue, dataprev_OriginalMargin, netSalary, otherIncome.

A armadilha mais comum dos dois módulos. requestedAmount não tem sufixo e é em centavos. totalValue, ao lado dele no mesmo corpo, é em reais. Um pedido de R$ 5.000,00 com garantia de R$ 6.840,00 fica "requestedAmount": 500000 e "totalValue": 6840.00. Se você enviar "requestedAmount": 5000, a operação nasce valendo R$ 50,00 — e passa por todas as validações.

{
  "amortization": { "requestedAmount": 500000 },
  "warranty": [ { "totalValue": 6840.00, "dataprev_WarrantyFgtsBalanceInCents": 150000 } ]
}

Como interpretar o valor retornado

O retorno respeita a mesma regra do request, campo por campo: o que você envia em centavos volta em centavos, o que você envia em reais volta em reais. A API não normaliza tudo para um formato só.

Na exibição, divida por 100 os campos em centavos e formate com duas casas. Nunca armazene o valor já formatado como texto: guarde o inteiro em centavos e formate na borda.

Taxas e percentuais

Campo Significado Exemplo Leia como
apr Taxa de juros ao mês, em porcentagem 2.15 2,15% ao mês
monthlyInterestRate Taxa ao mês, em porcentagem 2.15 2,15% ao mês
yearlyInterestRate Taxa ao ano, em porcentagem 29.07 29,07% ao ano
monthlyCet / yearlyCet Custo Efetivo Total ao mês / ao ano, em porcentagem 2.42 / 33.25 2,42% ao mês / 33,25% ao ano
rescissionBenefitPercentage Percentual, em porcentagem 40.0 40%

Nenhum campo de taxa é fração decimal: 2.15 é 2,15%, nunca 215%. E apr, apesar do nome vir de annual percentage rate, é a taxa mensal nos dois módulos — é o valor que a simulação devolve e o que a faixa do produto contratado limita.

Identificadores e documentos

Rótulo na tabela Formato Exemplo
string (uuid) UUID em minúsculas, com hífens 11111111-1111-1111-1111-111111111111
CPF Só dígitos, 11 posições. A API remove máscara, mas enviar limpo evita ambiguidade. 00000000000
CNPJ Só dígitos, 14 posições. 00000000000000
Telefone DDD + número, só dígitos, sem +55. 11900000000

Nos exemplos desta documentação o CPF aparece mascarado (000.000.000-00) porque exemplo é para ler; no curl ele aparece limpo (00000000000) porque request é para executar.

Enums

Enum é enviado como string, com a grafia exata do contrato, incluindo maiúsculas: EletronicTransfer, não eletronictransfer nem ELETRONIC_TRANSFER. A única exceção documentada é o discriminador amortizationType, comparado sem distinção de caixa — mesmo assim, use minúsculas (price, fgts) para manter os exemplos consistentes.

Toda tabela de campo que tem um enum lista os valores aceitos, com o significado de cada um. Não há enum documentado por lista corrida no meio de um parágrafo.

Dado pessoal

Dado pessoal ou sensível deve ser mascarado em outputs, logs, prints e chamados. Os exemplos desta documentação usam CPF 000.000.000-00, CNPJ 00.000.000/0000-00 e UUID 11111111-1111-1111-1111-111111111111 — todos fictícios.

Orientação técnica. A classificação de quais campos são dado pessoal, a base legal do tratamento e o prazo de retenção são competência do Compliance/Jurídico da UY3 (LGPD, Lei 13.709/2018). Esta página trata de formato, não de enquadramento.

Antes desta etapa

Próxima etapa