API Identifier Strategy — Discussion Document

§1 El problema

QIIUB hoy tiene dos fuentes de verdad contradictorias sobre cómo deben verse los identificadores en las rutas de API:

Ambos fueron aceptados el mismo día (2026-03-12) y nunca se resolvió la inconsistencia. El resultado: Phase 18 cerró con 246 endpoints y solo 2 entidades (Merchant, Partner) usando el PublicId. Todo lo demás — productos, ventas, clientes, empleados, purchase orders, shifts, gift cards, etc. — todavía expone el bigint Id interno.

§2 Estado actual de QIIUB

Ejemplos reales del código actual

// src/QIIUB.Api/Features/Products/GetProduct/GetProductEndpoint.cs:57
public override void Configure() {
    Get("/products/{Id}");    // ← expone bigint
}

// src/QIIUB.Api/Features/Sales/GetSale/GetSaleEndpoint.cs:90
Get("/sales/{Id}");             // ← expone bigint

// src/QIIUB.Api/Features/Platform/Merchants/GetMerchant/GetMerchantEndpoint.cs:57
Get("/platform/merchants/{Id}");   // ← acepta Id O PublicId (8-hex)

// src/QIIUB.Api/Features/Platform/Partners/GetPartner/GetPartnerEndpoint.cs:38
Get("/platform/partners/{PublicId}"); // ← solo PublicId (único consistente)

Total endpoints con bigint en ruta: ~240 de 246. Solo los endpoints de Partner y algunos de Merchant usan PublicId.

§3 Qué hacen otros POS y plataformas

Research completo en docs/research/research-api-identifier-format.md (14 plataformas + 5 especificaciones, con fuentes verificables). Resumen ejecutivo por categoría:

Hallazgos claves

• Toda plataforma que migró desde 2015 se alejó de bigint. Shopify, GitHub, Lightspeed lo hicieron. Nadie fue en dirección contraria.
• Typed prefixed IDs no son solo fintech. Square los adoptó en APIs lanzadas 2020+. Está llegando a POS.
• "Trate como opaco" es guidance universal. Shopify, GitHub, Slack, Linear todos publican lo mismo: no parseen, no generen, no dependan de la estructura.
• Casi nadie publica el algoritmo de generación. Solo Stripe lo hace en detalle. Todos los demás protegen esa información como implementation detail.

§4 El caso Square — nuestro cautionary tale

§5 La pregunta del nombre

Punto válido del team: ¿no podría confundirse "TypeID" con campos como ProductTypeId, PaymentTypeId, UserTypeId — FKs a tablas de enums o discriminadores de tipo?

Sí, absolutamente. "TypeID" como vocabulario del proyecto sería confuso. Comparación rápida:

// C# entity
public class Product : BaseEntity
{
    public long Id { get; set; }            // interno, bigint
    public Guid GlobalId { get; set; }       // sync identity — sin cambios
    public string PublicId { get; set; }      // "prod_01j8m410fpqm..." — expuesto en API
    public int MerchantId { get; set; }
    // ...
}

// Ruta
Get("/products/{PublicId}");

// Cliente HTTP
GET /products/prod_01j8m410fpqm4r6t8v0x1a3c5e7

§6 Arquitectura: dónde vive cada ID

QIIUB tiene tres tipos de identificadores con tres roles bien diferenciados. Antes de discutir formato, hay que tener clara la arquitectura porque el formato del PublicId solo aplica a parte del sistema — no al hot path del cashier.

Las tres columnas en cada entidad

public class Product : BaseEntity
{
    public long Id { get; set; }            // (A) INTERNO — PK clustered (MerchantId, Id), FKs, joins. Nunca expuesto.
    public Guid GlobalId { get; set; }       // (B) SYNC — dedup en push offline. En body MessagePack del sync engine.
    public string PublicId { get; set; }      // (C) EXTERNO — único en URL/response de API pública. "prod_01j8m..."
    public int MerchantId { get; set; }
    // ...
}

El flujo completo

Matriz: dónde se ve cada ID

§7 Recomendación: dos decisiones separadas Propuesta

El HTML original las trataba como una sola decisión. En realidad son dos decisiones independientes con perfiles de debate muy distintos.

Comparación visual: hoy vs propuesto

§8 Por qué UUIDv7 específicamente y no algo más corto

Pregunta válida del equipo: "¿Por qué UUIDv7 y no algo más corto, dado que ya tenemos prefijo tipado para diferenciar tipos?". Aquí el análisis honesto con números reales.

Las opciones reales (con cuenta correcta)

Asumiendo prefijo de 5 chars (prod_):

Diferencias clave:

