Fluxo completo: da consulta à liberação

Este guia percorre uma operação inteira, com o request e a resposta de cada passo. É o caminho feliz usando assinatura via Socinal (D4Sign) — o fluxo padrão.

Parceiro que assina no próprio ambiente usa a Assinatura externa, que tem duas variantes: agrupada (CCB + selfie + frente/verso juntos em POST /{id}/documentos, antes de averbar) e diferida (averba sem documento nenhum, desembolsa e devolve o pacote assinado depois em POST /{id}/documentos-dataprev, com prazo de 5 dias a partir da averbação).

Autentique


curl -X POST https://econsignado-api.socinal.com.br/v1/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{ "grant_type": "client_credentials", "client_id": "cli_...", "client_secret": "sk_..." }'

Use o access_token retornado como Authorization: Bearer ... nos passos seguintes.

Receba a autorização do trabalhador

Antes de consultar a margem, o trabalhador precisa autorizar a consulta (LGPD). Gere a autorização e entregue o link a ele:


curl -X POST https://econsignado-api.socinal.com.br/v1/margem/autorizacao \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "cpf": "93871045675", "nome": "João da Silva", "telefone": "81999990000" }'


{
  "link": "https://app.socinal.com.br/autorizar/<token>",
  "expira_em": "2026-06-14T02:59:59.999Z",
  "status": "pendente"
}

Entregue o link como preferir (seu app, WhatsApp, e-mail). Quando o trabalhador aceitar, a autorização passa a autorizado e a consulta de margem fica liberada. Confira o status quando precisar:


curl 'https://econsignado-api.socinal.com.br/v1/margem/autorizacao?cpf=93871045675' \
  -H 'Authorization: Bearer SEU_TOKEN'

Se você captura o aceite no seu próprio ambiente, registre-o via POST /v1/margem/autorizacao/aceite (sem link prévio). Já no fluxo do link, assine o webhook autorizacao.confirmada para saber quando o trabalhador aceita. Detalhes em Autorização do trabalhador.

Liste os vínculos do trabalhador


curl 'https://econsignado-api.socinal.com.br/v1/margem/vinculos?cpf=93871045675' \
  -H 'Authorization: Bearer SEU_TOKEN'

Escolha o empregador para o qual vai apurar a margem.

Consulte a margem


curl -X POST https://econsignado-api.socinal.com.br/v1/margem/consulta \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "cpf": "93871045675",
    "matricula": "MAT-5646996721",
    "codigo_inscricao_empregador": 1,
    "numero_inscricao_empregador": "12674953000114"
  }'

codigo_inscricao_empregador é o tipo de inscrição do empregador: 1 = CNPJ, 2 = CPF. Envie numero_inscricao_empregador como string, exatamente como veio em GET /v1/margem/vinculos — o CNPJ pode ser alfanumérico (IN RFB 2.229/2024, ex.: R7ZW4H8H000140) e zeros à esquerda são significativos. Por padrão a consulta reusa o resultado salvo quando há um recente; envie "skip_cache": true para pular o cache de banco e consultar a Dataprev novamente (gera cobrança).

A resposta traz os dados completos do trabalhador (os mesmos que a Socinal apura no Dataprev), normalizados — incluindo alertas e emprestimos_legados. Abaixo um recorte dos principais campos:


{
  "nome": "João da Silva",
  "cpf": "93871045675",
  "matricula": "MAT-5646996721",
  "nome_empregador": "Alves Teixeira - EI",
  "cbo": { "codigo": 357105, "descricao": "AGENTE DE VIAGEM" },
  "valor_total_vencimentos": 3559.35,
  "valor_base_margem": 2959.0,
  "valor_margem_disponivel": 1035.65,
  "data_admissao": "2016-10-28",
  "elegivel": true,
  "alertas": [],
  "emprestimos_legados": [],
  "consulta_margem_id": "6a450285-8ae3-4419-8335-0565f82d2d47"
}

A consulta completa (com todos os campos) está na Referência → Consultar margem. Guarde o consulta_margem_id — ele amarra os próximos passos a esta apuração.

(Opcional) Simule condições

Como já consultamos a margem, use POST /v1/simulacao/margem (com cpf + cnpj_empregador) para que cada cenário traga excede_margem. Se quiser apenas os números, sem avaliar margem, use POST /v1/simulacao (sem CPF/CNPJ).


curl -X POST https://econsignado-api.socinal.com.br/v1/simulacao/margem \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "cpf": "93871045675",
    "cnpj_empregador": "12674953000114",
    "numero_linha": "92",
    "valor": 1000,
    "prazos": [10, 12, 18]
  }'


{
  "resultados": [
    { "prazo": 12, "parcela_valor": 94.56, "total_a_pagar": 1134.72,
      "cet_anual": 28.32, "iof": 17.86, "taxa_mensal": 1.79, "excede_margem": false }
  ]
}

Emita o empréstimo (CCB)

Exige Idempotency-Key. Envie os dados do trabalhador, os dados bancários, o bloco dados_documento e a referência consulta_margem_id.


