API de Commerce

Usa la API de Commerce desde tu backend para administrar items vendibles y sincronizar ventas con tus propios sistemas. Todos los endpoints usan la URL base M2M:

https://platform-api.visitoai.com/m2m/v1

Las credenciales M2M son secretos de servidor. No llames estos endpoints desde navegador, móvil ni widgets incrustados.

Scopes

Scope	Permite
`commerce:items:read`	Listar e inspeccionar items del catálogo.
`commerce:items:write`	Crear, actualizar, asignar scope y eliminar items del catálogo.
`commerce:sales:read`	Listar e inspeccionar ventas.

Las rutas de commerce usan el tenant asociado a la credencial M2M. No envíes tenantId en path ni query string.

Modelo de item

{
  "itemId": "item_123",
  "tenantId": "tenant_123",
  "name": "Late checkout",
  "description": "Extender checkout hasta las 2pm",
  "amountMinor": 2500,
  "currency": "usd",
  "active": true,
  "scope": "global",
  "allowQuantity": false,
  "minQuantity": 1,
  "maxQuantity": 1,
  "fields": [],
  "createdAt": "2026-08-18T12:00:00.000Z",
  "updatedAt": "2026-08-18T12:00:00.000Z"
}

scope es global salvo que el item esté asignado a un negocio. Los items por negocio incluyen propertyId.

Listar items

GET /m2m/v1/commerce/items HTTP/1.1
Authorization: Bearer visito_m2m_...

Requiere commerce:items:read.

{
  "items": []
}

Crear un item

POST /m2m/v1/commerce/items HTTP/1.1
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requiere commerce:items:write.

{
  "name": "Late checkout",
  "description": "Extender checkout hasta las 2pm",
  "amountMinor": 2500,
  "currency": "usd",
  "active": true,
  "allowQuantity": false,
  "fields": [
    {
      "label": "Nombre del cliente",
      "type": "text",
      "required": true
    }
  ]
}

Respuesta:

{
  "item": {}
}

Tipos de campo soportados: text, number, email, phone, date y select.

Consultar un item

GET /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...

Requiere commerce:items:read.

Actualizar un item

PATCH /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requiere commerce:items:write. Envía solo los campos que quieras cambiar.

{
  "name": "Late checkout plus",
  "amountMinor": 3000,
  "active": true
}

Asignar scope de item

PATCH /m2m/v1/commerce/items/{itemId}/property
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requiere commerce:items:write. Asignar el item a un negocio activo:

{
  "propertyId": "property_123"
}

Hacer el item global:

{
  "propertyId": null
}

Respuesta:

{
  "itemId": "item_123",
  "scope": "property",
  "propertyId": "property_123"
}

Eliminar un item

DELETE /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...

Requiere commerce:items:write.

{
  "deleted": true
}

Ventas

Las ventas son compras de commerce expuestas con nombres de ruta orientados a sistemas externos.

Listar ventas

GET /m2m/v1/commerce/sales?status=paid&limit=50 HTTP/1.1
Authorization: Bearer visito_m2m_...

Requiere commerce:sales:read. Query parameters:

Parámetro	Valores
`limit`	`1` a `200`, default `50`
`cursor`	Cursor opaco de la respuesta anterior
`status`	`pending`, `paid`, `payment_failed`, `refunded`, `canceled`
`fulfillmentStatus`	`unfulfilled`, `fulfilled`

Respuesta:

