API de Comerciantes: conecte SKUs, pré-avisos de compra e o estoque de Shenzhen ao seu sistema

O que você já pode fazer

• Criar ou atualizar SKUs em lote (identificados pelo seu seller_sku), com um código de barras de produto para cada cor e cada tamanho, vinculados aos códigos de variação da Shopee / Coupang / momo.
• Verificar automaticamente os requisitos de importação pelo código tarifário de 11 dígitos e sinalizar produtos que exigem inspeção, licença ou que não podem ser importados.
• Fazer o pré-aviso dos códigos de rastreio e do conteúdo de cada caixa ao comprar; quando a mercadoria chega ao armazém de Shenzhen, uma ordem de etiquetagem WO-SK é aberta automaticamente e o armazém etiqueta, escaneia e armazena peça por peça.
• Consultar o estoque por armazém e o extrato de movimentações de estoque, e receber por webhook, em tempo real, chegadas, recebimentos concluídos, divergências de quantidade e alterações de estoque.

Fluxo de recebimento

1. Criar SKUs: envie códigos de barras de produto, variações, descrições declaradas e códigos tarifários.
2. Pré-aviso de recebimento: envie os códigos de rastreio e a quantidade prevista de cada SKU.
3. Chegada ao armazém de Shenzhen: ao escanear o código de rastreio, a ordem de serviço WO-SK é aberta e impressa automaticamente.
4. Etiquetagem e armazenagem: o armazém imprime os códigos de barras de produto, etiqueta cada peça e a escaneia para contagem.
5. Recebimento concluído: a quantidade recebida entra no estoque de Shenzhen, itens danificados são contados à parte e as divergências são notificadas ao seu sistema.

Funcionalidades planejadas

Pedidos de envio em lote, lotes de envio agrupados automaticamente conforme as regras de declaração, além de estoque antecipado, triagem e etiquetas de envio dos marketplaces no armazém de Taoyuan. Serão anunciados nesta página quando forem lançados.

Como obter acesso

1. Na área do membro, adicione um declarante do tipo “empresa” com o número de identificação fiscal de Taiwan de 8 dígitos.
2. Entre em contato com o atendimento da HowBridge para solicitar a ativação da API de Comerciantes; a chave é emitida após a aprovação.
3. A chave é exibida apenas uma vez. Guarde-a em uma variável de ambiente no servidor e nunca a coloque em navegador ou app.
4. Para usar webhooks, primeiro configure e verifique a URL na página de API da área do membro e depois assine os eventos de comerciante.

Base URL

Formato e idioma

Requisições e respostas são em JSON. As mensagens de erro vêm em chinês tradicional por padrão; envie Accept-Language: en para recebê-las em inglês. Na lógica do seu código, use sempre error.code, que é fixo em inglês.

Estrutura da resposta

Em caso de sucesso, retorna {"success": true, "data": …, "meta": …}; em caso de falha, {"success": false, "error": {"code", "message", "errors", "context"}}, em que errors traz o detalhamento por campo. A única exceção é chave ausente ou inválida: HTTP 401 com corpo {"message": "Unauthenticated."}.

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

Limites de requisições

60 requisições por minuto e 5.000 por dia por chave (300 por minuto e 50.000 por dia no plano de alto volume); uma requisição em lote conta como uma. Para dados em tempo real, assine webhooks em vez de fazer polling.

Idempotência (Idempotency-Key)

Requisições de escrita aceitam o cabeçalho Idempotency-Key (8–128 caracteres: letras, números e _-:.). Ao reenviar após um timeout de rede com a mesma chave e o mesmo conteúdo, você recebe a resposta original, com o cabeçalho Idempotent-Replayed: true; usar a mesma chave com conteúdo diferente retorna 422. Os registros são mantidos por 24 horas.

Respostas em lote

