Endpoints de la API. Especificación exacta de cada operación de la API v1 (parámetros, cuerpo, respuestas y ejemplos), generada del documento OpenAPI con el que se valida cada respuesta real. Los procedimientos completos están en Guías.

POST /imports

Subir un archivo de carga masiva

Sube un archivo .xlsx o .csv (máximo 5 MB) con la plantilla de la web y lo valida sin aplicar nada. Responde 202 con el resultado de la validación; el estado se consulta y la carga se confirma con confirmar carga. Los límites de filas dependen del plan (2,000 en Essentials, 10,000 en Professional, 100,000 en Enterprise).

Alcance (cliente de integración)
products:write
Permiso (token de usuario)
imports.run
Idempotency-Key
Opcional
Requisitos
Carga masiva activa

Cabeceras

  • Idempotency-Key string

    Llave única por operación (se recomienda un UUID v4). Reenviar la misma solicitud con la misma llave en las siguientes 24 horas devuelve la respuesta original sin repetir la operación.

Cuerpo de la solicitud multipart/form-data

  • kind string obligatorio
    Valores: entry_documents, exit_documents, transfer_orders, pick_faces, products
  • file string obligatorio

    El archivo .xlsx o .csv con la plantilla de la web.

  • options[on_duplicate] string

    Qué hacer con un documento que ya existe.

    Valores: skip, fail
  • options[auto_allocate] boolean

Respuestas

202 Archivo recibido y validado. Location apunta a la carga.
  • data objeto obligatorio
    9 campos de data
    • id integer obligatorio
    • kind string obligatorio
    • status string obligatorio
      Valores: uploaded, validating, validated, invalid, committing, committed, failed, cancelled
    • file string | null
    • rows objeto obligatorio
      3 campos de rows
      • total integer | null
      • valid integer | null
      • error integer | null
    • documents objeto obligatorio
      3 campos de documents
      • total integer | null
      • valid integer | null
      • committed integer | null
    • structure_errors array de textos
    • error_report_url string (uri) | null

      Excel con cada fila rechazada y su motivo.

    • committed_at string (date-time) | null
  • warning string

    Aviso cuando el mismo archivo ya se había subido.

401 Falta el token o no es válido.

Cuerpo: el sobre de error.

402 La función no está en el plan de la empresa, o la cuenta está suspendida o cancelada.

Cuerpo: el sobre de error.

403 Al cliente le falta el alcance (missing_scope), al usuario el permiso (forbidden), o el token de usuario no tiene acceso a la ruta (client_not_allowed: aplicación móvil o usuario con verificación en dos pasos).

Cuerpo: el sobre de error.

404 El módulo no está activo en la empresa.

Cuerpo: el sobre de error.

409 La solicitud choca con el estado actual (por ejemplo, un pedido ya está en otra ola).

Cuerpo: el sobre de error.

413 El archivo excede 5 MB.

Cuerpo: el sobre de error.

422 Datos no válidos (validation_failed), una llave de idempotencia reutilizada con otra solicitud (idempotency_key_reused) o una regla de negocio que bloquea la operación (rule_blocked).

Cuerpo: el sobre de error.

429 Se superó el límite por minuto. Reintente después de los segundos de Retry-After.

Cuerpo: el sobre de error.

Probar

Probar con una instancia

La solicitud sale del navegador hacia la instancia indicada; nada pasa por chainlink.mx. El token se conserva solo en esta pestaña.

Obtener un token con un cliente de integración

Credenciales de Configuración › Clientes API (grant client_credentials). El secreto se usa una vez y no se guarda. Los tokens de usuario se obtienen fuera de la consola; ver Autenticación.

Solicitud
curl -X POST "https://empresa.chainlink.mx/api/v1/imports" \
  -H "Authorization: Bearer $CHAINLINK_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "kind=products" \
  -F "file=@catalogo.xlsx"
Respuesta
{
    "data": {
        "id": 14,
        "kind": "products",
        "status": "validated",
        "file": "catalogo-octubre.xlsx",
        "rows": {
            "total": 250,
            "valid": 248,
            "error": 2
        },
        "documents": {
            "total": 0,
            "valid": 0,
            "committed": 0
        },
        "structure_errors": [],
        "error_report_url": "https://demo.chainlink.mx/imports/14/errors.xlsx",
        "committed_at": null
    }
}