> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatizar tickets de Comercio

> Inspecciona compras y gestiona entregas o conciliaciones verificadas con concurrencia independiente.

Comercio es un origen de tickets generales. El sistema crea un elemento abierto por compra/ciclo de revisión para entregas e incidencias elegibles de reservas. La creación manual sigue requiriendo conversación; `create_ticket` no crea tickets arbitrarios vinculados solo a una compra.

## Descubrir e inspeccionar

Usa `list_tickets` con `includeCommerce=true` y, opcionalmente, `source=commerce`, `purchaseId`, estado y responsable. Los conteos respetan el mismo alcance y modo. Los listados y streams heredados o predeterminados excluyen Comercio sin opt-in explícito.

Las filas contienen referencias sin leer la compra por cada elemento. Consulta `get_ticket` para `commerce.contextStatus` y, cuando se permita, `commerce.review`:

* `contextStatus`: `available`, `permission_denied` o `unavailable`. La evidencia requiere `commerce:sales:read`, además de visibilidad del ticket.
* Identidad: tenant, compra, `stripeMode`, motivo y ciclo; la conversación es opcional.
* Hechos actuales: pago, entrega, reembolso, reserva, importe en unidades menores, moneda, IDs de reservas del proveedor, conciliación y último comando cuando existan.
* Vigencia y concurrencia: `asOf`, revisión del estado de Comercio y `sourceVersion` opaco.
* Comandos permitidos: `permittedActions` (`fulfill`, `reconcile`) y, por separado, `humanActions` (`refund`, `retry_reservation`, `payout`).

`bookingConfirmed` exige un estado exitoso del proveedor y los identificadores guardados requeridos. Pagar o registrar una conciliación externa no lo establece en true. `historical` identifica evidencia histórica; los registros financieros son inmutables.

## Dos dominios de concurrencia

| Cambio | Token requerido | Idempotencia |
| - | - | - |
| Título, descripción, asignación, inicio y notas del ticket | `revision` entero del ticket | La creación requiere clave; los demás comandos usan revisiones. |
| Entrega de compra o conciliación no financiera | `sourceVersion` hexadecimal de 64 caracteres de la evidencia actual | `Idempotency-Key` para cada intención. |

No sustituyas el token de Comercio por la revisión del ticket. Inspecciona evidencia reciente antes de decidir un comando.

## Actualizar entrega

`PATCH /commerce/sales/{saleId}/fulfillment` requiere `commerce:sales:read` y `commerce:sales:fulfillment:write`. El cuerpo contiene `sourceVersion` y `fulfillmentStatus` (`fulfilled` o `unfulfilled`). Úsalo solo cuando esté permitido para la compra.

Herramienta MCP `update_commerce_sale_fulfillment`:

```json theme={null}
{"saleId":"YOUR_PURCHASE_ID","idempotencyKey":"fulfill-basket-01","input":{"sourceVersion":"COPY_THE_CURRENT_64_CHARACTER_HEX_TOKEN","fulfillmentStatus":"fulfilled"}}
```

El token anterior es un marcador, no un valor válido. Sustitúyelo por el `sourceVersion` exacto devuelto. La entrega registra el estado admitido de la compra; no fabrica confirmaciones de reserva, pagos ni mensajes.

## Registrar una conciliación verificada

`POST /commerce/sales/{saleId}/reconciliation` requiere `commerce:sales:read` y `commerce:sales:reconciliation:write`.

| Campo | Requisito |
| - | - |
| `sourceVersion` | Token reciente de Comercio |
| `outcome` | `completed_externally` o `verified_no_action_required` |
| `reference` | Referencia de respaldo, 1–500 caracteres |
| `note` | Explicación que verifica la incidencia actual, 1–1.000 caracteres |

Herramienta MCP `reconcile_commerce_sale`:

```json theme={null}
{"saleId":"YOUR_PURCHASE_ID","idempotencyKey":"reconcile-class-01","input":{"sourceVersion":"COPY_THE_CURRENT_64_CHARACTER_HEX_TOKEN","outcome":"completed_externally","reference":"studio-register-DEMO-042","note":"Front desk verified attendance against the studio register."}}
```

El servicio guarda un registro independiente atribuido a la credencial/autorización. No reescribe registros financieros ni presenta un resultado externo como éxito confirmado por el proveedor. Se conservan las aprobaciones del Agente integrado. Reembolsos, payouts y reintentos de reservas siguen siendo humanos en esta versión; estas dos herramientas no los ofrecen.

## Finalización y recuperación

Resolver y Cancelar genéricamente rechazan trabajo de Comercio. Los resultados válidos son entrega rutinaria completada, reembolso total confirmado, evidencia de reserva exitosa o conciliación verificada de la incidencia actual. Lo pendiente, parcial, fallido o incierto permanece abierto. El sistema puede cancelar obligaciones obsoletas con un motivo auditado.

Lee el estado devuelto de Comercio y el ticket exacto tras el cambio. La sincronización es asíncrona: un comando exitoso no prueba que la proyección del ticket haya avanzado. Usa recuperación por eventos y verificación acotada; no añadas polling continuo.

Ante token obsoleto (409), inspecciona evidencia actual y reconsidera. Ante comando incierto, revisa `lastCommand`, conciliación, hechos y ciclo antes de repetir la intención idéntica con la misma clave. Otro payload es otra intención y requiere otra clave. No cambies claves para sortear incertidumbre.

Los cambios actualizan el motivo del ticket abierto conservando responsable y texto editado. Una incidencia nueva que requiere acción después del cierre crea otro ciclo vinculado y conserva el terminal. Los metadatos de saldo o transferencia por sí solos no crean una incidencia. Los eventos duplicados o fuera de orden no sustituyen resultados más recientes.

## Autorización y eventos

Descubrimiento, conteos, referencias, comandos y entregas quedan aislados por espacio de trabajo y modo test/live. Las autorizaciones existentes no ganan scopes. Asignar, iniciar y anotar conservan permisos de ticket; los cambios humanos de Comercio conservan su requisito de administrador.

Suscríbete a `ticket.created` / `ticket.updated` con `includeCommerce=true`. Los eventos de compras sin conversación omiten sus IDs. Deduplica `eventId`, compara revisión y consulta estado actual antes de actuar. La entrega verifica modo, opt-in y autorización. Consulta [webhooks](https://docs.visitoai.com/es/api-docs/webhooks.md) y la [matriz completa](https://docs.visitoai.com/es/api-docs/tickets.md#rutas-herramientas-y-permisos).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.