API de Comerciantes: conecta tus SKU, los preavisos de compra y el inventario de Shenzhen a tu sistema

Lo que ya puedes hacer

• Crear o actualizar SKU en lote (identificados por tu seller_sku), con un código de barras de producto para cada color y cada talla, vinculados a los códigos de variante de Shopee / Coupang / momo.
• Verificar automáticamente los requisitos de importación a partir del código arancelario de 11 dígitos y marcar los productos que requieren inspección o permiso, o cuya importación no está permitida.
• Enviar el preaviso de los números de seguimiento y del contenido de cada caja al comprar; cuando la mercancía llega al almacén de Shenzhen, se abre automáticamente una orden de etiquetado WO-SK y el almacén etiqueta, escanea y ubica cada pieza.
• Consultar el inventario por almacén y el registro de movimientos de inventario, y recibir por webhook, en tiempo real, las llegadas, las recepciones completadas, las diferencias de cantidad y los cambios de inventario.

Flujo de recepción

1. Crear SKU: envía códigos de barras de producto, variantes, descripciones declaradas y códigos arancelarios.
2. Preaviso de recepción: envía los números de seguimiento y la cantidad prevista de cada SKU.
3. Llegada al almacén de Shenzhen: al escanear el número de seguimiento, se abre e imprime automáticamente una orden de trabajo WO-SK.
4. Etiquetado y ubicación: el almacén imprime los códigos de barras de producto, etiqueta cada pieza y la escanea para contarla.
5. Recepción completada: las unidades recibidas pasan al inventario de Shenzhen, las dañadas se contabilizan aparte y las diferencias se notifican a tu sistema.

Funciones previstas

Pedidos de envío en lote, lotes de envío agrupados automáticamente según las normas de declaración, e inventario anticipado, clasificación y etiquetas de envío de los marketplaces en el almacén de Taoyuan. Se anunciarán en esta página cuando estén disponibles.

Pasos para obtener acceso

1. En el área de miembros, añade un declarante de tipo «empresa» con su número de identificación fiscal taiwanés de 8 dígitos.
2. Contacta con la atención al cliente de HowBridge para solicitar la activación de la API de Comerciantes; la clave se emite tras la aprobación.
3. La clave se muestra una sola vez. Guárdala en una variable de entorno del servidor y nunca la incluyas en un navegador ni en una app.
4. Si necesitas webhooks, primero configura y verifica la URL en la página de API del área de miembros y luego suscríbete a los eventos de comerciante.

Base URL

Formato e idioma

Las solicitudes y respuestas son JSON. Los mensajes de error están en chino tradicional por defecto; envía Accept-Language: en para recibirlos en inglés. En tu código, basa siempre la lógica en error.code, que está fijo en inglés.

Estructura de la respuesta

En caso de éxito devuelve {"success": true, "data": …, "meta": …}; en caso de error, {"success": false, "error": {"code", "message", "errors", "context"}}, donde errors contiene el detalle por campo. La única excepción es una clave ausente o no válida: HTTP 401 con el cuerpo {"message": "Unauthenticated."}.

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "errors": [
      { "code": "TRACKING_IN_USE", "field": "packages.0.tracking_no", "message": "…" }
    ]
  }
}

Límites de solicitudes

60 solicitudes por minuto y 5000 por día por clave (300 por minuto y 50 000 por día en el plan de alto volumen); una solicitud en lote cuenta como una. Para datos en tiempo real, suscríbete a webhooks en lugar de hacer sondeos.

Idempotencia (Idempotency-Key)

Las solicitudes de escritura admiten el encabezado Idempotency-Key (8–128 caracteres: letras, dígitos y _-:.). Si reenvías tras un tiempo de espera de red agotado con la misma clave y el mismo contenido, recibirás la respuesta original con el encabezado Idempotent-Replayed: true; usar la misma clave con otro contenido devuelve 422. Los registros se conservan 24 horas.

