Skip to Content
Guias por fluxoMassa de dados (homologação)

Massa de dados (homologação)

Os endpoints sob /v1/massa-dados permitem que você mesmo monte os cenários de teste da integração, populando a base de HOMOLOGAÇÃO da Dataprev com trabalhadores, propostas, contratos, escriturações e repasses fictícios — sem depender do time Socinal para semear a base.

⚠️

Disponível apenas nos ambientes de staging e homologação. Em produção estas rotas não existem: a requisição responde 404 e elas nem aparecem no openapi.json daquele ambiente. Nunca escreva integração de produção que dependa delas.

Autenticação e escopo

Use o mesmo token das demais rotas, emitido por POST /v1/oauth/token. Todos os endpoints de massa exigem o escopo emprestimos:write — o mesmo que já permite criar e operar empréstimos.

Sem token válido: 401. Token sem o escopo: 403.

Convenções

Os corpos seguem o padrão do resto da API: snake_case, CPF como string de 11 dígitos, datas em ISO YYYY-MM-DD, data/hora em ISO 8601 e competência no formato yyyyMM (ex.: "202504"). A tradução para o formato interno da Dataprev (ddMMyyyy, ddMMyyyyHHmmss) é feita pela API.

Campos opcionais que você omitir não são enviados adiante — não mande null esperando que o valor seja ignorado.

tem_garantias é obrigatório nas rotas de solicitação, empréstimo e portabilidade: envie false explicitamente quando a operação não tiver garantia FGTS. O mesmo vale para verbas_rescisorias em /pagamento.

Ordem recomendada

Os registros têm dependência entre si. A sequência abaixo monta um cenário completo, do trabalhador até o repasse:

1. Trabalhador com vínculo e margem

POST /v1/massa-dados/trabalhador é o ponto de partida de qualquer cenário. O CPF criado passa a responder em GET /v1/margem/vinculos e POST /v1/margem/consulta.

{
  "cpf_trabalhador": "87070728050",
  "matricula": "MAT-99999999999999213",
  "codigo_inscricao_empregador": 1,
  "numero_inscricao_empregador": "66106660000160",
  "nome": "Trabalhador Fulano de Tal",
  "data_nascimento": "1990-01-01",
  "data_admissao": "2020-01-01",
  "codigo_categoria_trabalhador": 101,
  "elegivel": true,
  "valor_margem_disponivel": 1050,
  "nome_empregador": "Empresa Tal LTDA"
}

Para montar um cenário de trabalhador desligado (e testar GET /v1/vinculos/desligamentos), informe data_desligamento e codigo_motivo_desligamento.

2. Autorização de saldo FGTS (opcional)

POST /v1/massa-dados/autorizacao-saldo-fgts registra a autorização do trabalhador — pré-requisito de GET /v1/fgts/saldo. Só precisa do CPF.

3. Solicitação de proposta (opcional)

POST /v1/massa-dados/solicitacao-proposta cria o pedido que o trabalhador faz na CTPS Digital e que abre o leilão. A solicitação passa a aparecer em GET /v1/solicitacoes da API de Leilão.

3.1. Proposta pronta para autocontratação (opcional)

POST /v1/massa-dados/proposta-autocontratacao monta o cenário de uma proposta recém-arrematada no leilão e devolve o link da jornada de autocontratação — aquele em que o próprio trabalhador autoriza a consulta de margem, escolhe valor e prazo, preenche o cadastro e emite a CCB. Serve para testar essa jornada sem depender de um leilão real.

Use o mesmo CPF do passo 1: é dele que vêm o vínculo e a margem. E a data_nascimento informada lá é a que o trabalhador precisa digitar no passo de confirmação de identidade — sem ela, não se passa do gate.

Abra a url da resposta no navegador (de preferência no celular: a jornada é desenhada para mobile) e percorra as etapas.

Duas diferenças em relação às outras rotas deste grupo:

  • Não popula a base da Dataprev. A massa aqui é do backoffice (a proposta e a jornada), não do eSocial.
  • A taxa_mensal fica travada: o trabalhador escolhe apenas valor e prazo, sempre dentro da margem real. O leilao_numero (gerado, se omitido) põe a garantia FGTS no canal CTPS Digital.

Reexecutar para o mesmo CPF e linha reaproveita a proposta e o link, em vez de duplicar — os campos proposta_reaproveitada e jornada_reaproveitada na resposta indicam quando isso acontece.

