@bacano/sdk 1.2.1 → 1.2.3

package/FLOWS.md

@@ -0,0 +1,114 @@
+# Flows: participant SDK
+
+This delivery provides a local integration surface. Production identity and access-management adapters are intentionally not enabled yet. The local gateway returns 404 outside development even if its demo flag is enabled. Do not deploy demo credentials or replace Clerk with this adapter.
+
+```ts
+import { createFlowsClient } from "@bacano/sdk";
+
+let token: string | null = null;
+const flows = createFlowsClient({
+  apiUrl: "http://localhost:3001",
+  getAccessToken: () => token,
+});
+const session = await flows.localDemoLogin("ana@example.test", "Academy123!");
+token = session.token;
+const cases = await flows.listCases();
+const journey = await flows.getJourney(cases[0].id);
+// Render only available steps and the capabilities returned by the server.
+await flows.logout();
+token = null;
+```
+
+Existing Bacano clients expose the same methods on `client.flows`. No direct Hasura access or administrative credential belongs in the website. Bearer identity is resolved by the gateway; request bodies cannot choose a participant.
+
+## Surface
+
+- `listCases()`, `getJourney(caseId)`: explicitly granted cases and filtered state.
+- `getContent(caseId, stepId)`: ordered published Content resources compatible with Flows. Private fields are removed by the backend.
+- `getFile(caseId, stepId, fileId)`: authenticated Blob, only for files referenced in accessible content and belonging to the company. Revoke object URLs on unmount/logout.
+- `getForm(caseId, stepId)`: current published form, version and definition hash.
+- `getResponse(caseId, stepId)`: own response or explicitly shared evaluation; historical labels/answers, attempt and submission time. Never internal notes.
+- `act(caseId, command)`: `complete_content`, `complete_task`, `submit_form`. No review/approval/move operation for the participant.
+
+Every command supplies `stepId`, `revision` (case), `flowRevision`, and `idempotencyKey`. Keep the **same complete envelope and key** on network retries. New input requires a new key. On revision conflict refresh the journey and ask the person to review before resending. The server rechecks access, assignment, sequence and state; rendered buttons are not authorization.
+
+```tsx
+import { BacanoFlowForm } from "@bacano/sdk/react/forms";
+
+<BacanoFlowForm
+  key={`${caseId}:${stepId}:${publishedForm.correction?.attempt ?? 0}`}
+  form={publishedForm}
+  onRefresh={reloadPublishedForm}
+  onSubmit={(values, form) => submitStep({
+    operation: "submit_form",
+    submission: { values, formVersion: form.version, definitionHash: form.definitionHash },
+  })}
+/>
+```
+
+The component reuses existing Forms controls but never posts to the website-entry endpoint. A publication conflict leaves entered answers in place; refreshing the definition does not clear them. It does not persist sensitive drafts in localStorage. Clearing the authenticated view on logout removes its state. Applications must provide error/loading states and retain an idempotency envelope for retries.
+
+### Corrections
+
+After an operator requests changes, `getForm` may include `initialValues` and
+`correction: { attempt, formChanged }`. These are the authenticated participant's
+own previous answers to this case/step/form, filtered against the currently
+published questions and selected conditional branches. They never contain internal
+evaluations or another participant's answers. Numbers/scales use editable strings;
+checkboxes preserve booleans. Removed options and fields are omitted.
+
+Initialize a custom renderer from `initialValues ?? {}` once per case/step/attempt.
+Do not overwrite unsent edits during refresh or use case revision as a component
+key. Show a review warning when `formChanged` is true. Submitting creates a new
+immutable response; the earlier attempt remains in the operator history.
+Requesting changes requires participant instructions, not the configured evaluation
+form. Approving still requires that evaluation when configured.
+
+## Stage presentation
+
+Each journey stage exposes `presentation`: `step_by_step` (default, including older definitions) or `single_view`. Treat an absent value from an older gateway as `step_by_step`. This preference is independent of sequential/free execution order and manual/automatic advancement.
+
+For `single_view`, render the stage's steps together in their existing order, with stable component keys based on case and step IDs. Each activity saves independently; do not introduce a combined submit or automatically complete content when a form is sent.
+
+- Unavailable steps may show a locked heading, but must not load their content, form or files.
+- Internal steps may show their public status, never private instructions, evaluations or review controls. Respect `canReadResponse` for explicitly shared responses.
+- Operator-assigned tasks are omitted entirely from the participant journey,
+  including their titles. They remain operable in Bacano and still govern
+  sequencing/advancement. A stage with only internal tasks may therefore have
+  no visible steps: show a waiting state, never advance it in the browser.
+  Explicitly participant-assigned tasks remain available to that participant.
+- Refresh the journey after every action. Use the updated revisions for new commands. Concurrent actions may conflict; preserve unsent form values and let the participant retry after refreshing.
+- Keep sibling forms mounted when a step is completed so their local inputs survive. Do not use the case revision as a React key.
+- In single-view mode, keep the current page after saving; the participant can navigate to the next stage using the journey navigation.
+
+This is configuration delivered by the SDK, not an automatic layout component. Consuming applications implement the layout; the local Academy example implements both modes.
+
+## Local identity and access
+
+- Local demo emails: `ana@example.test`, `luis@example.test`; password `Academy123!`.
+- Enable only the local backend override (`docker-compose.flows-demo.yml`) and an explicit website UUID. Origins must be localhost/loopback.
+- The seed explicitly creates two client/contact fixtures, two separate real cases and grant rows. Runtime access is **not** inferred from email or contact.
+- Opaque local sessions expire after one hour; API restart or logout invalidates them. Session loss never deletes case data.
+- Revoking a `flow_case_access` row blocks subsequent reads and commands without deleting audit history.
+- A manual-advance stage remains there after its required form is submitted. An operator must move it; automatic stages use the existing domain rules. Empty stages do not advance spontaneously.
+
+## Pending before production
+
+Verify Clerk through the existing website identity adapter; add operator grant/revoke actions guarded by `flows.share`; validate isolation across real sites/tenants and production accounts; replace local fixtures and test deployment. Do not enable production by weakening the development/origin checks.
+
+## Contenido con devolución relacionada
+
+Un paso `content` puede exponer `canReadResponse: true`. En ese caso consulta
+`getContent(caseId, step.id)` y `getResponse(caseId, step.id)` para presentar el
+material de apoyo junto a la devolución original del mismo caso. No uses IDs de
+respuestas ni de otros pasos para saltarte la disponibilidad del recorrido.
+
+Si `canComplete` es verdadero y el contenido no es de consulta, ofrece continuar
+mediante `act(..., { operation: "complete_content", ... })` con las revisiones e
+idempotency key vigentes. La aprobación interna entrega el resultado; esta acción
+registra por separado la confirmación del participante. No marques el paso como
+completado por abrirlo. Si la respuesta no pudo cargarse, no ofrezcas confirmarla.
+
+Tras cada acción vuelve a consultar el recorrido y presenta su etapa actual.
+Durante una espera interna puedes consultar periódicamente el estado; conserva
+los formularios con valores sin enviar que sigan en la misma etapa agrupada.