Respuestas en lote

Los endpoints en lote informan el resultado de cada elemento: 200 si todos tienen éxito, 207 si fallan algunos y 422 si fallan todos. Cada elemento incluye index, status (created / updated / failed) y el motivo del error.

Caracteres de los identificadores

seller_sku solo admite letras, dígitos y ._- (1–64 caracteres); los códigos de barras de producto admiten además / y + (3–64 caracteres). No se distingue entre mayúsculas y minúsculas.

Crear o actualizar SKU en lote

POST/api/v1/merchant/skus/batch

Hasta 200 elementos por solicitud. Cada elemento se procesa de forma independiente, por lo que un error no afecta a los demás.

Ejemplo de solicitud (POST JSON)

curl -X POST https://0523.tw/api/v1/merchant/skus/batch \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-sync-20260917-001" \
  -d '{
  "items": [
    {
      "seller_sku": "TEE-RED-S",
      "barcode": "4710000000011",
      "product_name": "Cotton T-shirt",
      "spec": { "color": "red", "size": "S" },
      "declared_name_en": "Cotton knitted T-shirt",
      "declared_unit_value": 18.5,
      "declared_currency": "CNY",
      "hs_code": "61091000006",
      "weight_g": 160,
      "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566" } ]
    }
  ]
}'

Respuesta 200

{
  "success": true,
  "data": [
    {
      "index": 0,
      "seller_sku": "TEE-RED-S",
      "status": "created",
      "sku": {
        "seller_sku": "TEE-RED-S",
        "barcode": "4710000000011",
        "system_barcode": null,
        "pick_code": "131999",
        "hs_code": "61091000006",
        "regulation": { "status": "ok", "import_codes": [], "reasons": [] },
        "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566", "platform_sku": null } ]
      }
    }
  ],
  "meta": { "summary": { "created": 1, "updated": 0, "failed": 0 } }
}

Verificación de requisitos de importación (regulation.status)

Consultar SKU

GET/api/v1/merchant/skus

Filtra por seller_sku, barcode, regulation_status o updated_since (ISO 8601) y pagina con page / per_page (máximo 100).

Consultar un SKU

GET/api/v1/merchant/skus/{seller_sku}

Actualizar vínculos con marketplaces

PUT/api/v1/merchant/skus/{seller_sku}/channels

La lista enviada sustituye por completo los vínculos existentes; una misma variante de marketplace no puede vincularse a dos SKU.

Descargar etiquetas de código de barras

GET/api/v1/merchant/skus/{seller_sku}/label.pdf?qty=10

Devuelve un PDF de etiquetas de 40×30 mm; qty es el número de etiquetas (1–1000). El almacén de Shenzhen imprime la misma etiqueta al etiquetar; este endpoint sirve si quieres etiquetar por tu cuenta antes del envío.

Crear una orden de recepción

POST/api/v1/merchant/inbound-orders

Se valida la orden completa: si hay cualquier error, no se crea nada. Un número de seguimiento solo puede pertenecer a una orden de recepción en curso a la vez; los SKU repetidos dentro de un mismo paquete se combinan sumando sus cantidades.

Ejemplo de solicitud (POST JSON)

curl -X POST https://0523.tw/api/v1/merchant/inbound-orders \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-20260917-0001" \
  -d '{
  "reference_no": "PO-20260917-0001",
  "supplier_order_no": "1688-3312456789",
  "packages": [
    {
      "tracking_no": "YT1234567890123",
      "carrier": "yto",
      "items": [
        { "seller_sku": "TEE-RED-S", "qty": 40 },
        { "seller_sku": "TEE-RED-M", "qty": 60 }
      ]
    }
  ]
}'

Estados de la orden de recepción

Estados del paquete

Consultar órdenes de recepción

GET/api/v1/merchant/inbound-orders

GET/api/v1/merchant/inbound-orders/{id}

