Visão geral

A API da Socinal expõe uma borda /v1 curada e estável: um conjunto enxuto de endpoints orientados a caso de uso, que orquestram internamente todo o processo de crédito consignado. Você não chama os passos crus do nosso wizard — chama endpoints “grossos” que fazem o trabalho pesado.

Divisão de responsabilidades

Você (parceiro)	Socinal (a API)
Relacionamento e experiência com o trabalhador	Consulta de margem no Dataprev
Coleta do consentimento (autorização)	Cálculo de condições (simulação, CET, IOF)
Decisão comercial de ofertar o crédito	Emissão da CCB e assinatura digital
Orquestração das chamadas na ordem certa	Averbação e desembolso via PIX

Ambientes

Ambiente	URL base
Produção	`https://api.socinal.com.br`
Desenvolvimento local	`http://localhost:3101`

Todos os caminhos desta documentação são relativos à URL base e começam com /v1. Por exemplo: POST https://api.socinal.com.br/v1/oauth/token.

Blocos da integração

Autenticação — OAuth2 client_credentials. Você troca client_id + client_secret por um token de acesso curto e o envia em todas as chamadas. Veja Autenticação.
Escopos — cada credencial carrega permissões granulares (margem:read, emprestimos:write, desembolso:write…). Verbos que mexem em dinheiro exigem escopos dedicados.
Idempotência — POST que criam recurso ou movem dinheiro exigem o header Idempotency-Key, para que retries não dupliquem operações. Veja Idempotência.
Webhooks — em vez de ficar consultando, cadastre URLs e receba eventos assinados quando algo assíncrono concluir. Veja Webhooks.
Erros — todas as respostas de erro seguem o mesmo envelope { "error": { "code", "message", "details?" } }. Veja Tratamento de erros.

Próximo passo

Configure sua credencial e gere o primeiro token em Autenticação.