ISTMO COMMERCE / GUÍA

Primeros pasos

Del aprovisionamiento de la tienda a la primera solicitud.

1. Identifica el servidor operativo

La base de la API es https://TU-SERVIDOR-POS/api/v1/commerce. El dominio de esta documentación no es la URL de la API. cloud-api administra licencias; Commerce se ejecuta en pos-server, tanto local como cloud-pos.

Para instalaciones locales, localhost e IP privadas no son accesibles desde Vercel. Consulta la guía local/cloud antes de configurar el backend.

Instalaciones locales y cloud

2. Crea una integración

Un administrador del POS crea la integración con su JWT vigente. El servidor comprueba el permiso actual admin.configuracion o un rol superadmin activo, pertenencia a la sucursal y licencia POS/facturación. Empresa y sucursal se derivan de la identidad autenticada.

json

{
  "nombre": "Mi tienda",
  "sitioUrl": "https://tienda.example.com",
  "almacenId": "11111111-1111-4111-8111-111111111111",
  "numeroLista": 1,
  "scopes": [
    "catalog:read",
    "orders:write",
    "orders:read"
  ]
}

Enviar a POST /admin/integrations. El UUID es ilustrativo: usar un almacén real de la sucursal. Guardar data.id y data.credential; la credencial se devuelve una sola vez. Si se pierde la respuesta, listar antes de repetir y rotar si se perdió la clave.

3. Publica una selección

PUT /admin/integrations/{id}/products reemplaza toda la selección mediante {"productoIds":["UUID-REAL"]}. Una lista vacía despublica todo. Se admiten hasta 200 productos simples activos con precio en USD en la lista seleccionada.

No se publican automáticamente todos los productos. Esta versión excluye servicios, variantes, lotes, seriales, compuestos y precio libre. No incluye fotos.

4. Consulta desde el backend

Guardar la credencial sólo en el servidor de la tienda. Nunca en variables VITE_, código Vue, localStorage o parámetros de URL. El secreto identifica una integración, no autentica a cada comprador.

bash

curl "https://TU-SERVIDOR-POS/api/v1/commerce/catalog?limit=50" \
  -H "x-istmo-commerce-key: $ISTMO_COMMERCE_KEY"

Implementar con Vue y Vercel

Precios y disponibilidad

unitPriceReference es texto decimal con cuatro posiciones: precio de lista referencial, no cotización fiscal ni total a cobrar.
availableReference es max(0, existencia − reservada) del almacén autorizado. No garantiza disponibilidad ni reserva.
No calcular impuestos, envío o cobros a partir del precio de referencia. Para cotizar y reservar usar checkout-commands.
Paginación: usar limit (1–100) y after=nextCursor. El cursor ordena UUID, no es una fecha ni un mecanismo de sincronización incremental.