• NanoID-16 vs UUIDv7-base62: 6 chars de diferencia (21 vs 27)
• NanoID-16 vs TypeID: 10 chars de diferencia (21 vs 31)
• NanoID-21 vs TypeID: 5 chars de diferencia (26 vs 31)

Los 5 factores que importan PARA QIIUB específicamente

Cuándo la opción más corta SÍ sería correcta

Resumen comparativo concreto

// Más corto (NanoID-16, 21 chars):
prod_V1StGXR8_Z5jdHi6B-

// UUIDv7 base62 (27 chars):
prod_2x4y6z8a0b1c2d3e4f5g6h

// TypeID Crockford base32 (31 chars) — recomendado:
prod_01j8m410fpqm4r6t8v0x1a

// UUIDv4 actual GUID (41 chars):
prod_550e8400-e29b-41d4-a716-446655440000

5-10 chars extra para offline-determinismo + fragmentation-fix + spec-based. Trade reasonable. No es "UUIDv7 porque sí" — es "UUIDv7 porque QIIUB es offline-first y tiene Sale".

Las 7 razones (originales, refinadas)

1. Resuelve la contradicción ADR-0005 vs ADR-0029. UUIDv7 cumple sync (colisión-libre offline) y el suffix de 26 chars cumple "corto" de ADR-0029.
2. UUIDv7 arregla la fragmentación de índice que ADR-0005 mitigó con NEWSEQUENTIALID(). Time-ordered globalmente, server y client.
3. El prefijo paga en logs y debugging. El POS llama cloud para returns/loyalty/AR — los IDs aparecen en Sentry breadcrumbs y mensajes de error. sale_01j8m... se entiende solo; 987654 no.
4. Spec open-source, no roll-your-own. Adoptamos estándar emergente con lecciones de Stripe ya incorporadas.
5. Evita el escenario Square. Una regla explícita ahora, antes de crecer a 500+ endpoints.
6. Forward-compatible con webhooks. IDs prefijados son mandatorios cuando el payload no tiene URL context.
7. Consistente con la convención PublicId existente de Merchant/Partner. Extendemos, no inventamos.

§9 Decisiones a confirmar por el equipo Abiertas

Prefijos propuestos (preliminar — sujeto a Q5)

§10 Alternativas viables

§11 Lo que NO debe hacerse Anti-patrones

• IDs compuestos tipo Square refund. Embebir el parent ID en el child (refund_id = payment_id + "_" + suffix) es tentador para lookup gratis pero acopla los dos IDs para siempre y rompe el contrato "opaco".
• Diferentes formatos por entidad. La lección principal de Square. Si hay UNA cosa que la ADR debe lograr, es "una regla, todas las entidades".
• Version markers dentro del prefix (inv:0-…). Parece buena idea; en la práctica nunca se usa — cuando hay que migrar, el equipo introduce un prefijo nuevo (inv2_…) de todos modos.
• Exponer GlobalId as-is con 36 chars. Es lo que ADR-0005 insinuó; hoy sabemos que UUIDv7 + base32 da 26 chars con propiedades equivalentes.
• Generar PublicId en el cliente del POS sin coordinación. UUIDv7 sí puede generarse client-side (ya lo hacemos con GUIDv4) — pero el prefix debe venir de una tabla/enum compartida, no hardcoded en cada app.
• Parsear el PublicId en el frontend. Los clientes deben tratarlo como string opaco. No publicId.substring(5), no publicId.split("_")[1]. Regla: opaco.

§12 Próximos pasos

1. Discusión de equipo sobre este documento. Respuestas a Q1–Q7.
2. Escribir ADR-0044 — "Uniform API identifier strategy — prefixed PublicId across Central and Merchant DBs". Supersede la línea de API routes de ADR-0005, extender scope de ADR-0029.
3. Task file en C:\temp\.claude\qiiub\ con plan de migración detallado: prefijos definitivos, librería C# (Jetify/TypeID bindings), estrategia de migración de data, actualización de 240 endpoints, ajuste de admin portal + mockups, tests de integración.
4. Actualizar docs afectados:
   • docs/adr/0005-globalid-guid-sync-identity.md — reemplazar nota "under review" con referencia a ADR-0044
   • docs/adr/0029-publicid-central-api-routes.md — marcar como supersedida por ADR-0044 (manteniendo el 8-hex para Merchant/Partner como legacy)
   • docs/qiiub-context-for-ai.md §API Identifier Strategy — reemplazar con la regla final
   • Memoria feedback_api_identifiers.md — actualizar con la regla final
5. Implementación antes de Phase 19 (Merchant Portal frontend).

Research completo con fuentes verificables → docs/research/research-api-identifier-format.md

QIIUB — API Identifier Strategy Discussion · 2026-04-24 AST