4. Empréstimo já averbado

POST /v1/massa-dados/emprestimo cria um contrato de consignado já averbado, pulando o fluxo de originação — é o atalho para testar refinanciamento, renegociação, portabilidade e repasses. O trabalhador (cpf_trabalhador + matricula) precisa já existir na massa.

{
  "numero_contrato": "199912345678",
  "cpf_trabalhador": "87070728050",
  "matricula": "MAT-99999999999999213",
  "codigo_inscricao_empregador": 1,
  "numero_inscricao_empregador": "66106660000160",
  "data_inicio_contrato": "2020-01-01",
  "data_fim_contrato": "2021-01-01",
  "data_primeiro_desconto": "2020-02-01",
  "numero_parcelas": 10,
  "valor_parcela": 100,
  "valor_emprestimo": 1000,
  "valor_iof": 33.73,
  "valor_liberado": 966.27,
  "valor_taxa_anual": 34.49,
  "valor_cet_anual": 40.9,
  "valor_taxa_mensal": 2.5,
  "valor_cet_mensal": 2.9,
  "codigo_situacao_emprestimo": 1,
  "tem_garantias": false,
  "competencia_inicio_desconto": "202401"
}

Todo campo de taxa da API — valor_taxa_*, valor_cet_*, taxa_mensal, cet_anual, taxa_minima, taxa_maxima — usa percentual (2.5 = 2,5% a.m.), a mesma unidade dos sistemas da Socinal e do Dataprev.

A resposta traz a escrituração da primeira parcela, gerada junto com o contrato.

5. Escrituração e repasse

Com o contrato criado, dois endpoints alimentam as consultas de acompanhamento:

EndpointFaz o contrato aparecer em
POST /v1/massa-dados/escrituracaoGET /v1/escrituracao
POST /v1/massa-dados/pagamentoGET /v1/repasses

Na escrituração, omita numero_contrato_emprestimo quando o desconto se referir ao próprio contrato escriturado — é o caso comum.

Ordem importa para o ciclo ponta a ponta. As consultas /v1/escrituracao e /v1/repasses retornam apenas as suas CCBs — a correlação é por número de contrato + CPF. Um contrato que exista só na massa da Dataprev, sem CCB correspondente, não aparece nelas.

Só que POST /v1/emprestimos não aceita numero_contrato: o número da CCB (formato Axxxxxx-xxx) é gerado pela Socinal na emissão. Portanto o caminho é o inverso do que se poderia supor:

  1. emita a CCB pelo fluxo normal (POST /v1/emprestimos);
  2. leia o numero devolvido na resposta (ex.: A000123-001);
  3. use esse valor como numero_contrato ao criar a massa (POST /v1/massa-dados/emprestimo) e como numero_contrato_escrituracao / numero_contrato nos passos de escrituração e pagamento, sempre com o mesmo CPF.

6. Portabilidade (opcional)

POST /v1/massa-dados/solicitacao-portabilidade abre uma proposta de portabilidade a partir de um contrato existente — crie o contrato antes, no passo 4.

Não há endpoint que consulte portabilidades especificamente. A solicitação criada aqui aparece entre as solicitações de proposta em GET /v1/solicitacoes da API de Leilão, junto com as demais — e o contrato atual daquela rota não publica um campo que permita distinguir uma portabilidade de uma proposta comum. Na prática, correlacione pelo CPF e pelo contrato de origem que você acabou de criar. Estamos tratando isso com o time responsável pela API de Leilão; até lá, planeje seus testes de portabilidade sabendo dessa limitação.

Verificando o ambiente

GET /v1/massa-dados/status é o health check do serviço de massa. Use antes de gerar massa em lote para confirmar que o ambiente de homologação está no ar.

Erros

Os erros seguem o envelope padrão. Além de 401/403, espere:

CódigoQuando
ERRO_VALIDACAO (400)Corpo inválido (CPF fora de 11 dígitos, data fora de YYYY-MM-DD, campo obrigatório ausente).
ERRO_NEGOCIO (422)A Dataprev recusou o registro — a mensagem repassa o motivo original (ex.: trabalhador inexistente, contrato duplicado).
DATAPREV_INDISPONIVEL (502)Serviço de massa fora do ar.
Leilão