Leilão

A API de Leilão da Socinal permite consultar as solicitações de leilão em aberto, enviar propostas e acompanhar o resultado. O resultado é assíncrono. Você envia sua solicitação e recebe o resultado por webhook. Ou pode consultar o status a qualquer momento.

Todos os endpoints são versionados sob o prefixo /v1 e exigem Authorization: Bearer <token>. A referência completa está em Referência API → Leilão.

Autenticação

Use o mesmo token das demais APIs da Socinal. O token é sempre emitido pelo backoffice (o provedor de autenticação): faça o POST /v1/oauth/token na URL da API Backoffice (https://econsignado-api.socinal.com.br), mesmo que as outras chamadas sejam na API de Leilão. O mesmo token serve as duas. A identidade do parceiro vem do próprio token (nunca do corpo da requisição).

Escopos

Sem token válido: 401. Token sem o escopo exigido pelo endpoint: 403.

Fluxo de ponta a ponta

1. POST /v1/oauth/token → token com escopos leilao:*.
2. GET /v1/solicitacoes → lista paginada das solicitações de leilão em aberto (janela por dataHoraInicio / dataHoraFim em ISO 8601).
3. POST /v1/propostas → envia uma ou mais propostas. Modelo assíncrono: a resposta é só o aviso de recebimento (recebido: true); o resultado (confirmada/recusada) chega por webhook.
4. GET /v1/solicitacoes/{id}/status → consulta o status atual de uma proposta enviada (PropostaDto + mensagemStatus).
5. GET /v1/propostas e GET /v1/propostas/{id} → consultam as propostas que você enviou.

Status das propostas

O campo statusSocinal reflete o status recebido (normalizado para MAIÚSCULAS). O status resume o ciclo da proposta (enviada → resultado do webhook). Os campos suaPontuacao e pontuacaoVencedora mostram a colocação da proposta no leilão quando o resultado sai.

Webhook de status

O resultado da proposta chega de forma assíncrona por webhook: você cadastra uma URL HTTPS e a Socinal faz um POST nela sempre que o status de uma proposta muda (por exemplo, de ENVIADA para CONFIRMADA ou RECUSADA).

Cadastro

O cadastro é self-service, pela própria API:

• POST /v1/webhooks → cadastra a URL e retorna o secret (exibido só nessa resposta — guarde-o).
• GET /v1/webhooks → lista os webhooks ativos (sem o secret).
• DELETE /v1/webhooks/{id} → remove um webhook.

Segurança (validação da assinatura)

Cada entrega é assinada com HMAC-SHA256 do corpo bruto usando o secret do cadastro, no header X-Webhook-Signature. O header X-Webhook-Event traz o nome do evento.

X-Webhook-Event: proposta.atualizada
X-Webhook-Signature: sha256=<hmac_hex>

Para validar, recompute o HMAC do corpo recebido e compare (comparação em tempo constante). Rejeite se não bater — é o que garante que a chamada veio da Socinal.

import { createHmac, timingSafeEqual } from 'node:crypto';
 
const assinado = createHmac('sha256', SEU_SECRET).update(rawBody).digest('hex');
const recebido = req.headers['x-webhook-signature']?.replace('sha256=', '');
const ok =
  recebido &&
  timingSafeEqual(Buffer.from(assinado), Buffer.from(recebido));

Corpo da entrega

O corpo é um envelope: metadados na raiz e a carga do evento em data.

{
  "evento": "proposta.atualizada",
  "timestamp": "2026-07-17T12:00:00.000Z",
  "data": {
    "id": "cmqb...",
    "numero": "LEI-0091",
    "idSolicitacao": "30808607",
    "status": "CONFIRMADA",
    "statusSocinal": "CONFIRMADA",
    "mensagem": "Proposta vencedora.",
    "suaPontuacao": 7,
    "pontuacaoVencedora": 7
  }
}

Resposta esperada e retries

Responda 2xx (ex.: 200) para confirmar o recebimento. Se o seu endpoint falhar (timeout ou status ≥ 400), a entrega é reprocessada com backoff exponencial (até 5 tentativas). Trate duplicatas sem efeito colateral (idempotência), pois um reenvio pode repetir o mesmo evento.