Comece por aqui

Este é o seu ponto de partida para integrar a API B2B da Socinal — crédito consignado do trabalhador de ponta a ponta, da consulta de margem à liberação do dinheiro. A integração é server-to-server, autenticada via OAuth2 e versionada sob o prefixo /v1.

URLs para realizar as chamadas

Autenticação

Toda requisição usa um token JWT no header Authorization: Bearer <token>. O token carrega o parceiro_id e os escopos da sua credencial, e expira em 10 minutos (sem refresh).

Como obter o token?

Troque suas credenciais (client_id + client_secret) por um token no endpoint POST /v1/oauth/token:

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

Idempotência

Os POST que criam recurso ou movem dinheiro exigem o header Idempotency-Key. Reenviar a mesma chave retorna a resposta original (X-Idempotency-Replayed: true), sem reexecutar — seguro para retries.

Rate limiting

O limite é por credencial. Ao exceder, a API responde 429 com o header Retry-After indicando quando tentar de novo.

Envelope de erro

Erros seguem o formato { "error": { "code", "message", "details?" } }, com um code estável por tipo de falha (ex.: CREDENCIAL_INVALIDA, ESCOPO_INSUFICIENTE, MARGEM_INSUFICIENTE).

Suporte e Ajuda

Em caso de dúvidas durante a integração, fale com o nosso time de integração pelos canais combinados no onboarding do parceiro.