Repasses e Vínculos

Estes endpoints dão ao parceiro visibilidade, por API, de dois assuntos das suas CCBs: se a Socinal já repassou os pagamentos (repasses) e o que aconteceu com o vínculo empregatício do trabalhador (desligamento ou novo emprego). Há ainda um endpoint de escrituração reservado, ainda em definição.

Todos são somente-leitura, versionados sob /v1 e exigem Authorization: Bearer <token>. Cada resposta é filtrada para as suas próprias CCBs — você nunca vê contrato de outro parceiro.

Autenticação

Use o mesmo token das demais APIs da Socinal, emitido pelo backoffice: POST /v1/oauth/token. A identidade do parceiro vem do próprio token — você nunca informa parceiro_id.

Escopos

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

Janela de datas

Repasses e vínculos aceitam uma janela opcional via data_inicio e data_fim (formato YYYY-MM-DD). Quando omitidas, o backend usa uma janela padrão (repasses: últimos 90 dias; vínculos: últimos 30 dias) terminando hoje. Consultas sem registros retornam a lista vazia (200), não erro.

Repasses

GET /v1/repasses lista os pagamentos das suas CCBs no período. Cada item traz contrato (número da CCB), competencia, valor_parcela_paga e as datas do fluxo. O campo repassado resume o que interessa: true quando a instituição financeira já efetuou o repasse (há data_repasse_if); false quando o pagamento foi identificado mas o repasse ainda não saiu.

Para consultar uma CCB específica, passe contrato:

GET /v1/repasses?contrato=A100001-001

{
  "repasses": [
    {
      "contrato": "A100001-001",
      "competencia": "202506",
      "valor_parcela_paga": 312.45,
      "numero_guia": 998877,
      "nsu": 4455667,
      "data_pagamento_guia": "2025-06-05T00:00:00.000Z",
      "data_inclusao_dataprev": "2025-06-06T00:00:00.000Z",
      "data_repasse_if": "2025-06-10T00:00:00.000Z",
      "repassado": true
    }
  ]
}

Vínculos

Dois endpoints cobrem as duas pontas do vínculo empregatício do trabalhador.

Desligamentos

GET /v1/vinculos/desligamentos lista os empréstimos das suas CCBs cujo trabalhador foi desligado (contrato encerrado por término de vínculo). Útil para acompanhar risco: o trabalhador perdeu a fonte de averbação. A correlação com o seu parceiro é feita por contrato + CPF.

{
  "desligamentos": [
    {
      "contrato": "A100001-001",
      "cpf_trabalhador": "75842274574",
      "nome_trabalhador": "João da Silva",
      "cnpj_empregador": "12674953000114",
      "nome_empregador": "Alves Teixeira - EI",
      "data_desligamento": "2025-05-30",
      "motivo_desligamento": { "codigo": 2, "descricao": "Dispensa sem justa causa" },
      "situacao_emprestimo": { "codigo": 15, "descricao": "Encerrado por término do vínculo" },
      "total_parcelas": 24,
      "valor_parcela": 312.45,
      "valor_emprestimo": 6000
    }
  ]
}

Novos vínculos

GET /v1/vinculos/novos lista novos vínculos empregatícios de trabalhadores que têm empréstimo com você — candidatos a averbar o saldo pendente no novo emprego. A correlação é por CPF contra os empréstimos do seu parceiro. Traz a margem_disponivel e a elegibilidade no novo vínculo.

{
  "vinculos": [
    {
      "cpf_trabalhador": "75842274574",
      "nome_trabalhador": "João da Silva",
      "cnpj_empregador": "98765432000199",
      "nome_empregador": "Nova Empresa LTDA",
      "data_admissao": "2025-06-15",
      "elegivel": true,
      "valor_margem_disponivel": 800,
      "qtd_emprestimos": 0
    }
  ]
}

Escrituração

GET /v1/escrituracao (escopo escrituracao:read) lista as escriturações do eSocial — os descontos de parcela efetivamente registrados — dos trabalhadores das suas CCBs no período. É a visão “o desconto foi lançado na folha”, complementar aos repasses (“o dinheiro chegou”).

Aceita data_inicio/data_fim (janela padrão: últimos 90 dias) e contrato para restringir a uma CCB específica. Um contrato que não seja seu retorna 404. Sem registros, retorna { "escrituracoes": [] }.

curl 'https://econsignado-api.socinal.com.br/v1/escrituracao?contrato=A000123-001' \
  -H 'Authorization: Bearer SEU_TOKEN'

{
  "escrituracoes": [
    {
      "contrato": "A000123-001",
      "cpf_trabalhador": "93871045675",
      "periodo_referencia": "202607",
      "valor_parcela_desconto": 94.56,
      "excluido": false,
      "retificado": false
    }
  ]
}

Cada item traz ainda matricula, inscricao_empregador, numero_inscricao_empregador, data_inclusao_dataprev, tipo_evento_esocial e o bloco analise (conferência do eSocial). Os campos excluido/retificado sinalizam eventos posteriores do eSocial sobre o mesmo desconto — a forma completa está na referência.