Autenticação

A API usa OAuth2 no fluxo client_credentials — o padrão de mercado para integração máquina-a-máquina. Você troca suas credenciais por um token de acesso de curta duração e o envia em toda requisição.

Como obter credenciais

Suas credenciais (client_id e client_secret) são emitidas pela Socinal e amarradas ao seu parceiro_id. O client_secret é exibido uma única vez no momento da criação — guarde-o em local seguro. Para rotacionar, gere uma nova credencial, migre e revogue a antiga.

Nunca exponha o client_secret no front-end ou em apps cliente. Ele vive apenas no seu backend.

Trocando credenciais por um token

Solicite o token


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

Receba o `access_token`


{
  "access_token": "eyJhbGciOiJ...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "margem:read emprestimos:read emprestimos:write"
}

O access_token é um JWT curto e sem refresh — ele carrega o seu parceiro_id e os escopos da credencial. Respeite o campo expires_in (em segundos) e solicite um novo token quando o atual expirar.

Use o token em todas as chamadas


curl https://api.socinal.com.br/v1/linhas-credito \
  -H 'Authorization: Bearer eyJhbGciOiJ...'

Escopos

Cada credencial carrega um conjunto de escopos. Uma chamada sem o escopo necessário retorna 403 ESCOPO_INSUFICIENTE.

Escopo	Permite
`margem:read`	Consultar margem e vínculos no Dataprev
`simulacao:read`	Simular condições de crédito
`credito:read`	Listar linhas de crédito ativas
`emprestimos:read` / `emprestimos:write`	Ler / criar e operar empréstimos
`documentos:read`	Baixar CCB e evidências de assinatura
`documentos:write`	Devolver pacote assinado externamente
`desembolso:write`	Mover dinheiro (PIX) — concedido com cautela
`webhooks:read` / `webhooks:write`	Listar / cadastrar e remover webhooks

A granularidade é proposital: um parceiro pode ter emprestimos:write mas não desembolso:write — ele origina a operação, e a Socinal libera o crédito.

Erros de autenticação

HTTP	`code`	Significado
401	`CREDENCIAL_INVALIDA`	Token ausente, inválido ou expirado
403	`ESCOPO_INSUFICIENTE`	A credencial não tem o escopo exigido pela rota
429	`RATE_LIMIT_EXCEDIDO`	Limite por credencial excedido — respeite o `Retry-After`