Skip to main content
Traducción. Autoritativo: ../../standards/api.md.

​
Base y estructura

  • Canónico: https://api.softcrum.com/v1/{module}/{resource} (sin segmento /api). Módulos: identity, core, loyalty, messaging, crm (los módulos de la suite se suman a medida que exponen API pública).
  • SIN aliases estilo Segment en v1 (/v1/track no existe; el canónico es /v1/core/track). Una capa de compatibilidad Segment es una feature futura explícita solo si una integración real la exige.
  • Dos clases de API dentro de la misma convención:
    • Runtime (camino caliente, llamado en línea por los sistemas del tenant): track/identify/batch, canjes, validación de cupón, qualifications, members/me. SLO p95: track <100 ms (fast-ack 202), lecturas de member <150 ms, decisiones síncronas <300 ms.
    • Management (CRUD de consola e integraciones): todo lo demás. SLO p95 <1 s. Paginación obligatoria (por cursor).
  • Los presupuestos de SLO son ítems del Definition of Done; los tests de carga con k6 gatean la certificación.

​
Parámetros de política

Todo parámetro de política es configurable por tenant y viene con un default publicado (OQ-LOY-14). Ventanas de atribución, horizontes de vencimiento, períodos de gracia, TTL de reservas, límites de reversa, ventanas de devolución, cantidad de reintentos — un valor que elegimos es un punto de partida, nunca una restricción con la que el tenant tenga que vivir. De ahí dos obligaciones: el default se documenta en la referencia pública junto al parámetro, y cambiarlo surte efecto desde ese momento hacia adelante, nunca retroactivamente sobre registros ya creados bajo el valor anterior. La excepción es un parámetro que gobierna una máquina de estados o un invariante de corrección. Esos no son política y no son configurables.

​
AuthN/AuthZ

  • Mecanismos: API keys de tenant (con alcance, rotables) · write keys públicas (solo track, llegan con el widget en F1b) · OAuth2 client credentials (integraciones) · tokens de member (OTP o magic link nativo, o token exchange POST /v1/core/auth/token-exchange).
  • Modelo de autorización (DEC-D5): cada endpoint declara EXACTAMENTE UN permiso {module}.{resource}.{action} (por ejemplo loyalty.redemptions.create). Los permisos se agrupan en roles; los roles se asignan a usuarios Y a máquinas (API keys y clientes OAuth = roles de máquina). Los scopes OAuth son agrupaciones de permisos mostradas en la pantalla de consentimiento.
  • A los terceros NUNCA se les exige entregar IPs: keys + HMAC + rate limits bastan. La allowlist de IP por tenant existe como endurecimiento opcional, apagada por defecto.

​
Convenciones

  • Idempotencia: cabecera Idempotency-Key OBLIGATORIA en POST /v1/loyalty/redemptions y en toda mutación que la documentación marque como idempotente; el servidor guarda el resultado 24 h y lo reproduce.
  • Errores: RFC 9457 problem+json con code estable (por ejemplo UNSUPPORTED_CODE, LIMIT_EXCEEDED, SUPPRESSED_RECIPIENT).
  • Rate limits: PUBLICADOS por plan en la documentación; las respuestas llevan cabeceras RateLimit-* estándar.
  • Deprecación: ventana mínima de 6 meses, cabecera Sunset, entrada en el changelog de Mintlify. Solo cambios aditivos dentro de v1.
  • Regla de oro: la consola, el portal y el widget propios de Softcrum consumen EXCLUSIVAMENTE esta API pública vía packages/api-client. Si nuestra UI necesita algo que la API no tiene, la API está incompleta.