Filtra por status, reference_no o updated_since. Cada paquete devuelve las cantidades previstas, recibidas y dañadas, además de la diferencia.

Cancelar una orden de recepción

POST/api/v1/merchant/inbound-orders/{id}/cancel

Solo se puede cancelar mientras no haya llegado ningún paquete; tras la cancelación, los números de seguimiento pueden volver a incluirse en un preaviso.

Consultar inventario

GET/api/v1/merchant/inventory?warehouse_code=SZ

Filtra por warehouse_code y seller_sku[] (hasta 200).

Respuesta 200

{
  "success": true,
  "data": [
    { "seller_sku": "TEE-RED-S", "barcode": "4710000000011", "warehouse_code": "SZ",
      "on_hand": 38, "reserved": 0, "available": 38, "damaged": 2, "updated_at": "2026-09-17T15:20:11+08:00" }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 100, "last_page": 1 }
}

Registro de movimientos de inventario

GET/api/v1/merchant/inventory/movements?after_id=0&limit=200

Registros de movimientos que solo se añaden y nunca se modifican. Avanza de página con el cursor after_id (hasta 500 registros por solicitud) y guarda el meta.next_after_id de la respuesta para continuar la conciliación.

Configuración

1. Configura la URL del webhook en la página de API del área de miembros (solo https) y completa la verificación de titularidad: tu endpoint debe responder HTTP 200 con el cuerpo {"challenge": "valor recibido"}.
2. Llama a PUT /api/v1/merchant/webhook/events para suscribirte a los eventos de comerciante. Cambiar después la URL en el área de miembros no elimina esas suscripciones.

curl -X PUT https://0523.tw/api/v1/merchant/webhook/events \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["inbound.arrived", "inbound.received", "inbound.discrepancy", "inventory.changed"]}'

Lista de eventos

inbound.received

{
  "event": "inbound.received",
  "delivery_id": "5b0f1c2e-8f3a-4d7e-9c21-0a6b2d4e8f10",
  "created_at": "2026-09-17T15:20:11+08:00",
  "data": {
    "inbound_order_id": 128,
    "reference_no": "PO-20260917-0001",
    "order_status": "completed_with_discrepancy",
    "tracking_no": "YT1234567890123",
    "work_order": "WO-SK-315",
    "warehouse_code": "SZ",
    "items": [
      { "seller_sku": "TEE-RED-S", "expected_qty": 40, "received_qty": 38, "damaged_qty": 2, "difference": 0 },
      { "seller_sku": "TEE-RED-M", "expected_qty": 60, "received_qty": 59, "damaged_qty": 0, "difference": -1 }
    ],
    "received_at": "2026-09-17T15:20:10+08:00"
  }
}

Verificar la firma

Cada envío incluye X-Lucky-Event, X-Lucky-Delivery-Id y X-Lucky-Signature: t=marca_de_tiempo,v1=firma. Calcula un HMAC-SHA256 con tu webhook secret sobre «marca de tiempo + . + cuerpo sin procesar», compáralo con v1 y rechaza las marcas de tiempo de más de 5 minutos. En los reintentos de un mismo evento, delivery_id no cambia y puede usarse para eliminar duplicados.

Las respuestas distintas de 2xx se reintentan tras 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas; tras 20 fallos consecutivos, el webhook se desactiva automáticamente y debe volver a configurarse en el área de miembros.

// PHP
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_LUCKY_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);   // ['t' => '1789…', 'v1' => 'ab12…']

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('LUCKY_WEBHOOK_SECRET'));

if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);   // de-duplicate by $event['delivery_id']
http_response_code(200);

Cuenta oficial de LINE @0523tw

Correo técnico howyunqisoftware@gmail.com

Versión v1, fase 1 (2026-09-17): SKU de productos, preaviso de recepción, etiquetado y ubicación en Shenzhen, consulta de inventario, webhooks.