package/README.md

@@ -7,6 +7,10 @@ Buyer credentials are owned by each storefront's Clerk application. Read
 sign-in, customer profiles, authenticated checkout, or order history. The guide
 ships inside the npm package.
 
+For participant journeys, forms and activities, see [FLOWS.md](./FLOWS.md).
+Flows currently includes an explicitly gated local identity adapter; production
+participant authentication and grant management are not enabled by this sample.
+
 ## Installation
 
 ```bash
@@ -107,6 +111,12 @@ when instrumenting analytics, advertising signals, contact actions, ecommerce
 events, attribution, or preview behavior. It is the canonical implementation
 contract for storefront agents and ships inside the npm package.
 
+Every storefront that accepts payments must follow
+[`STOREFRONT_PAYMENTS.md`](./STOREFRONT_PAYMENTS.md). It defines the SDK flow,
+provider boundaries, Mercado Pago Orders setup and payload invariants, safe
+retry behavior, diagnostics and the minimum sandbox evidence required before
+production.
+
 Commercial forms and newsletter subscriptions must follow
 [`STOREFRONT_LEADS.md`](./STOREFRONT_LEADS.md). Storefronts own the form UI;
 Bacano owns consent evidence, identity resolution, attribution and idempotent
@@ -639,9 +649,16 @@ ahora" and "Pagar al recoger", while `SHIPPING` may return "Pagar ahora" and
 "Pagar contraentrega".
 
 Only payment methods marked as **Disponible para web** in Bacano and enabled in
-the website payment settings are returned. Gateway methods such as Wompi expose
-`gatewayCode`, `requiresPaymentSession` and public configuration only; secrets
-never leave Bacano.
+the website payment settings are returned. Gateway methods such as Wompi,
+Mercado Pago, Openpay and Addi expose `gatewayCode`,
+`requiresPaymentSession` and public configuration only; secrets never leave
+Bacano.
+
+Openpay uses its hosted Webcheckout. The storefront does not render Openpay.js,
+does not request card/PSE data and does not send a provider transaction ID when
+reconciling the return. Open the Bacano `redirectUrl` immediately and let the
+backend verify the charge. See [STOREFRONT_PAYMENTS.md](./STOREFRONT_PAYMENTS.md)
+for the provider-specific contract and retry rules.
 
 Each payment option also exposes `initialPaymentPolicy` (`none`, `optional` or
 `required`), `requiresInitialPayment`, `minInitialAmount` and
@@ -657,6 +674,60 @@ initialPayment: {
 The API enforces the policy, minimum and order total. Do not infer deposits from
 labels or delivery mode.
 
+#### Addi: conditional buyer identification
+
+The Addi backend adapter is implemented on the integration branch and internally
+tested. It still requires migration, merchant configuration and sandbox validation
+before use. Render only methods returned by Bacano, never invent an Addi option:
+
+- When the selected method has `gatewayCode === "ADDI"`, show the identification
+  fields immediately below that payment method, before submitting the order.
+- Request **Cédula de ciudadanía** only if a compatible document is missing.
+  Reuse an existing CC without asking the buyer to enter it twice; allow correction.
+- Addi only accepts CC in this integration. Show the document type as the fixed
+  label **Cédula de ciudadanía (CC)**, not a selector offering unsupported types.
+  The editable field is **Número de cédula**; no document photo is requested here.
+- Submit identification through the existing `contact.documentType` and
+  `contact.documentNumber` fields. Use Bacano's document-type identifiers from
+  `customerIdentification`; the backend adapter must map the CC identifier to
+  Addi's `idType: "CC"`. Do not assume the two systems use identical codes.
+- Switching away from Addi removes its extra identification requirement and
+  hides fields added only for Addi. Keep any identification fields required by
+  the website's own `customerIdentification` policy.
+- Validate missing/incompatible identification before proceeding, with an
+  inline message explaining that Addi requires a CC. Backend validation must
+  enforce the same rule; hiding a field is not a security boundary.
+
+Suggested helper text: “Para continuar con Addi, necesitamos tu número de
+cédula. Completarás el proceso de financiación en Addi.”
+
+This condition concerns identification only; the integration must also validate
+the other buyer data required by Addi. Credit evaluation and financing remain
+in Addi's hosted checkout, not in a custom storefront credit form.
+For Addi, also provide `contact.firstName`, `lastName`, `email`, a Colombian
+`cellphone`, and residence in `contact.address.line1` and
+`contact.address.municipalityName`. Ask explicitly before reusing a delivery
+address as residence. These fields already exist in the SDK contact contract.
+This first adapter supports complete product-order payments in COP, not deposits
+or service orders. Errors must remain visible; never mark a payment approved from
+redirect parameters. Use the backend's order status.
+See the [official Addi API](https://api-docs.addi-staging.com/integration/).
+
+#### Payment-method surcharge (planned; not yet available)
+
+The planned company payment-method setting is **Recargo al comprador (%)**,
+defaulting to **0 %**, shared by web and point of sale. This is a merchant
+surcharge, not the provider's financing interest or settlement commission.
+The agreed basis is products after discounts, excluding shipping.
+Provider/merchant contractual eligibility and the calculation/tax rules must be
+confirmed before enabling it.
+
+Once supported, storefronts must show the backend-calculated surcharge and final
+total when a method is selected, before the buyer confirms. Switching methods
+must remove/recalculate it; 0 % adds no charge. Do not calculate a surcharge
+locally or add it directly to the gateway amount. There are no surcharge SDK
+fields or operations available yet; the response contract remains to be defined.
+
 ```typescript
 const payNow = paymentOptions.find((option) => option.mode === "pay_now");
 