Endpoints em lote informam o resultado item a item: 200 quando todos têm sucesso, 207 quando alguns falham e 422 quando todos falham. Cada item traz index, status (created / updated / failed) e o motivo da falha.

Caracteres dos identificadores

seller_sku aceita apenas letras, números e ._- (1–64 caracteres); códigos de barras de produto aceitam também / e + (3–64 caracteres). Maiúsculas e minúsculas são tratadas como iguais.

Criar ou atualizar SKUs em lote

POST/api/v1/merchant/skus/batch

Até 200 itens por requisição. Cada item é processado de forma independente; a falha de um não afeta os demais.

Exemplo de solicitação (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" } ]
    }
  ]
}'

Resposta 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 } }
}

Verificação de requisitos de importação (regulation.status)

Consultar SKUs

GET/api/v1/merchant/skus

Filtre por seller_sku, barcode, regulation_status ou updated_since (ISO 8601) e pagine com page / per_page (máximo 100).

Consultar um SKU

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

Atualizar vínculos com marketplaces

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

A lista enviada substitui integralmente os vínculos existentes; a mesma variação de marketplace não pode ser vinculada a dois SKUs.

Baixar etiquetas de código de barras

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

Retorna um PDF de etiquetas de 40×30 mm; qty é a quantidade de etiquetas (1–1000). O armazém de Shenzhen imprime a mesma etiqueta na etiquetagem; este endpoint serve para quando você quiser etiquetar por conta própria antes do envio.

Criar ordem de recebimento

POST/api/v1/merchant/inbound-orders

Validação da ordem inteira: se houver qualquer erro, nada é criado. Um código de rastreio só pode pertencer a uma ordem de recebimento em andamento por vez; SKUs repetidos no mesmo pacote têm as quantidades somadas.

Exemplo de solicitação (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 }
      ]
    }
  ]
}'

Status da ordem de recebimento

Status do pacote

Consultar ordens de recebimento

GET/api/v1/merchant/inbound-orders

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

Filtre por status, reference_no ou updated_since. Cada pacote retorna as quantidades previstas, recebidas e danificadas, além da divergência.

Cancelar ordem de recebimento

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

Só é possível cancelar enquanto nenhum pacote tiver chegado; após o cancelamento, os códigos de rastreio podem ser incluídos em um novo pré-aviso.

Consultar estoque

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

Filtre por warehouse_code e seller_sku[] (até 200).

Resposta 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 }
}

Extrato de movimentações de estoque

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

Registros de movimentação que só são acrescentados, nunca alterados. Avance as páginas com o cursor after_id (até 500 registros por requisição) e guarde o meta.next_after_id da resposta para continuar a conciliação.

Configuração

1. Configure a URL do webhook na página de API da área do membro (somente https) e conclua a verificação de propriedade: seu endpoint deve responder HTTP 200 com o corpo {"challenge": "valor recebido"}.
2. Chame PUT /api/v1/merchant/webhook/events para assinar os eventos de comerciante. Alterar a URL depois na área do membro não remove essas assinaturas.

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"
  }
}

Verificação de assinatura

Cada envio inclui X-Lucky-Event, X-Lucky-Delivery-Id e X-Lucky-Signature: t=timestamp,v1=assinatura. Calcule o HMAC-SHA256 com o seu webhook secret sobre “timestamp + . + corpo bruto”, compare com v1 e rejeite timestamps com mais de 5 minutos. Nas novas tentativas do mesmo evento, delivery_id não muda e pode ser usado para eliminar duplicidades.

Respostas diferentes de 2xx geram novas tentativas após 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas; após 20 falhas consecutivas, o webhook é desativado automaticamente e precisa ser configurado novamente na área do membro.

// 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);

Conta oficial no LINE @0523tw

E-mail técnico howyunqisoftware@gmail.com

Versão v1, fase 1 (2026-09-17): SKUs de produtos, pré-aviso de recebimento, etiquetagem e armazenagem em Shenzhen, consulta de estoque, webhooks.