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.
/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-KeystringLlave ú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
-
kindstring obligatorioValores:entry_documents,exit_documents,transfer_orders,pick_faces,products -
filestring obligatorioEl archivo
.xlsxo.csvcon la plantilla de la web. -
options[on_duplicate]stringQué 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.
-
dataobjeto obligatorio9 campos de
data-
idinteger obligatorio -
kindstring obligatorio -
statusstring obligatorioValores:uploaded,validating,validated,invalid,committing,committed,failed,cancelled -
filestring | null -
rowsobjeto obligatorio3 campos de
rows-
totalinteger | null -
validinteger | null -
errorinteger | null
-
-
documentsobjeto obligatorio3 campos de
documents-
totalinteger | null -
validinteger | null -
committedinteger | null
-
-
structure_errorsarray de textos -
error_report_urlstring (uri) | nullExcel con cada fila rechazada y su motivo.
-
committed_atstring (date-time) | null
-
-
warningstringAviso 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
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"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://empresa.chainlink.mx/api/v1/imports', [
'headers' => [
'Authorization' => 'Bearer ' . getenv('CHAINLINK_TOKEN'),
'Accept' => 'application/json',
'Idempotency-Key' => (string) \Ramsey\Uuid\Uuid::uuid4(),
],
'multipart' => [
['name' => 'kind', 'contents' => 'products'],
['name' => 'file', 'contents' => fopen('catalogo.xlsx', 'r')],
],
]);
$data = json_decode((string) $response->getBody(), true);
import fs from 'node:fs';
const form = new FormData();
form.append('kind', 'products');
form.append('file', new Blob([fs.readFileSync('catalogo.xlsx')]), 'catalogo.xlsx');
const response = await fetch('https://empresa.chainlink.mx/api/v1/imports', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CHAINLINK_TOKEN}`,
Accept: 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: form,
});
const data = await response.json();
import os
import uuid
import requests
response = requests.post(
"https://empresa.chainlink.mx/api/v1/imports",
headers={
"Authorization": f"Bearer {os.environ['CHAINLINK_TOKEN']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
data={"kind": "products"},
files={"file": open("catalogo.xlsx", "rb")},
)
data = response.json()
{
"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
}
}
{
"error": {
"code": "unauthenticated",
"message": "Falta el token de acceso o ya no es válido.",
"doc_url": "https://chainlink.mx/developers/errores#unauthenticated",
"request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3"
},
"errors": [],
"message": "Falta el token de acceso o ya no es válido."
}
{
"error": {
"code": "feature_not_in_plan",
"message": "Función no disponible en tu plan actual.",
"feature": "webhooks.enabled",
"upgrade_url": "/billing/plans",
"doc_url": "https://chainlink.mx/developers/errores#feature_not_in_plan",
"request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3"
},
"errors": [],
"message": "Función no disponible en tu plan actual."
}
{
"error": {
"code": "missing_scope",
"message": "El cliente no tiene el alcance products:write.",
"scope": "products:write",
"doc_url": "https://chainlink.mx/developers/errores#missing_scope",
"request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3"
},
"errors": [],
"message": "El cliente no tiene el alcance products:write."
}
{
"error": {
"code": "transfer_orders_disabled",
"message": "Las órdenes de transferencia no están activas en tu empresa.",
"doc_url": "https://chainlink.mx/developers/errores#transfer_orders_disabled",
"request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3"
},
"errors": [],
"message": "Las órdenes de transferencia no están activas en tu empresa."
}
{
"error": {
"code": "order_in_wave",
"message": "El pedido OV-000977 ya está en la ola OLA-000008.",
"doc_url": "https://chainlink.mx/developers/errores#order_in_wave",
"request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3"
},
"errors": [],
"message": "El pedido OV-000977 ya está en la ola OLA-000008."
}
{
"error": {
"code": "bad_request",
"message": "texto",
"field": "texto",
"doc_url": "https://demo.chainlink.mx/api/v1/",
"request_id": "texto"
},
"errors": [
{
"field": "texto",
"message": "texto"
}
],
"message": "texto"
}
{
"error": {
"code": "validation_failed",
"message": "El campo name es obligatorio.",
"field": "name",
"doc_url": "https://chainlink.mx/developers/errores#validation_failed",
"request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3"
},
"errors": [
{
"field": "name",
"message": "El campo name es obligatorio."
}
],
"message": "El campo name es obligatorio."
}
{
"error": {
"code": "rate_limited",
"message": "Superaste el límite de solicitudes por minuto. Espera los segundos que indica Retry-After.",
"doc_url": "https://chainlink.mx/developers/errores#rate_limited",
"request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3"
},
"errors": [],
"message": "Superaste el límite de solicitudes por minuto. Espera los segundos que indica Retry-After."
}