@@ -945,6 +1016,10 @@ contains only browser-safe media metadata and a public Storage URL.
 
 GA4, Meta, and Microsoft Clarity are configured per website in Bacano and are
 disabled by default.
+An optional Google Tag Manager web container is also supported via
+`marketing.destinations.gtm.containerId`. It adds `bacano_*` browser events to
+the data layer without replacing native destinations or server conversions.
+See [GTM setup, limitations and duplication safeguards](./STOREFRONT_MARKETING.md#google-tag-manager-contenedor-web-opcional).
 The existing public-config request returns only active public destination IDs;
 provider secrets never reach the SDK. The runtime remains a no-op outside the
 website's canonical production domain.
@@ -1533,22 +1608,22 @@ function ProfilePage() {
 
 ### Hooks Summary
 
-| Hook                          | Returns                                                                                 | Auth Required |
-| ----------------------------- | --------------------------------------------------------------------------------------- | ------------- |
-| `useBacano()`                 | `BacanoClient`                                                                          | No            |
-| `useBacanoState()`            | `{ client, loading, error }`                                                            | No            |
-| `useProducts(opts?)`          | `{ data, loading, error, refetch }`                                                     | No            |
-| `useProduct(id)`              | `{ data, loading, error, refetch }`                                                     | No            |
-| `useCategories()`             | `{ data, loading, error, refetch }`                                                     | No            |
-| `useBrands()`                 | `{ data, loading, error, refetch }`                                                     | No            |
-| `useProductFilters(opts?)`    | `{ data, loading, error, refetch }`                                                     | No            |
-| `useSearchSuggestions(opts?)` | `{ data, loading, error, refetch }`                                                     | No            |
-| `useAvailability(ids)`        | `{ data, loading, error, refetch }`                                                     | No            |
+| Hook                          | Returns                                                                                        | Auth Required |
+| ----------------------------- | ---------------------------------------------------------------------------------------------- | ------------- |
+| `useBacano()`                 | `BacanoClient`                                                                                 | No            |
+| `useBacanoState()`            | `{ client, loading, error }`                                                                   | No            |
+| `useProducts(opts?)`          | `{ data, loading, error, refetch }`                                                            | No            |
+| `useProduct(id)`              | `{ data, loading, error, refetch }`                                                            | No            |
+| `useCategories()`             | `{ data, loading, error, refetch }`                                                            | No            |
+| `useBrands()`                 | `{ data, loading, error, refetch }`                                                            | No            |
+| `useProductFilters(opts?)`    | `{ data, loading, error, refetch }`                                                            | No            |
+| `useSearchSuggestions(opts?)` | `{ data, loading, error, refetch }`                                                            | No            |
+| `useAvailability(ids)`        | `{ data, loading, error, refetch }`                                                            | No            |
 | `useCart()`                   | `{ cart, loading, error, startCheckout, getOrCreate, addItem, updateItem, removeItem, clear }` | No            |
-| `useCheckout()`               | `{ checkout, loading, error }`                                                          | No            |
-| `useOrders(opts?)`            | `{ data, loading, error, refetch }`                                                     | Yes           |
-| `useOrder(id)`                | `{ data, loading, error, refetch }`                                                     | Yes           |
-| `useProfile()`                | `{ profile, loading, error, updateProfile }`                                            | Yes           |
+| `useCheckout()`               | `{ checkout, loading, error }`                                                                 | No            |
+| `useOrders(opts?)`            | `{ data, loading, error, refetch }`                                                            | Yes           |
+| `useOrder(id)`                | `{ data, loading, error, refetch }`                                                            | Yes           |
+| `useProfile()`                | `{ profile, loading, error, updateProfile }`                                                   | Yes           |
 
 ---
 

package/STOREFRONT_FORMS.md

@@ -1,5 +1,19 @@
 # Formularios de websites
 
+## Escalas discretas (desarrollo local)
+
+El tipo `scale` incorpora `scale: { min, max, display, minLabel?, maxLabel? }`.
+`display` admite `numbers` o `stars`. Los límites son enteros entre 0 y 10,
+con mínimo menor al máximo; las estrellas comienzan en 1. No usa `optionSource`
+ni `validation`: sus límites viven en `scale`. Ejemplo: `scale: { min: 1, max: 5, display: "stars" }`.
+
+El renderer muestra una selección única, sin valor inicial. Envía el entero elegido
+como string (`"4"`), igual que los campos numéricos existentes. El backend valida
+el rango, guarda el número y conserva `4 / 5` en el snapshot histórico. Funciona
+tanto en formularios web como en pasos de Flows. No es un slider continuo ni una
+calificación calculada automáticamente. Renderers propios deben respetar el
+rango, `required`, las etiquetas y la interacción por teclado.
+
 Desde SDK 1.2.0, `BacanoForm` instrumenta interacciones mediante el provider
 global de marketing. Para modales montados ocultos, pasar `visible={open}`.
 Renderers personalizados usan `useBacanoFormTracking`. Leer la sección de
@@ -250,6 +264,42 @@ consultarlo.
   no recibe ni debe inferir si Bacano creó un lead, encontró un cliente o marcó
   una identidad para revisión.
 
+## Preguntas condicionales
+
+Un campo `radio` o `select` con opciones inline puede incluir ramas recursivas:
+
+```ts
+branches: [
+  { value: "simple", fields: [/* campos normales */] },
+  { value: "complete", fields: [/* campos normales o condicionales */] },
+]
+```
+
+`value` corresponde al valor estable de una opción. La etiqueta puede cambiar sin
+mover sus campos. Las definiciones sin `branches` siguen funcionando igual.
+`BacanoForm` y el renderer de formularios de Flows muestran solo el camino elegido,
+aplican la obligatoriedad de sus hijos y descartan valores ocultos al cambiar de
+opción. El backend vuelve a validarlo; no acepta respuestas de caminos ocultos.
+
+Para un renderer propio, importar desde la entrada principal del SDK:
+
+```ts
+import { activeFormValues, formRootFields, visibleFormFields } from "@bacano/sdk";
+
+const fields = visibleFormFields(formRootFields(definition), values);
+const submissionValues = activeFormValues(definition, values);
+```
+
+`visibleFormFields` devuelve la ruta activa aplanada, incluyendo las preguntas
+padre. Para preservar secciones, pasos y presentación, recorrer cada contenedor
+y sus ramas seleccionadas. Al modificar una respuesta, usar `activeFormValues`
+también para actualizar el estado: evita restaurar respuestas ocultas al volver
+a una opción anterior. Filtrar nuevamente antes de enviar.
+
+Los sitios que tengan instalado un SDK anterior deben actualizarlo. Una definición
+con ramas necesita un renderer compatible; no basta con actualizar el backend.
+La definición admite cinco niveles condicionales y cien campos en total.
+
 ## Checklist mínimo del storefront
 
 - Usar un solo `BacanoProvider` y el cliente global ya inicializado.

package/STOREFRONT_MARKETING.md

@@ -6,9 +6,65 @@ identificadores, adaptadores ni llamadas directas a proveedores.
 
 ## Regla principal
 
+### Google Tag Manager (contenedor web opcional)
+
+En Bacano, la tarjeta Google Tag Manager permite guardar un ID `GTM-…`, validar
+que el script publicado sea accesible y activar o pausar la integración por sitio.
+Validar no comprueba propiedad del contenedor, etiquetas, consentimiento ni
+recepción de eventos: comprobar esto en Tag Assistant con el administrador del
+contenedor. No se solicitan secretos, HTML ni URLs de scripts personalizados.
+
+Requiere desplegar API/migración y actualizar `@bacano/sdk` en el storefront.
+El contrato público añade `marketing.destinations.gtm.containerId`; SDKs anteriores
+lo ignoran. Un sitio con configuración estática debe reconstruirse para incorporar
+cambios. No se modifica ni se publica automáticamente ningún contenedor de Google.
+
+El mismo `BacanoMarketingProvider` carga `gtm.js` una sola vez, conserva la cola
+`window.dataLayer` existente y respeta las barreras de dominio, preview y
+`measurementAllowed`, además de la carga diferida. No instalar otro snippet.
+Esta versión requiere JavaScript; no incorpora un iframe `noscript` ni GTM server-side.
+Pausar evita nuevas cargas con la configuración actualizada; no puede deshacer
+etiquetas de terceros ya ejecutadas en pestañas abiertas. Recargar para comprobar.
+
+Los eventos oficiales de navegador se publican con prefijo `bacano_`:
+
+```js
+{ event: "bacano_add_to_cart", bacano: {
+  schema_version: 1, event_name: "add_to_cart", event_id: "…",
+  currency: "COP", value: 50000,
+  items: [{ item_id: "product-variant-id", item_name: "Producto", quantity: 1 }]
+} }
+```
+
+Configurar activadores de evento personalizado `bacano_*` y variables de capa de
+datos como `bacano.event_name`, `bacano.value` y `bacano.items`. El objeto `bacano`
+se limpia antes de cada evento para no arrastrar artículos ni parámetros anteriores.
+Incluye URL saneada, parámetros de comercio e identificadores técnicos de
+interacciones; no copia datos de clientes, valores de formularios, atribución,
+títulos de página ni texto libre de búsqueda. Los eventos `search` no llevan el término.
+No emitir desde GTM `purchase`, `refund` u `order_placed` basándose en la página de
+gracias: siguen siendo autoritativos del servidor y no se publican en este puente.
+
+GA4, Meta y Clarity nativos permanecen sin cambios. **No repetir esos destinos o
+conversiones dentro del contenedor**. Esta fase no es un modo alternativo completo
+de medición ni realiza deduplicación entre proveedores y etiquetas configuradas
+externamente. El administrador de GTM puede ejecutar scripts con acceso a la página:
+otorgar acceso solo a personas de confianza y revisar cada publicación.
+El aviso de cookies informativo de Bacano no es un CMP y no autoriza las etiquetas;
+el responsable del contenedor debe configurar el consentimiento aplicable.
+
+CSP: permitir `https://www.googletagmanager.com` en `script-src`. Los destinos
+adicionales y Tag Assistant requieren revisar sus propios permisos de CSP; no
+habilitar comodines ni `unsafe-eval` globalmente para acomodar un contenedor.
+
+Referencias: [configuración de GTM](https://support.google.com/tagmanager/answer/14842164)
+y [contrato dataLayer](https://developers.google.com/tag-platform/tag-manager/datalayer).
+
+### Eventos comunes
+
 El storefront expresa hechos mediante `useMarketing().track()`. El SDK decide
-si la medición está activa, sanea la URL y adapta el evento a GA4, Meta y
-Microsoft Clarity. Nunca
+si la medición está activa, sanea la URL y adapta el evento a GA4, Meta,
+Microsoft Clarity y, si se configuró, GTM. Nunca
 se debe llamar directamente a `gtag`, `dataLayer`, `fbq`, Measurement Protocol
 o Conversions API.
 Clarity también se carga desde este runtime; no se instala su snippet de forma

package/STOREFRONT_PAYMENTS.md

@@ -0,0 +1,231 @@
+# Pagos en storefronts Bacano
+
+Contrato canónico para agentes que implementan o auditan pagos con
+`@bacano/sdk`. El storefront presenta las opciones y abre la URL devuelta por
+Bacano; las credenciales, payloads, webhooks, conciliación, inventario y
+contabilidad pertenecen al backend.
+
+## Flujo obligatorio del SDK
+
+1. Consultar `checkout.getPaymentOptions({ fulfillmentFamily })` y mostrar
+   únicamente los métodos retornados por Bacano.
+2. Enviar `paymentMode` y `paymentMethodId` a `checkout.submit()`.
+3. Si el resultado exige pasarela, llamar una sola vez a
+   `checkout.createPaymentSession()` con el `orderId`, `publicOrderToken`,
+   método y una `returnUrl` pública.
+4. Cuando `integrationMode === "redirect"`, navegar inmediatamente a
+   `redirectUrl` con `window.location.assign()`. No insertar una pantalla
+   intermedia de confirmación.
+5. En el retorno, conciliar la sesión existente y después consultar el pedido.
+   Nunca crear otro pedido para reintentar el mismo pago.
+6. Aprobar la compra solo por el estado verificado por Bacano. Los parámetros
+   del navegador y la pantalla del proveedor no son evidencia financiera.
+
+El storefront no construye URLs de Wompi, Mercado Pago, Openpay o Addi, no envía
+credenciales del comercio y no reproduce los payloads privados del proveedor.
+
+### Conciliación segura al regresar del proveedor
+
+La llamada canónica es:
+
+```ts
+await client.checkout.reconcilePaymentSession({
+  orderId,
+  publicOrderToken,
+  paymentSessionId,
+  // Solo si el proveedor devuelve un ID que Bacano espera y verifica.
+  gatewayTransactionId,
+});
+```
+
+- `paymentSessionId` es la referencia estable creada por Bacano y debe viajar
+  en la `returnUrl`.
+- Para **Mercado Pago Orders**, **Openpay** y **Addi**, se omite
+  `gatewayTransactionId`: Bacano recupera el identificador remoto guardado y
+  consulta al proveedor con credenciales del servidor.
+- Para **Wompi**, se envía el ID público de transacción retornado por Wompi;
+  Bacano comprueba que coincida antes de consultar la pasarela.
+- No tratar `payment_id`, `collection_status`, `status`, ni ningún otro
+  parámetro del navegador como evidencia de aprobación. En Mercado Pago,
+  `payment_id` identifica un pago dentro de la Order y no sustituye el ID de
+  Order remoto almacenado por Bacano.
+- Incluso si la conciliación responde con error temporal, consultar el pedido
+  y esperar el estado confirmado mediante `orders.waitForPayment()`; un
+  timeout significa **pendiente**, no rechazado.
+
+## Mercado Pago · contrato vigente
+
+La integración de Bacano usa **Checkout Pro con API de Orders** (`POST
+/v1/orders`), no la API antigua de Preferences. Esta diferencia es crítica:
+una aplicación o payload de Preferences puede autenticar correctamente y aun
+así recibir `403` o `400` al crear la order.
+
+### Configuración del comercio
+
+- Crear o elegir una aplicación en **Mercado Pago Developers** preparada para
+  Checkout Pro y **API de Orders**.
+- En Bacano, **Access Token de la aplicación** significa la credencial privada
+  con la que el backend llama la API. No es la Public Key y tampoco es la firma
+  del webhook.
+- **Firma secreta del Webhook** es un secreto distinto, generado al guardar la
+  configuración de notificaciones en Mercado Pago.
+- Pruebas y producción tienen credenciales diferentes. El ambiente elegido en
+  Bacano debe coincidir con el vendedor/credencial verificado por Mercado Pago.
+- Copiar en Mercado Pago la **URL de notificaciones de Bacano** mostrada en la
+  configuración del método. La ruta identifica la conexión del comercio; no
+  debe inventarse ni compartirse entre configuraciones.
+- Activar el evento **Order (Mercado Pago)** (`orders_v2`). No seleccionar
+  `Pagos (legacy)` como sustituto.
+- Webhook, API pública y `returnUrl` deben ser HTTPS alcanzable. En local se
+  necesita un túnel; `localhost` no sirve para Mercado Pago.
+- La Public Key no se utiliza en este modo de redirección alojada y nunca debe
+  colocarse en el campo Access Token.
+
+No registrar, copiar a código, enviar al navegador ni incluir en capturas el
+Access Token o la firma secreta. Si una credencial queda expuesta, rotarla.
+
+### Formato privado de Orders para Colombia
+
+Este es el contrato del adaptador de Bacano validado contra la API colombiana
+de Orders el 22 de septiembre de 2026. No debe implementarse en el storefront,
+pero un agente que modifique el backend debe preservarlo y volver a probarlo si
+Mercado Pago cambia su esquema.
+
+```json
+{
+  "type": "online",
+  "processing_mode": "manual",
+  "total_amount": "19000",
+  "items": [
+    {
+      "title": "Pedido Bacano",
+      "quantity": 1,
+      "unit_price": "19000"
+    }
+  ],
+  "taxes": [{ "type": "IVA", "value": "0" }]
+}
+```
+
+Reglas que evitaron un rechazo real del proveedor:
+
+- Los montos enviados a Orders son strings de pesos COP enteros: `"19000"`,
+  no `"19000.00"`. Bacano conserva centavos internamente y rechaza fracciones
+  que no pueda representar; nunca redondea silenciosamente.
+- El ítem usa `title`, `quantity` y `unit_price`. En este contrato no enviar
+  `currency_id`, `total_amount` ni `unit_measure` dentro de `items[]`.
+- `taxes[].value` es string, incluso cuando el IVA es cero. No enviarlo como
+  número.
+- Orders rechaza `config.notification_url` en el payload de creación. La URL
+  se registra en **Webhooks** de la aplicación de Mercado Pago y no se repite
+  dentro de cada order.
+- Si existe IVA, `unit_price × quantity + taxes` debe reconciliar exactamente
+  con `total_amount`. El adaptador utiliza el IVA calculado por Bacano; no
+  inventa una tarifa fija.
+- El monto persistido, el total remoto autenticado y el pedido deben coincidir
+  antes de aprobar el pago.
+
+La idempotencia de creación pertenece a Bacano. Tras una respuesta incierta se
+reutiliza el mismo intento y la misma clave; generar una nueva order podría
+producir un cobro duplicado. Un rechazo definitivo de creación (`400`, `401` o
+`403`) cierra esa sesión y permite corregir la configuración sin considerar el
+pedido pagado.
+
+### Diagnóstico rápido
+
+| Síntoma | Interpretación inicial | Acción segura |
+| --- | --- | --- |
+| `MERCADOPAGO_ACCOUNT_ENVIRONMENT_MISMATCH` | La credencial y el ambiente no corresponden | Verificar credencial de prueba/productiva y vendedor; no cambiar el ambiente para ocultarlo |
+| `MERCADOPAGO_HTTP_401` | Access Token inválido, revocado o mal copiado | Rotar/verificar el Access Token de la aplicación |
+| `MERCADOPAGO_HTTP_403` al crear | La cuenta autentica, pero la aplicación no está habilitada para Orders o la operación | Confirmar API de Orders y capacidades de la aplicación |
+| `MERCADOPAGO_HTTP_400` al crear | El proveedor rechazó el payload | Inspeccionar una versión sanitizada del error; nunca imprimir token ni PII |
+| `MERCADOPAGO_RETURN_HTTPS_REQUIRED` | La URL de retorno no es HTTPS pública | Usar dominio publicado o túnel local |
+| `MERCADOPAGO_CHECKOUT_PENDING_RECONCILIATION` | El resultado de creación es incierto | Reintentar la sesión existente; no crear otro pedido |
+
+Un `403` que cambia a `400` después de crear una aplicación de Orders indica
+que la autorización avanzó y ahora debe corregirse el contrato de la solicitud;
+no significa que el Access Token sea la firma del webhook.
+
+## Openpay by BBVA · contrato vigente
+
+Bacano usa el **Webcheckout alojado sin ID de cliente** de Openpay Colombia.
+El storefront no carga Openpay.js ni recibe llaves: crea una sesión Bacano y
+abre el `redirectUrl` validado que devuelve el backend.
+
+### Configuración del comercio
+
+- Registrar en Bacano el **ID del comercio** y la **llave privada** del mismo
+  ambiente. La llave pública no participa en Webcheckout server-to-server.
+- Sandbox usa `https://sandbox-api.openpay.co`; producción usa
+  `https://api.openpay.co`. Bacano fija esos orígenes y no acepta una URL de API
+  suministrada por el comercio.
+- La API pública de Bacano debe ser HTTPS. Al guardar, Bacano registra el
+  webhook en Openpay con credenciales Basic generadas internamente y completa
+  la verificación que Openpay envía al endpoint. No se copian esas credenciales
+  al storefront ni se solicitan al usuario.
+- El método queda guardado aunque falle la provisión remota del webhook; la
+  interfaz reporta el error y permite reintentar la misma conexión. No se
+  ofrece en el checkout hasta que el webhook figure verificado.
+
+Referencia oficial: [API Openpay Colombia](https://documents.openpay.co/api/index.html).
+
+### Creación, recuperación y confirmación
+
+- `POST /v1/{MERCHANT_ID}/checkouts` recibe monto entero COP, `iva` string,
+  referencia única, comprador, retorno HTTPS y una expiración anterior a la
+  expiración local de la sesión.
+- Bacano persiste primero sesión, payload y snapshot cifrado de credenciales.
+  El primer intento crea directamente el checkout. Tras un timeout, primero
+  busca la misma referencia; si Openpay responde duplicado `1006`, recupera el
+  checkout existente. Nunca genera otra referencia para un reintento técnico.
+- Solo se redirige a un link HTTPS del host exacto de Openpay y ruta `/ck/...`.
+- El retorno y el webhook son señales para conciliar. Bacano consulta cargos
+  con la llave privada y exige igualdad de referencia, moneda e importe antes
+  de aprobar. Campos adicionales del webhook o del navegador no se registran
+  como evidencia financiera.
+- Un cargo `failed` o `cancelled` no cierra por sí solo la sesión mientras el
+  checkout alojado siga disponible: el comprador puede probar otro medio. Un
+  cargo posterior `completed` aprueba si es el único aprobado y todos los demás
+  cargos son fallidos o cancelados. Cargos simultáneos pendientes, más de un
+  aprobado, reembolsos, contracargos o discrepancias pasan a revisión manual.
+- El retorno al sitio no declara vencida una sesión remota por la hora local;
+  solo permite reintentar cuando el proveedor confirma el cierre del checkout.
+
+El comprador usa los medios habilitados por Openpay dentro de su página
+alojada; el SDK no pide tarjeta, PSE ni efectivo de forma separada.
+
+### Diagnóstico rápido
+
+| Síntoma | Acción segura |
+| --- | --- |
+| `OPENPAY_CREDENTIALS_REQUIRED` | Ingresar la llave privada; no la llave pública |
+| `OPENPAY_MERCHANT_ID_REQUIRED` | Copiar el ID del comercio del mismo ambiente |
+| `OPENPAY_HTTP_401` / `OPENPAY_HTTP_403` | Verificar pareja comercio/llave y sandbox/producción |
+| `OPENPAY_PUBLIC_HTTPS_REQUIRED` | Publicar la API Bacano por HTTPS antes de registrar el webhook |
+| `OPENPAY_CHECKOUT_PENDING_RECONCILIATION` | Reutilizar la sesión y consultar; no crear otro pedido |
+| `OPENPAY_*_REVIEW_REQUIRED` | No aprobar ni reintentar con otra referencia; revisar la evidencia |
+
+## Reglas específicas visibles
+
+- Addi puede exigir CC y datos de contacto/residencia. Mostrar esos campos solo
+  cuando el método retornado tenga `gatewayCode === "ADDI"`; la evaluación de
+  crédito ocurre en Addi.
+- El storefront debe usar el texto del modo seleccionado: para `pay_now`, el
+  botón principal comunica **Pagar ahora**, no solo **Confirmar pedido**.
+- Recargos, impuestos, descuentos, envío y total final siempre vienen de
+  Bacano. El storefront no los recalcula ni altera el monto de la pasarela.
+- Los secretos vacíos al editar una conexión significan conservar los
+  existentes; nunca intentar precargarlos en el navegador.
+
+## Prueba mínima antes de publicar
+
+- Ejecutar un pago sandbox completo por cada pasarela activa, no solo validar
+  el formulario de configuración.
+- Confirmar redirección inmediata al checkout alojado.
+- Probar aprobación, rechazo, retorno, refresco, doble clic y reintento.
+- Confirmar que el webhook responde, que Bacano consulta el recurso autenticado
+  y que repetir el evento no duplica pago, pedido, inventario ni conversión.
+- Verificar el pedido desde `orders.getPublicOrder()` o
+  `orders.waitForPayment()`; no desde parámetros de retorno.
+- Si el flujo real no se ejecutó, reportarlo como **NO VERIFICADO**, nunca como
+  listo para producción.

package/client.d.ts

@@ -1,5 +1,7 @@
+import { type FlowsClient } from "./flows";
 import type { BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogCategoryList, CatalogPageResult, CheckoutResult, CheckoutSubmission, ContentEntry, CustomerAddress, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCatalogPageOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductRecommendationsOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, Order, Product, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductRecommendationsResult, ProductSeoEntriesResult, ProductVariantLiveState, PublicOrder, PublicOrderLookupInput, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, WaitForPublicOrderPaymentInput, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteFormResponseInput, WebsiteFormResponseResult, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLocationOptions, WebsitePaymentMethod, WebsitePaymentOption, WebsitePaymentSessionResult, WebsitePublishedForm, WebsiteShippingPolicy, WebsiteShippingQuote } from "./types";
 export interface BacanoClient {
+    flows: FlowsClient;
     /** Initialize the client and resolve its website context. */
     init(): Promise<void>;
     /** Get the resolved website context (company_id, chain_id, etc.) */
@@ -89,7 +91,12 @@ export interface BacanoClient {
             orderId: string;
             publicOrderToken: string;
             paymentSessionId: string;
-            gatewayTransactionId: string;
+            /**
+             * Provider transaction returned to the browser. Required by providers
+             * such as Wompi; omit it for Mercado Pago Orders and Addi, which Bacano
+             * reconciles server-side from the stored payment session.
+             */
+            gatewayTransactionId?: string;
         }): Promise<WebsitePaymentSessionResult>;
     };
     orders: {