Crea 500 códigos desde tu ERP

Un código por producto, estante, habitación o activo, creado desde el sistema que ya los conoce. Esta guía crea un lote, obtiene los diseños para imprimir y muestra cómo mantenerlo al día.

Antes de empezarCopiar link a esta sección

• Una clave de Lectura y escritura de Configuración, Desarrolladores.
• Opcional: un design. { "kind": "template", "templateId": "..." } copia una plantilla guardada de GET /templates, { "kind": "brand" } usa tu Brand Kit y { "kind": "auto" } lee los colores del sitio web de la primera fila. Sin él, los códigos son negro sobre blanco simple. Consulta Códigos diseñados.
• El límite de lote del plan: 100 filas en PRO y 500 en Business (GET /me lo informa como limits.bulkBatch). Un lote también tiene que caber dentro del límite de códigos activos del espacio de trabajo.

1. Arma las filasCopiar link a esta sección

Una fila por código. name y url son obligatorios; tags, utm y gps son opcionales. Pon en el nombre el identificador que usa tu sistema y, si el destino debe conocerlo, también en la URL.

{
  "rows": [
    { "name": "SKU 10432 Espresso beans 250 g", "url": "https://shop.example.com/p/10432", "tags": ["beans", "retail"] },
    { "name": "SKU 10433 Espresso beans 1 kg", "url": "https://shop.example.com/p/10433", "tags": ["beans", "retail"] }
  ],
  "design": { "kind": "template", "templateId": "tpl_3f9a" },
  "newFolderName": "Retail packaging, autumn run",
  "scanHost": "acme.kuikco.de"
}

• newFolderName crea una carpeta para el lote; folderId lo guarda en una que ya existe. Exactamente uno de los dos.
• scanHost imprime cada código con tu host de marca en lugar de kuikco.de/p/. Queda fijo una vez que existen los códigos.
• La creación masiva está limitada a diez lotes cada diez minutos por clave, además del presupuesto de escritura.
• ¿Tienes un CSV en lugar de filas? Envía su texto como csv y la API lo analiza con las mismas reglas de encabezados que la carga masiva del panel (Name, Destination URL, Tags, UTM parameters, GPS; o la plantilla GS1).

Primero, la vista previaCopiar link a esta sección

Agrega "dryRun": true y no se escribe nada. La respuesta lista las filas entendidas, las líneas que no se importarían y por qué, el impacto en la cuota (quota.remaining, quota.fits), cuántas filas superan el tamaño de lote del plan (over) y un previewHash. Envía ese hash de vuelta como previewHash con la solicitud real: si las filas cambiaron mientras tanto, la API responde 409 preview_changed en lugar de crear un lote distinto.

• ¿Tienes un CSV en lugar de filas? Envía su texto como csv y la API lo analiza con las mismas reglas de encabezados que la carga masiva del panel (Name, Destination URL, Tags, UTM parameters, GPS; o la plantilla GS1).

2. Crea el loteCopiar link a esta sección

Envía un Idempotency-Key derivado de tu propio id de ejecución, para que una solicitud reintentada después de un tiempo de espera agotado devuelva el mismo lote en lugar de crear un segundo.

curl -X POST https://api.kuikcode.com/v1/codes/bulk \
  -H "Authorization: Bearer kc_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-run-2026-09-06-01" \
  -d @batch.json

{
  "folderId": "f_8Ka2",
  "created": 2,
  "codes": [
    { "id": "K02bEPC2SmtopwPr6S-jt", "shortCode": "Ab3dE9xYz", "name": "SKU 10432 Espresso beans 250 g" },
    { "id": "Zq9vX1mN4kLp8rTb2cWd0", "shortCode": "Cd4eF0aBc", "name": "SKU 10433 Espresso beans 1 kg" }
  ]
}

Los lotes son todo o nada: una fila con una URL incorrecta hace fallar toda la solicitud con 400 invalid_request y un param como rows.7.url. Corrige la fila y vuelve a enviar con la misma clave.

Guarda cada id junto al SKU en tu sistema. Esa correspondencia es lo que convierte cada paso posterior en una sola llamada.

3. Obtén los diseños para imprimirCopiar link a esta sección

El diseño de cada código está a un GET de distancia. png y jpg aceptan un size de 256 a 4096 píxeles; svg es vectorial, para la imprenta.

curl "https://api.kuikcode.com/v1/codes/K02bEPC2SmtopwPr6S-jt/image?format=svg" \
  -H "Authorization: Bearer kc_live_..." -o 10432.svg

La primera generación de un código tarda unos segundos; las siguientes quedan en caché hasta que cambia el diseño. Recorre el lote con poca concurrencia y tendrás una carpeta de archivos para imprimir con el nombre de tus SKU.

4. Mantenlo sincronizadoCopiar link a esta sección

• Un producto cambia de lugar: PATCH /codes/{id} con el nuevo destination; consulta Cambia a dónde apunta un código impreso.
• Un producto se descontinúa: PATCH /codes/{id} con { "archived": true }. El código impreso muestra una página neutral de "ya no está activo" y deja de contar para tu plan.
• Un producto nuevo: POST /codes para uno, u otro lote en el mismo folderId.
• Reportes: GET /analytics/summary?folderId=f_8Ka2 para los totales del lote, o GET /scans?folderId=f_8Ka2 para las filas sin procesar.

Productos GS1Copiar link a esta sección

Para empaques de venta minorista que también deben escanearse en la caja, el mismo lote puede ser un lote GS1: cada fila lleva gs1 con el GTIN y, de forma opcional, el número de lote, el número de serie y los atributos, y se imprime como un GS1 Digital Link en tu host GS1. Consulta Lotes GS1; el cuerpo de la solicitud está documentado en la referencia.