{
  "sales": [
    {
      "purchaseId": "purchase_01JY8Q4W9F3C2M7N6K5H1G0D8A",
      "tenantId": "tenant_123",
      "purchaseKind": "catalog_item",
      "itemId": "item_123",
      "itemName": "Consulta inicial",
      "scope": "global",
      "quantity": 1,
      "unitAmountMinor": 5000,
      "totalAmountMinor": 5000,
      "amountMinor": 5000,
      "currency": "usd",
      "status": "paid",
      "fulfillmentStatus": "unfulfilled",
      "transferStatus": "transferred",
      "refundStatus": "none",
      "capturedFields": {
        "customer_name": "Sofia Reyes",
        "customer_email": "sofia@example.com"
      },
      "paidAt": "2026-08-31T18:42:17.000Z",
      "createdAt": "2026-08-31T18:40:02.000Z",
      "updatedAt": "2026-08-31T18:42:18.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA4LTMxVDE4OjQwOjAyLjAwMFoifQ"
}

Consultar una venta

GET /m2m/v1/commerce/sales/{saleId}
Authorization: Bearer visito_m2m_...

Requiere commerce:sales:read.

{
  "sale": {
    "purchaseId": "purchase_01JY8Q4W9F3C2M7N6K5H1G0D8A",
    "tenantId": "tenant_123",
    "stripeMode": "live",
    "purchaseKind": "catalog_item",
    "conversationId": "conversation_123",
    "conversationKey": "whatsapp:+525512345678",
    "itemId": "item_123",
    "itemName": "Consulta inicial",
    "scope": "global",
    "quantity": 1,
    "unitAmountMinor": 5000,
    "totalAmountMinor": 5000,
    "amountMinor": 5000,
    "currency": "usd",
    "status": "paid",
    "fulfillmentStatus": "unfulfilled",
    "transferStatus": "transferred",
    "refundStatus": "none",
    "capturedFields": {
      "customer_name": "Sofia Reyes",
      "customer_email": "sofia@example.com"
    },
    "checkoutSessionId": "cs_live_123",
    "paymentIntentId": "pi_123",
    "connectedAccountId": "acct_123",
    "platformFeeBps": 1000,
    "transferId": "tr_123",
    "proofUrl": "https://example.com/commerce/proof/purchase_01JY8Q4W9F3C2M7N6K5H1G0D8A",
    "paidAt": "2026-08-31T18:42:17.000Z",
    "createdAt": "2026-08-31T18:40:02.000Z",
    "updatedAt": "2026-08-31T18:42:18.000Z"
  }
}

Los endpoints de lista y detalle devuelven la misma estructura de venta. Los campos opcionales se omiten cuando no aplican o todavía no están disponibles.

Grupo	Campos
Identidad	`purchaseId` (también se usa como `{saleId}`), `tenantId`, `purchaseKind`
Conversación	`conversationId`, `conversationKey`
Item y alcance	`itemId`, `itemName`, `scope`, `propertyId`
Importes	`quantity`, `unitAmountMinor`, `totalAmountMinor`, `amountMinor`, `currency`
Estado	`status`, `fulfillmentStatus`, `fulfilledAt`, `fulfilledBy`
Checkout	`capturedFields`, `checkoutSessionId`, `checkoutUrl`, `paymentIntentId`
Transferencias	`connectedAccountId`, `platformFeeBps`, `transferStatus`, `transferId`, `transferError`, `balance`
Reembolsos	`refundStatus`, `refundId`, `refundAmountMinor`, `refundCurrency`, `refundReason`, `refundRequestedBy`, `refundRequestedAt`, `refundError`, campos de reversión y `refundedAt`
Detalles por tipo	`reservation` solo aparece en ventas compatibles de depósito de reserva
Auditoría	`proofUrl`, `paidAt`, `createdAt`, `updatedAt`

Todos los campos monetarios que terminan en Minor usan la unidad menor de la moneda. Por ejemplo, 5000 con currency: "usd" equivale a USD 50.00. capturedFields contiene los valores recopilados de los campos del item configurados para el checkout.

Desarrollar con Visito

Asistentes de programación con IA

Scopes

Modelo de item

Listar items

Crear un item

Consultar un item

Actualizar un item

Asignar scope de item

Eliminar un item

Ventas

Listar ventas

Consultar una venta

​Scopes

​Modelo de item

​Listar items

​Crear un item

​Consultar un item

​Actualizar un item

​Asignar scope de item

​Eliminar un item

​Ventas

​Listar ventas

​Consultar una venta

Scopes

Modelo de item

Listar items

Crear un item

Consultar un item

Actualizar un item

Asignar scope de item

Eliminar un item

Ventas

Listar ventas

Consultar una venta