Saltar al contenido principal

Changelog

Historial de cambios de la API de Unicreda.

v1.2.0 (2026-05-10)​

Limite oficial de tamaño de lote ajustado a 5,000 destinatarios por request/Excel.

Cambios mayores​

  • recipients[] en POST /credentials/issue ahora acepta hasta 5,000 destinatarios (antes 10,000). Limite operativo oficial. Pydantic devuelve 422 Unprocessable Entity antes del dispatcher si excede.
  • Endpoints bulk-validate y bulk-emit (admin JWT) rechazan con HTTP 413 Payload Too Large cualquier Excel/lote con mas de 5,000 filas.

Numero defendible para SLAs​

  • 5,000 credenciales/hora sostenido (basado en throughput real medido)
  • 75,000 credenciales/dia asumiendo 15 horas operativas con margen
  • Para volumenes mayores: dividir en multiples requests/Excels.

Migración​

Si tu integracion enviaba >5,000 destinatarios en un solo request, dividir en multiples lotes secuenciales o paralelos (mismo endpoint, mismo flow). Ningun otro cambio en contrato.

v1.1.0 (2026-05-09)​

Endurecimiento de emisión masiva: idempotency, arquitectura por chunks, dead-letter queue con reintento, mayor concurrencia. Sin breaking changes: todos los endpoints existentes mantienen su contrato y forma.

Cambios mayores​

  • Idempotency en emisión masiva: cada job_id actúa como idempotency key implícito. Si el broker o el cliente reintenta el mismo job, las credenciales ya emitidas no se duplican. La base de datos garantiza unicidad por (achievement, email_normalizado, job_id). El response del job incluye un nuevo campo already_emitted que cuenta los recipientes detectados como duplicados; no se cuenta como error.
  • Arquitectura interna por chunks: las emisiones grandes se parten internamente en chunks de 100 filas que se procesan en paralelo. Para el integrador no hay diferencia visible (mismo mode, mismo job_id, mismo polling). La única diferencia perceptible es que progress.current avanza en saltos de 100 en vez de fila por fila.
  • DLQ + Retry: tres endpoints nuevos para auditar y reintentar fallos persistentes:
    • GET /api/v1/jobs/\{job_id\}/failures — fallos de un job específico (vigente 7 días).
    • GET /api/v1/bulk-failures — auditoría histórica con paginación y filtros.
    • POST /api/v1/bulk-failures/\{id\}/retry — reintenta una fila fallida con overrides opcionales.
  • Concurrencia 2x en worker: el worker procesa hasta 2 chunks en paralelo. Mismo throughput percibido en jobs chicos, ~1.7x en batches grandes.

Cambios menores​

  • recipients[] en POST /credentials/issue ahora tiene max_length=10000 (antes sin límite explícito).
  • Validación previa de DNS MX paralelizada (~10x más rápida en lotes con muchos dominios distintos).
  • Rate limits explícitos para los 3 endpoints DLQ (60/60/20 req/min — ver rate-limits.md).

Migración​

Ningún cambio requerido en código de integración. Si tu cliente ya consume GET /jobs/\{id\}, el campo already_emitted aparece automáticamente en el response — podés ignorarlo si no lo necesitás. Para usar el DLQ, ver la guía de manejo de fallos en Quickstart y la referencia completa en Bulk Failures.

v1.0.0 (2026-02-22)​

Release inicial de la API pública.

Endpoints​

  • GET /api/v1/templates - Listar templates de credenciales
  • GET /api/v1/templates/\{id\} - Detalle de template con campos requeridos
  • POST /api/v1/credentials/validate - Validación de datos sin emisión (dry run)
  • POST /api/v1/credentials/issue - Emisión de credenciales (sync para 1, async para N)
  • GET /api/v1/credentials/\{id\} - Consulta de estado de credencial
  • GET /api/v1/jobs/\{id\} - Estado de job de emisión masiva

Autenticación​

  • API Keys con formato uc_live_ + 40 hex chars
  • Headers: X-API-Key o Authorization: Bearer
  • Gestion de keys via panel de admin (crear, listar, revocar)

Features​

  • Emisión síncrona para 1 recipiente, asíncrona para 2+
  • Validación de emails con MX records y detección de typos
  • Deteccion automática de recipientes internos/externos
  • Credenciales Open Badges 3.0 con firma Ed25519
  • Notificacion por email automática
  • Rate limiting por endpoint