Integración con ERP

Conecta tu ERP con Admin API: crea productos con variantes, ajusta el stock de cada una y recibe los pedidos nuevos.

Requisitos

• Una app con la conexión Desde tu servidor y su client_id y client_secret en tu servidor. Ver Inicio rápido.
• Los permisos catalog:create, inventory:read e inventory:update. La plantilla ERP completo los incluye.

Pide un token

Pide el token con client_credentials y el scope api_admin. La app está vinculada a la tienda, así que el token ya la identifica. Guárdalo en caché y renuévalo antes de que venza.

curl -X POST https://auth.ecomiq.pe/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$ECOMIQ_CLIENT_ID" \
  -d "client_secret=$ECOMIQ_CLIENT_SECRET" \
  -d "scope=api_admin"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600
}

expires_in es la vigencia en segundos. Los ejemplos siguientes usan getToken(). Más detalle en Autenticación.

Crea un producto

Declara las opciones en options y una variante por combinación en variants. Cada variante indica en options su valor para cada opción.

{
  "name": "Polo clásico",
  "description": "Polo unisex disponible en varios colores y tallas.",
  "status": "active",
  "isDigital": false,
  "options": [
    { "name": "Color", "key": "color", "values": ["Azul", "Blanco"] },
    { "name": "Talla", "key": "talla", "values": ["M", "L"] }
  ],
  "variants": [
    {
      "name": "Azul / M",
      "sku": "POL-CL-AZ-M",
      "price": 89,
      "trackInventory": true,
      "options": { "Color": "Azul", "Talla": "M" },
      "isDefault": true
    },
    {
      "name": "Blanco / L",
      "sku": "POL-CL-BL-L",
      "price": 89,
      "trackInventory": true,
      "options": { "Color": "Blanco", "Talla": "L" },
      "isDefault": false
    }
  ]
}

curl -X POST https://api.ecomiq.pe/api/v1/catalog/products \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  --data @producto.json

La API responde 201 con el producto y sus variantes. Guarda el id de cada variante junto a su SKU; los IDs son strings. Campos completos en Crear producto.

Lee el stock

POST /v1/inventory/levels devuelve el stock de las variantes en cada ubicación. Cada fila trae locationId, onHand, available y version.

curl -X POST https://api.ecomiq.pe/api/v1/inventory/levels \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "variantIds": ["7204558912004325377"] }'

Los IDs de tus ubicaciones están en Listar ubicaciones logísticas.

Ajusta el stock

Envía la variante, la ubicación, la cantidad y el motivo. mode: "adjust" suma la cantidad al stock actual; mode: "set" la fija. En expectedVersion envía la version leída, o 0 si la variante aún no tiene nivel en esa ubicación.

curl -X POST https://api.ecomiq.pe/api/v1/inventory/adjust \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variantId": "7204558912004325377",
    "locationId": "7204558912004325378",
    "target": "onHand",
    "mode": "adjust",
    "quantity": 5,
    "reason": "restock",
    "note": "Ingreso de cinco unidades.",
    "expectedVersion": 3
  }'

La respuesta trae el nivel con la nueva version. Si la versión que enviaste ya cambió, la API responde 409 Inventory.Changed: lee el stock otra vez y reintenta. Para muchas variantes a la vez, usa Actualizar existencias en lote.

Recibe pedidos

Suscribe un endpoint de tu ERP al evento order.created. Llega uno por cada pedido nuevo. Sigue Pedidos entrantes.

Errores

Siguientes pasos

• Pedidos entrantes: recibe y verifica cada pedido nuevo.
• Inventario: varias ubicaciones, conflictos y lotes.
• Errores: formatos y cuándo reintentar.