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. Para a variação em que o parceiro assina, veja Assinatura externa.

Autentique


curl -X POST https://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://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://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 PUT /v1/margem/autorizacao/{token}/aceite. Detalhes em Autorização do trabalhador.

Liste os vínculos do trabalhador


curl 'https://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://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. Por padrão a consulta reusa o resultado salvo quando há um recente; envie "skipCache": true para pular o cache de banco e consultar a Dataprev novamente (gera cobrança).


{
  "nome": "João da Silva",
  "salario_bruto": 3559.35,
  "margem_disponivel": 1035.65,
  "ja_comprometido": 1923.35,
  "cnpj_empregador": "12674953000114",
  "nome_empregador": "Alves Teixeira - EI",
  "consulta_margem_id": "6a450285-8ae3-4419-8335-0565f82d2d47"
}

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://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 bancários e a referência consulta_margem_id.


curl -X POST https://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",
    "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": 1000,
    "prazo": 12,
    "taxa_mensal": 1.79,
    "banco_codigo": "001",
    "agencia": "1234",
    "conta": "56789-0",
    "tipo_conta": "corrente",
    "chave_pix": "93871045675"
  }'


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

Envie para assinatura


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


{ "enfileirado": true }

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://api.socinal.com.br/v1/emprestimos/emp_77aa.../desembolso \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Idempotency-Key: 1f0c...-desemb-1'

A liquidação é assíncrona — confirme pelo webhook desembolso.liquidado.

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 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.