Documentación de la API

Una API REST para que tu propio sistema — un flujo de n8n, un asistente de WhatsApp, tu backend, o cualquier cliente HTTP — lea los datos de tu negocio (inventario, contactos) y también cree información: cargar productos en bloque o registrar un pedido directamente. Cada organización se autentica con su propia API key, así que solo puedes ver y modificar los datos de tu propia empresa.

Cómo generar tu API key

Desde el panel, ve a Ajustes → API, ponle un nombre a tu key (por ejemplo "Integración n8n") y créala. El valor completo se muestra una sola vez — cópialo de inmediato, porque después solo verás los primeros caracteres para identificarla. Si la pierdes, revócala y crea una nueva; no hay forma de recuperarla.

Puedes crear varias API keys (una por integración) y revocar cualquiera en cualquier momento sin afectar a las demás — revocar no borra su historial, solo deja de aceptarla en nuevas peticiones.

Autenticación

Envía tu API key en el header Authorization con el esquema Bearer, en cada petición:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Si tu cliente no permite personalizar el header Authorization (algunas herramientas low-code lo hacen difícil), también aceptamos X-Api-Key: sk_live_... como alternativa.

Una petición sin key válida responde 401, y una key revocada responde 403:

{
  "error": {
    "message": "API key inválida.",
    "status": 401
  }
}

Referencia de endpoints

Todos los endpoints viven bajo /api/v1, solo devuelven datos de la organización dueña de la API key, y los que listan varios registros aceptan ?page= y ?limit= (máximo 100 por página).

GET/api/v1/products

Listar inventario

Todo el catálogo de la organización — productos con sus variantes, stock disponible y precio. Pensado para que un flujo de n8n consulte el inventario completo por HTTP en lugar de depender de una hoja de cálculo.

Parámetro	Tipo	Descripción
page	integer	Página a consultar. Por defecto 1.
limit	integer	Resultados por página. Por defecto 25, máximo 100.
category	string	Filtra por el nombre exacto de la categoría (sin distinguir mayúsculas/minúsculas) — útil para que un flujo dedicado a una sola línea, ej. "Camisas Hombre", solo vea ese inventario.
sku	string	Filtra al producto dueño de esa variante — para revisar un código puntual.

Request

curl "https://tu-crm.com/api/v1/products?category=Camisas%20Hombre&limit=2" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "data": [
    {
      "id": "clx1a2b3c",
      "name": "Camiseta Oversize",
      "sku": "CAM-001",
      "priceCents": 89900,
      "currency": "COP",
      "isActive": true,
      "status": "ACTIVO",
      "category": { "id": "clxcat1", "name": "Camisetas" },
      "variants": [
        {
          "id": "clxvar1",
          "name": "Negro / M",
          "sku": "CAM-001-NEG-M",
          "color": "Negro",
          "size": "M",
          "priceCents": 89900,
          "stock": 12,
          "reservedStock": 2,
          "availableStock": 10
        }
      ],
      "createdAt": "2026-08-01T10:00:00.000Z",
      "updatedAt": "2026-08-20T15:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 2, "total": 48, "totalPages": 24 }
}

POST/api/v1/products

Crear un producto (cargar inventario)

Crea un producto nuevo, con sus variantes (color/talla/stock) si las tiene. Pensado para cargar inventario en bloque desde una hoja de cálculo o un sistema externo vía n8n. Los precios van en pesos completos (75000), no en centavos. Si mandas un sku (de producto o de variante) que ya existe, responde 409 en vez de duplicar — así un reintento de n8n no crea el mismo producto dos veces.

Request

curl -X POST https://tu-crm.com/api/v1/products \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camisa Cargo Hombre",
    "categoryName": "Camisas Hombre",
    "price": 75000,
    "variants": [
      { "color": "Azul", "colorHex": "#2563eb", "size": "M", "stock": 12 },
      { "color": "Azul", "colorHex": "#2563eb", "size": "L", "stock": 8 },
      { "color": "Negro", "colorHex": "#111111", "size": "M", "stock": 10 }
    ]
  }'

