Documentação da API de Parceiros.

Introdução#

A API de Parceiros Alethica permite que concessionárias, plataformas de veículos e sistemas de gestão integrem financiamento veicular diretamente em seus fluxos. Submeta solicitações, acompanhe status em tempo real via webhooks e ofereça uma experiência nativa com o widget embarcado.

Base URL

https://api.alethica.co/api/v1

Escopos disponíveis

Autenticação#

A API utiliza OAuth2 com o fluxo client_credentials. Você recebe um client_id e client_secret ao registrar-se como parceiro. Use-os para obter um token JWT com validade de 1 hora.

Aplicações#

O recurso de aplicações permite submeter solicitações de financiamento, consultar status e acompanhar a timeline completa de eventos.

CRM (Negócios)#

Acesse o funil de vendas (CRM “Negócios”) da revenda vinculada ao seu parceiro: liste e gerencie negócios, mova etapas, registre ganho/perda, crie tarefas e inicie financiamentos — tudo de forma programática. Cada parceiro opera somente a revenda à qual está vinculado.

Marketplace (Anúncios)#

Sincronize o estoque da revenda com o marketplace da Alethica de forma programática. Cada anúncio é identificado pelo seu próprio identificador (externalListingId) — o PUT é idempotente (cria ou atualiza), e a publicação é um passo explícito (/submit). Todos os anúncios pertencem à revenda vinculada ao parceiro.

Assinaturas#

Crie solicitações de assinatura para PDFs próprios, acompanhe o status dos signatários e consulte evidências de auditoria pela API de parceiros.

Webhooks#

Receba notificações em tempo real quando o status de uma solicitação muda. Registre endpoints, escolha os eventos de interesse e receba payloads assinados via HMAC-SHA256.

Eventos disponíveis

Verificação de assinatura (HMAC-SHA256)

Cada entrega inclui headers que permitem verificar a autenticidade. O header X-Alethica-Signature contém o HMAC-SHA256 de timestamp.payload usando seu signingSecret.

import crypto from "crypto";

function verifyWebhookSignature(payload, headers, signingSecret) {
  const timestamp = headers["x-alethica-timestamp"];
  const signature = headers["x-alethica-signature"];

  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestamp}.${JSON.stringify(payload)}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Widget Embarcado#

O widget permite que seus clientes preencham a solicitação de financiamento diretamente no seu site, sem redirecionamentos. A integração é feita via iframe seguro com um token de sessão temporário.

Fluxo de integração

Embed via script

A forma mais simples de integrar o widget é via nosso script de bootstrap. Ele cria automaticamente o iframe e gerencia a comunicação entre janelas.

<!-- Adicione o container onde o widget será renderizado -->
<div id="alethica-widget"></div>

<!-- Inclua o script com os atributos de configuração -->
<script
  src="https://api.alethica.co/api/v1/widget/embed.js"
  data-session-token="SESSION_TOKEN_AQUI"
  data-container-id="alethica-widget"
  data-height="880"
></script>

Analytics de Uso#

Monitore o uso da API com métricas detalhadas de requisições, latência e distribuição por status code e endpoint.

Códigos de Erro#

Todos os erros retornam um JSON com o campo error contendo um código de erro padronizado e uma mensagem descritiva.

{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Access token has expired. Please request a new token."
  }
}

Rate Limiting#

Cada parceiro possui um limite de requisições por minuto configurável. Ao exceder o limite, a API retorna 429 Too Many Requests. Os headers de resposta incluem informações sobre o estado do rate limit.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 45
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 45 seconds."
  }
}