Glosario Canónico de Payloads y Eventos

Este glosario evita ambigüedad de nombres y formatos entre frontend, backend, QA y observabilidad.

1. Campos base de API

Campo	Tipo	Obligatorio	Regla
trace_id	UUID	Sí	Presente en toda respuesta API
public_id	UUID/ULID	Sí	Nunca exponer PK interna
status	String (enum)	Sí	Estados definidos por entidad
created_at	ISO-8601 UTC	Sí	Fecha de creación
updated_at	ISO-8601 UTC	Sí	Fecha de última modificación
deleted_at	ISO-8601 UTC/null	No	Soft-delete
country_code	ISO-3166 alpha-2	Sí (cuando aplica)	Ej: GT, MX, CO
locale	String	No	Ej: es-GT
version	Semver x.y.z	Sí	Contratos/documentos/versiones de esquema

2. Campos base de error

Campo	Tipo	Obligatorio	Regla
error.code	String enum	Sí	Ver catálogo canónico de errores
error.message	String	Sí	Mensaje para cliente
error.details	Array	No	Lista de errores por campo
error.trace_id	UUID	Sí	Correlación operativa
error.retryable	Boolean	Sí	Define si cliente puede reintentar

3. Campos base de eventos

Campo	Tipo	Obligatorio	Regla
event_id	UUID	Sí	Identificador único del evento
event_name	String enum	Sí	Nombre canónico (APPOINTMENT_CONFIRMED, etc.)
occurred_at	ISO-8601 UTC	Sí	Timestamp del evento
producer	String	Sí	Servicio emisor
schema_version	Semver x.y.z	Sí	Versionado del payload
payload	Object	Sí	Datos mínimos de negocio
meta	Object	No	Contexto (country_code, source)

4. Convenciones de nomenclatura

• API payloads: snake_case.
• Eventos de dominio: event_name en UPPER_SNAKE_CASE.
• Enums:
  • Estados de entidad en UPPER_SNAKE_CASE.
  • Roles en UPPER_SNAKE_CASE.
• IDs:
  • Público: UUID/ULID.
  • Interno: nunca expuesto fuera de backend.

5. Campos prohibidos en respuestas públicas

• password_hash
• mfa_secret
• refresh_token (si no es endpoint de sesión explícito)
• internal_id / PK autoincremental
• IP o datos sensibles no necesarios para UX

6. Checklist de uso

• Todo endpoint usa trace_id y formato canónico de error.
• Todo evento usa contrato base y schema_version.
• No hay campos duplicados con distinto nombre para el mismo concepto.
• Nombres de estado/rol alineados a enums oficiales en DB/OpenAPI.