> ## 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.

# API de Commerce

> Administra items del catálogo de commerce y consulta ventas mediante la API M2M de Visito.

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:

```bash theme={null}
https://platform-api.visitoai.com/m2m/v1
```

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

## 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

```json theme={null}
{
  "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 una propiedad. Los items por propiedad incluyen `propertyId`.

## Listar items

```http theme={null}
GET /m2m/v1/commerce/items HTTP/1.1
Authorization: Bearer visito_m2m_...
```

Requiere `commerce:items:read`.

```json theme={null}
{
  "items": []
}
```

## Crear un item

```http theme={null}
POST /m2m/v1/commerce/items HTTP/1.1
Authorization: Bearer visito_m2m_...
Content-Type: application/json
```

Requiere `commerce:items:write`.

```json theme={null}
{
  "name": "Late checkout",
  "description": "Extender checkout hasta las 2pm",
  "amountMinor": 2500,
  "currency": "usd",
  "active": true,
  "allowQuantity": false,
  "fields": [
    {
      "label": "Nombre del huésped",
      "type": "text",
      "required": true
    }
  ]
}
```

Respuesta:

```json theme={null}
{
  "item": {}
}
```

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

## Consultar un item

```http theme={null}
GET /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...
```

Requiere `commerce:items:read`.

## Actualizar un item

```http theme={null}
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.

```json theme={null}
{
  "name": "Late checkout plus",
  "amountMinor": 3000,
  "active": true
}
```

## Asignar scope de item

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

Requiere `commerce:items:write`.

Asignar el item a una propiedad activa:

```json theme={null}
{
  "propertyId": "property_123"
}
```

Hacer el item global:

```json theme={null}
{
  "propertyId": null
}
```

Respuesta:

```json theme={null}
{
  "itemId": "item_123",
  "scope": "property",
  "propertyId": "property_123"
}
```

## Eliminar un item

```http theme={null}
DELETE /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...
```

Requiere `commerce:items:write`.

```json theme={null}
{
  "deleted": true
}
```

## Ventas

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

### Listar ventas

```http theme={null}
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:

```json theme={null}
{
  "sales": [],
  "hasMore": false,
  "nextCursor": null
}
```

### Consultar una venta

```http theme={null}
GET /m2m/v1/commerce/sales/{saleId}
Authorization: Bearer visito_m2m_...
```

Requiere `commerce:sales:read`.

```json theme={null}
{
  "sale": {}
}
```

Los objetos de venta incluyen estado de pago, fulfillment, campos de transfer/refund, datos capturados en checkout, conversación vinculada cuando exista, y detalles de reservación para pagos de depósito.