FRON-2558 – Documentación pública del ID externo de suscripción
Estado: implementado. Ticket en "En espera deploy". Rama:
feature/mux-mb-26(base:dev).Esta es la spec de
public-sites/documentation— el contrato que ven los comercios en developers.flow.cl. El feature abarca seis repos, cada uno con su propia spec:
Repo Rol Rama public-sites/documentation(este doc)Documentación pública de la API feature/mux-mb-26core/flow.clMigración, dominio y API pública que se documenta acá feature/mux-mb-26core/private-services/subscriptionsAPI privada de la consola feature/mux-mb-26api-gateway/console-servicesRutas del portal feature/mux-mb-26core/private-services/aws-infrastructurePermiso AVP de la nueva acción feature-mux-mb-26core/front/private-portalCampo en creación, detalle editable y filtro feature/mux-mb-26
MR: documentation!26
1. Contexto
El ticket agrega un identificador externo de suscripción y su criterio de aceptación número 5 es explícito: "DADO que se crea una suscripción vía API con ID externo, CUANDO se consulta la suscripción, ENTONCES el campo es retornado correctamente". QA preguntó además si la documentación pública entraba en el alcance del ticket.
La respuesta implícita en la implementación es que sí: el campo es inútil para el caso de uso principal —integraciones vía API de comercios con altos volúmenes— si no está documentado. Este repo es el sitio público de documentación (developers.flow.cl); su static/es-openApiFlow.yaml es el contrato que los comercios leen.
El core expone el campo en subscription/create y agrega subscription/update; acá se documentan ambos.
2. Objetivo
La documentación pública describe el campo external_subscription_id en la creación de suscripciones, documenta el endpoint nuevo subscription/update y muestra el campo en el objeto Subscription que devuelven las consultas.
3. Alcance
Un solo archivo: static/es-openApiFlow.yaml (+68 / −3).
| Sección | Cambio |
|---|---|
/subscription/create — tabla HTML de la descripción | Fila nueva para external_subscription_id con su explicación (máximo 100 caracteres, único por comercio). |
/subscription/create — requestBody | Propiedad external_subscription_id (string, opcional), no incluida en required. |
/subscription/update | Endpoint nuevo: descripción, requestBody (apiKey, subscriptionId, external_subscription_id, s), respuestas 200 / 400 / 401. |
components.schemas.Subscription | Propiedad external_subscription_id con ejemplo ORD-2025-001 y la nota de que devuelve null si no se definió. |
components.schemas (esquema de creación) | Propiedad external_subscription_id con la misma descripción. |
4. No-objetivos
- No se documenta la API privada de la consola (
/v1/subscription/{sus_id}/updatede console-services): es interna del portal, no la consumen los comercios. - No se documenta el campo en webhooks: el core no lo agregó ahí.
- No se traduce a otro idioma: el repo tiene una sola versión del contrato (
es-openApiFlow.yaml); no existe unen-*que quedara desactualizado. - No se agregan ejemplos de código de integración ni guías: solo el contrato OpenAPI.
- No se documenta el campo en el objeto de estado de pago, aunque el core lo devuelve ahí cuando la transacción viene de una factura de suscripción (ver §Preguntas abiertas).
5. Requisitos funcionales
- RF-01: La tabla de parámetros de
/subscription/createincluyeexternal_subscription_idcon la descripción "Identificador externo de la suscripción definido por el comercio. Máximo 100 caracteres, único por comercio". - RF-02: El
requestBodyde/subscription/createdeclaraexternal_subscription_idcomostringopcional (no aparece enrequired, que sigue siendoplanId,customerId,s). - RF-03: Existe
POST /subscription/update, tagsubscription, con el resumen "Modifica una suscripción" y una descripción que explica: permite modificar el identificador externo, es opcional, de máximo 100 caracteres, único entre las suscripciones del comercio, y retorna error si el valor ya está en uso. - RF-04: El
requestBodyde/subscription/updateesapplication/x-www-form-urlencodedconapiKey,subscriptionId,external_subscription_idys, siendo requeridosapiKey,subscriptionIdys— coherente con que el campo se pueda vaciar. - RF-05: Las respuestas documentadas son
200(objetoSubscription),400(error del API) y401(error de negocio), siguiendo el patrón del resto de los endpoints de suscripción del contrato. - RF-06: El schema
Subscriptionincluyeexternal_subscription_idcon ejemploORD-2025-001y la aclaración de que es opcional, único por comercio y devuelvenullsi no se definió. - RF-07: El esquema del cuerpo de creación incluye la propiedad con la misma descripción, de modo que el contrato sea consistente en los dos lugares donde aparece.
7. Diseño propuesto
Estructura del cambio
static/es-openApiFlow.yaml
├── paths./subscription/create.post
│ ├── description → tabla HTML de parámetros: + fila external_subscription_id
│ └── requestBody → + propiedad external_subscription_id (opcional)
├── paths./subscription/update.post ← NUEVO
│ ├── summary/description → qué hace, límite, unicidad, error por duplicado
│ ├── requestBody (form-urlencoded) → apiKey, subscriptionId, external_subscription_id, s
│ └── responses → 200 Subscription | 400 Error | 401 Error
└── components.schemas
├── Subscription → + external_subscription_id (ejemplo, nota de null)
└── (creación) → + external_subscription_id
Decisión 1 — Documentar el endpoint aunque solo edite un campo
subscription/update existe en el core como endpoint genérico con una whitelist de un solo campo. La documentación lo describe por lo que hoy hace ("permite modificar el identificador externo"), en lugar de prometer una capacidad de edición general que no existe. Si la whitelist crece, la descripción se amplía.
Decisión 2 — external_subscription_id no va en required del update
El campo se puede vaciar (enviarlo vacío deja el identificador en null, liberándolo). Declararlo requerido impediría documentar ese caso y contradiría el comportamiento del core. Los requeridos son los de autenticación y el identificador de la suscripción.
Decisión 3 — Documentar explícitamente el null
El schema aclara que el campo devuelve null cuando no se definió. Es la información que evita el soporte más probable: todas las suscripciones creadas antes del feature devuelven null, y un integrador que asuma string siempre presente rompe su parser.
Decisión 4 — Repetir la restricción de unicidad en cada lugar
La frase "único por comercio" (o "único entre las suscripciones del comercio") aparece en las cinco ubicaciones tocadas. Es redundante a propósito: un integrador lee la sección que necesita, no el contrato completo, y la unicidad es la regla que produce el error del que hay que enterarse antes de integrar.
Integración con sistemas externos
El contrato es la fuente del sitio público (developers.flow.cl). No hay código: el cambio es declarativo y su efecto es lo que ve el integrador.
9. Casos borde y errores
-
CB-01: Documentar antes de que el core esté en producción — Impacto: Alto
- Escenario: El sitio público publica
subscription/updatey el campo antes de que la API pública del core esté desplegada en producción. - Comportamiento esperado: Debe evitarse. Un comercio que lea la documentación e integre recibirá error de ruta inexistente o un campo ignorado, con un costo de soporte y de confianza mayor que el de documentar tarde.
- Mitigación: Este repo va último en el orden de deploy del feature, después del core en producción. Es el único de los seis cuyo despliegue es visible para clientes.
- Escenario: El sitio público publica
-
CB-02: Integrador que asume el campo siempre presente — Impacto: Medio
- Escenario: Un comercio consulta suscripciones creadas antes del feature y su parser espera un string.
- Comportamiento esperado: El contrato debe advertir que el valor es
nullcuando no se definió, para que el integrador lo maneje. - Mitigación: La nota explícita del schema
Subscription(RF-06).
-
CB-03: Integrador que reutiliza un identificador — Impacto: Medio
- Escenario: Un comercio con un sistema propio intenta usar el mismo identificador en dos suscripciones (por ejemplo, al re-suscribir un cliente).
- Comportamiento esperado: La documentación debe anticipar el error, no dejar que se descubra en producción: la descripción del update dice que "el servicio retornará un error" si el valor ya está en uso.
- Mitigación: RF-03. Queda pendiente documentar el código de error (ver §Preguntas abiertas).
-
CB-04: Contrato desalineado con el core — Impacto: Medio
- Escenario: El core cambia el límite (100 caracteres) o la semántica y la documentación queda vieja.
- Comportamiento esperado: El contrato es lo que los comercios leen; una desalineación se traduce en integraciones incorrectas.
- Mitigación: La restricción está escrita en cinco lugares del mismo archivo, así que un cambio exige un barrido; conviene buscar
external_subscription_iden el archivo al modificar la regla en el core.
11. Plan de verificación
No hay tests ni build de contrato en este repo para el YAML. La verificación es de contenido y de render.
# Validación sintáctica local del YAML antes de subir
python -c "import yaml; yaml.safe_load(open('static/es-openApiFlow.yaml')); print('YAML OK')"
Checklist
- El YAML es sintácticamente válido (el archivo es grande; un error de indentación rompe el render del sitio completo, no solo esta sección).
- El sitio renderiza
subscription/updateen la sección de suscripciones, con su descripción y sus tres respuestas. -
subscription/createmuestraexternal_subscription_iden la tabla de parámetros y en el cuerpo, marcado como opcional. - El objeto
Subscriptionde la sección de esquemas muestra el campo, su ejemplo y la nota denull. - Los endpoints vecinos (
/subscription/get,/subscription/cancel,/subscription/changeTrial) siguen renderizando bien: el diff toca líneas adyacentes a ellos. - Contraste con el core: los textos documentados coinciden con lo implementado — máximo 100 caracteres, opcional, único por comercio,
nullcuando no se definió, ysubscription/updaterecibeapiKey,subscriptionId,external_subscription_idys. - Prueba real contra el ambiente:
subscription/createcon el campo,subscription/updatecambiándolo ysubscription/getdevolviéndolo, siguiendo exactamente lo que dice la documentación (es la forma de detectar CB-04).
12. Riesgos y mitigaciones
-
R-01: Publicar antes que el core en producción — P: Media · I: Alto
- Descripción: Este es el único repo del feature cuyo despliegue es visible para clientes. Publicado antes del core, documenta una capacidad que no existe: un integrador que la use recibe errores y el equipo recibe tickets de soporte.
- Mitigación: Orden de deploy con este repo al final, después de verificar la API pública en producción. El MR no debería mergearse hasta entonces.
-
R-02: Error de sintaxis en un archivo de 7000+ líneas — P: Baja · I: Alto
- Descripción: El contrato completo vive en un solo YAML. Un error de indentación no rompe solo la sección nueva: puede impedir el render de toda la documentación pública.
- Mitigación: Validación del YAML antes de subir (§11) y revisión visual de los endpoints vecinos, que son los que el diff toca por proximidad.
-
R-03: Desalineación futura con el core — P: Media · I: Medio
- Descripción: El límite y la semántica están escritos en cinco lugares de este archivo y también en el core, ms-subscriptions y el portal. Un cambio en el backend deja la documentación pública mintiendo, y es la que menos se revisa.
- Mitigación: Al modificar la regla, barrer
external_subscription_iden este archivo. La verificación de §11 incluye contrastar contra el comportamiento real del ambiente, no solo leer el diff.
-
R-04: Código de error no documentado — P: Media · I: Medio
- Descripción: La descripción dice que "retornará un error" ante un duplicado, pero no publica el código (1002) ni el mensaje. Un integrador no puede distinguir programáticamente ese caso de otros errores de negocio y tendrá que hacer matching por texto.
- Mitigación: Queda como pregunta abierta; el código ya está estable en el core (1002, misma fuente de verdad en los tres puntos de detección), así que documentarlo es de bajo costo.
13. Checklist de aceptación
- Requisitos funcionales implementados (RF-01 a RF-07)
- Casos borde considerados (CB-01 a CB-04)
- Campo documentado en creación, en el endpoint nuevo y en el objeto de respuesta
- Opcionalidad y unicidad por comercio explícitas en cada ubicación
- Comportamiento
nulldocumentado - YAML validado y render verificado en el sitio (§11)
- Textos contrastados contra el comportamiento real del ambiente
- Publicado después del core en producción (R-01)
Preguntas abiertas
- Código de error del duplicado (R-04): el core devuelve code 1002 con el mensaje "Este ID ya está en uso, ingresa uno diferente". ¿Se documenta explícitamente, para que el integrador pueda distinguirlo por código y no por texto?
- Case-sensitivity (pregunta de QA sin responder en el ticket): la documentación dice "único por comercio" sin aclarar si
SUS-123ysus-123son el mismo identificador. Hoy lo decide la collation de la base. Es información que un integrador necesita antes de elegir su formato de identificadores. - Caracteres permitidos: el core rechaza caracteres de control pero acepta espacios y símbolos. La documentación no lo menciona. ¿Se agrega, sobre todo si se decide restringir el formato?
- Campo en el estado de pago: el core devuelve
subscription.external_subscription_iden el estado de pago cuando la transacción viene de una factura de suscripción, y eso no está documentado acá. ¿Entra en este ticket o en uno aparte?