Saltar al contenido principal
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

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:
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. Herramienta MCP reconcile_commerce_sale:
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 y la matriz completa.