Response 200

{
  "data": {
    "id": "clx1a2b3c",
    "name": "Camisa Cargo Hombre",
    "priceCents": 7500000,
    "categoryId": "clxcat1",
    "variants": [
      { "id": "clxvar1", "sku": "CMCR-AZU-M-001", "stock": 12 },
      { "id": "clxvar2", "sku": "CMCR-AZU-L-002", "stock": 8 },
      { "id": "clxvar3", "sku": "CMCR-NEG-M-003", "stock": 10 }
    ]
  }
}

GET/api/v1/products/:id

Consultar un producto

Un producto puntual, con el mismo detalle de variantes que la lista.

Parámetro	Tipo	Descripción
id	string (en la URL)	Id del producto.

Request

curl https://tu-crm.com/api/v1/products/clx1a2b3c \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "data": {
    "id": "clx1a2b3c",
    "name": "Camiseta Oversize",
    "sku": "CAM-001",
    "priceCents": 89900,
    "currency": "COP",
    "isActive": true,
    "status": "ACTIVO",
    "category": { "id": "clxcat1", "name": "Camisetas" },
    "variants": [
      {
        "id": "clxvar1",
        "name": "Negro / M",
        "color": "Negro",
        "size": "M",
        "priceCents": 89900,
        "stock": 12,
        "reservedStock": 2,
        "availableStock": 10
      }
    ]
  }
}

GET/api/v1/contacts

Listar contactos

Los contactos de tu CRM, paginados, más recientes primero.

Parámetro	Tipo	Descripción
page	integer	Página a consultar. Por defecto 1.
limit	integer	Resultados por página. Por defecto 25, máximo 100.

Request

curl https://tu-crm.com/api/v1/contacts \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "data": [
    {
      "id": "clxctc1",
      "firstName": "Laura",
      "lastName": "Gómez",
      "email": "laura@example.com",
      "phone": "+573001234567",
      "city": "Bogotá",
      "customerType": "DETAL",
      "company": null,
      "createdAt": "2026-08-10T09:00:00.000Z",
      "updatedAt": "2026-08-10T09:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 3, "totalPages": 1 }
}

POST/api/v1/orders

Crear un pedido

Envía Idempotency-Key (máximo 200 caracteres) con un identificador estable del intento de compra. Los reintentos con la misma clave, empresa, llave de API y cuerpo devuelven el mismo pedido con HTTP 201. Si reutilizas la clave con otro cuerpo, la API responde HTTP 409. Sin la cabecera, cada POST crea un pedido nuevo.

Request

curl -X POST https://tu-crm.com/api/v1/orders \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "sku": "CMCR-AZU-M-001", "quantity": 2 }
    ],
    "customer": {
      "name": "María Pérez",
      "phone": "3001234567",
      "address": "Cra 45 #12-34",
      "city": "Medellín"
    },
    "paymentMethod": "CONTRA_ENTREGA",
    "notes": "Pidió que llegue después de las 3pm"
  }'

Response 200

{
  "data": {
    "id": "clxord1",
    "number": 214,
    "status": "NUEVO",
    "paymentMethod": "CONTRA_ENTREGA"
  }
}

Preguntas frecuentes

¿Puedo ver los datos de otra organización con mi API key?

No. Cada API key queda ligada a una sola organización desde el momento en que la creas; ningún endpoint acepta un id de organización por parámetro.

¿Qué pasa si pierdo mi API key?

No hay forma de volver a verla. Revócala desde Ajustes → API y crea una nueva.

¿Hay límite de peticiones?

Por ahora no hay un límite explícito de tasa (rate limit), pero cada endpoint que lista varios registros está paginado — no dependas de recibir todo el inventario en una sola respuesta.