curl -X POST https://econsignado-api.socinal.com.br/v1/emprestimos \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Idempotency-Key: 1f0c...-emp-1' \
  -H 'Content-Type: application/json' \
  -d '{
    "cpf_trabalhador": "93871045675",
    "nome_trabalhador": "João Alves Teixeira",
    "data_nascimento_trabalhador": "1985-03-22",
    "telefone_trabalhador": "11999990000",
    "email_trabalhador": "joao@email.com",
    "cnpj_empregador": "12674953000114",
    "nome_empregador": "Alves Teixeira - EI",
    "matricula": "MAT-5646996721",
    "salario_bruto": 3559.35,
    "margem": 1035.65,
    "numero_linha": "92",
    "consulta_margem_id": "6a450285-8ae3-4419-8335-0565f82d2d47",
    "valor_liberado": 1000,
    "prazo": 12,
    "taxa_mensal": 1.79,
    "iof": 17.86,
    "data_liberacao": "2026-08-03",
    "banco_codigo": "001",
    "agencia": "1234",
    "conta": "56789-0",
    "tipo_conta": "corrente",
    "chave_pix": "93871045675",
    "dados_documento": {
      "nome_mae": "Maria Alves Teixeira",
      "genero": "M",
      "endereco": {
        "cep": "50030230",
        "logradouro": "Rua do Sol",
        "numero": "120",
        "bairro": "Santo Antônio",
        "cidade": "Recife",
        "uf": "PE"
      }
    }
  }'


{ "id": "emp_77aa...", "numero": "A000123-001", "status": "em_assinatura",
  "proxima_acao": "enviar_assinatura" }

201 é o caminho normal — e existe um 202. Se o sistema de liquidação da Socinal não confirmar a proposta dentro da requisição (timeout, indisponibilidade momentânea), a emissão responde 202 com o empréstimo já criado e endereçável:


{ "emprestimo_id": "emp_77aa...", "status": "emitindo",
  "proxima_acao": "aguardar_emissao" }

Nesse caso: aguarde, não reemita. Repetir com a mesma Idempotency-Key devolve o mesmo 202. O desfecho chega pelo webhook emprestimo.emitido (a CCB vira em_assinatura e traz o número definitivo) ou emprestimo.emissao_falhou (o empréstimo é cancelado — aí sim reemita, com uma chave nova). Detalhes em Ciclo de vida → Emissão em andamento.

Três detalhes que costumam gerar 400 ERRO_VALIDACAO aqui:

o campo do valor é valor_liberado (não valor, como na simulação);
nome_trabalhador, data_liberacao e o bloco dados_documento (com nome_mae, genero e endereco completo) são obrigatórios;
dentro de dados_documento, os dados de RG são opcionais — mas se você informar rg, orgao_expedidor ou uf_emissor, então data_emissao_doc passa a ser obrigatória.

iof é opcional: informe o da simulação para precisão; omitido, o servidor estima. A lista completa e autoritativa dos campos está na referência de POST /v1/emprestimos.

Envie para assinatura


curl -X POST https://econsignado-api.socinal.com.br/v1/emprestimos/emp_77aa.../assinatura \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "metodo_auth": "whatsapp" }'


{ "recebido": true, "status": "em_assinatura" }

Responde 202 — o envio é assíncrono. Você recebe o webhook assinatura.concluida quando o trabalhador assinar. Nesse fluxo, a averbação dispara automaticamente após a validação.

Desembolse

Quando o empréstimo estiver averbada, libere o PIX. Exige Idempotency-Key.


curl -X POST https://econsignado-api.socinal.com.br/v1/emprestimos/emp_77aa.../desembolso \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Idempotency-Key: 1f0c...-desemb-1'

Responde 202 com o empréstimo em desembolso_agendado: a liquidação é assíncrona — confirme pelo webhook desembolso.liquidado.

Além do empréstimo em averbada, o desembolso depende de cadastros feitos pela Socinal (conta corrente da linha de crédito e registro da CCB no sistema de liquidação). Se algum faltar, a resposta é 503 OPERACAO_NAO_PROVISIONADA — veja Desembolso (PIX).

Resumo das chamadas

#	Passo	Endpoint	Escopo	Idempotência
1	Token	`POST /v1/oauth/token`	—	—
2	Autorização	`POST /v1/margem/autorizacao`	`margem:read`	—
3	Vínculos	`GET /v1/margem/vinculos`	`margem:read`	—
4	Margem	`POST /v1/margem/consulta`	`margem:read`	—
5	Simulação	`POST /v1/simulacao` (ou `/v1/simulacao/margem`)	`simulacao:read`	—
6	Emitir CCB	`POST /v1/emprestimos`	`emprestimos:write`	✅
7	Assinatura	`POST /v1/emprestimos/{id}/assinatura`	`emprestimos:write`	—
8	Desembolso	`POST /v1/emprestimos/{id}/desembolso`	`desembolso:write`	✅

Os passos 7 e 8 são assíncronos e respondem 202 — o desfecho chega por webhook. Aceite qualquer 2xx como sucesso (ver Ciclo de vida → Síncrono vs. assíncrono).

Acompanhando a carteira

GET /v1/emprestimos lista os empréstimos do parceiro, 20 por página (page, 1-based). Por default a resposta é o array puro de empréstimos. Se você preferir saber em que página está, peça o envelope com paginado=true:


curl 'https://econsignado-api.socinal.com.br/v1/emprestimos?status=averbada&paginado=true' \
  -H 'Authorization: Bearer SEU_TOKEN'


{
  "dados": [ { "id": "emp_77aa...", "status": "averbada", "proxima_acao": "desembolsar" } ],
  "paginacao": { "pagina": 1, "itens_por_pagina": 20, "itens_retornados": 1,
    "tem_proxima_pagina": false }
}

O formato é escolhido só por paginado: sem ele — com ou sem page — a resposta continua sendo o array puro, exatamente como antes. Itere até tem_proxima_pagina: false (ou, no array puro, até a página voltar com menos de 20 itens).

Os nomes dos campos e os formatos exatos de cada request/response estão na Referência API, gerada a partir do próprio código.