API de compra manual

Un canal, un vendedor, un pedido de compra

Un pedido de compra puede incluir varios productos o SKU, pero todos los artículos deben pertenecer al mismo canal y al mismo vendedor.

Si tu cliente compra artículos de distintos vendedores o canales, tu aplicación debe separarlos en pedidos de compra independientes antes de llamar a la API de pedidos de HIOBuy.

HIOBuy no divide automáticamente los pedidos de compra ni ofrece una API de pedidos por lotes para este flujo.

Identificar el canal y el vendedor

• Usa el channel del pedido. El canal de la ruta abreviada, del cuerpo y de las líneas debe coincidir. No mezcles canales en lines[] ni en items[].
• Para agrupar artículos en el cliente, usa el seller.id real de la API de productos cuando esté disponible: en 1688 procede de sellerOpenId y en los detalles de Taobao, de shop_id. Un valor alternativo generado seller_1688_* / seller_taobao_*, un ID ausente, el título del producto o el nombre de la tienda no acreditan la identidad del vendedor. Los ID de tienda de Taobao y los ID de vendedor del renderizado pertenecen a sistemas de identificación distintos y no deben compararse.
• La solicitud estándar no añade ningún campo de vendedor obligatorio. En modo self, antes de crear el pedido oficial, Gateway verifica la titularidad de 1688 con los detalles originales y la de Taobao con render_item_list[].seller_id, comprobando todos los productos y SKU solicitados. Si faltan pruebas o son ambiguas, se rechaza la creación.
• En modo de compra Warehouse, incluidos los pedidos manuales, el almacén verifica el vendedor antes de crear pedidos, iniciar compras, cargar el monedero o devolver éxitos parciales. Gateway comprueba los conflictos de canal de la solicitud original y transmite los errores del almacén sin repetir consultas a las plataformas. El almacén requiere una validación de aceptación independiente; desplegar Gateway no demuestra que un almacén externo ya aplique este control.
• Los pedidos manuales usan channel=manual y todos los artículos deben compartir también el mismo source_platform. seller_name es solo una declaración para mostrar. El almacén debe verificar el vendedor real de cada producto o devolver SELLER_ID_UNAVAILABLE. Un nombre o ID declarado por el cliente no sustituye esta verificación. No actives la creación manual antes de aceptar el contrato del almacén.

Errores y medidas correctivas

Los tres errores devuelven HTTP 400, con categoría VALIDATION_ERROR:

Texto original en inglés que devuelve la API para un pedido mixto:

A purchase order must contain products from the same channel and seller. Please split the items into separate orders by channel and seller.

Un rechazo por vendedor no debe crear pedidos ni tareas de compra, cargar el monedero ni producir éxitos parciales. Siguen vigentes las reglas de idempotencia existentes. Cada compra separada intencionadamente debe tener su propia referencia o clave; para reintentar una compra sin cambios, reutiliza la clave original.

Compra y envío consolidado

Los pedidos de compra representan compras nacionales a vendedores individuales. Los artículos de pedidos distintos pueden recibirse en paquetes separados y después consolidarse en un envío internacional, si lo permiten las condiciones del almacén y del transporte. La consolidación no fusiona los números de compra originales, los portes nacionales ni los estados de pago, cancelación o reembolso.

Solicitud válida: varios SKU de un vendedor verificado

El almacén debe establecer de forma independiente que ambas URL pertenecen a un único vendedor estable de la plataforma. Las URL son ilustrativas y no constituyen pruebas de identidad ni resultados de aceptación en producción.

{
  "channel": "manual",
  "external_order_id": "MANUAL-SELLER-A-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 41",
      "unit_price": 5000,
      "quantity": 1
    }
  ]
}

Ejemplo incorrecto: los vendedores reales son distintos

Si items[0].product_url pertenece al vendedor A y items[1].product_url al vendedor B, el almacén debe devolver MULTIPLE_SELLERS_NOT_ALLOWED aunque la solicitud declare seller_name: "Seller A". Si no puede verificar la titularidad, debe devolver SELLER_ID_UNAVAILABLE en lugar de aceptar el nombre declarado.

{
  "channel": "manual",
  "external_order_id": "INVALID-MIXED-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-B/shirt",
      "product_name": "Shirt",
      "specification": "M",
      "unit_price": 3000,
      "quantity": 1
    }
  ]
}

El rechazo del almacén por vendedor debe reproducirse según el contrato de referencia de negocio/idempotencia existente, sin crear pedidos ni efectuar cargos. Los pedidos ya creados conservan su comportamiento de repetición, consulta, pago y cancelación.

POST /v1/orders/manual

Una solicitud crea un pedido de una plataforma y un vendedor, con varios artículos del mismo vendedor. Solo se admiten jd, pinduoduo y poizon; seller_name es obligatorio. Separe plataformas o vendedores distintos con números de compra diferentes.

Requiere Production API Key, permiso order:create, modo warehouse y vinculación activa al almacén. No necesita OAuth de marketplace. Sandbox no está disponible. El almacén debe implementar y verificar su API manual antes del uso.

Solicitud

Authorization: Bearer <PRODUCTION_API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16

{
  "channel": "manual",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "language": "es",
  "remark": "Please ship together",
  "items": [
    {
      "item_ref": "I001",
      "product_url": "https://example.com/item1",
      "product_name": "Wireless Mouse",
      "specification": "Black",
      "unit_price": 3500,
      "quantity": 2,
      "product_image": null,
      "remark": ""
    }
  ]
}

external_order_id es obligatorio y único en los pedidos manuales de la aplicación. Mismo número y datos: pedido existente; datos cambiados: HTTP 409 IDEMPOTENCY_CONFLICT. Una nueva compra usa otro número. Idempotency-Key es obligatorio al crear, pagar y cancelar. HIOBuy genera order_sn; item_ref es opcional. No se admiten arrays sellers ni vendedores definidos por artículo.

Importes del almacén

Los importes son enteros en fen CNY: 3500 = CNY 35.00. El almacén calcula productos, envío nacional, comisión existente del 5 % y total. El ejemplo no define base, mínimo ni redondeo. HIOBuy guarda los importes sin añadir otro 5 %. Importes o referencias incompletos impiden pagar.

{
  "channel": "manual",
  "success": true,
  "order_id": "WH10001",
  "order_sn": "HB202610160001",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "status": "wait_payment",
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "total": {
    "merchandise": {
      "amount": 7000,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 800,
      "currency": "CNY"
    },
    "procurement_fee": {
      "amount": 390,
      "currency": "CNY"
    },
    "payment": {
      "amount": 8190,
      "currency": "CNY"
    }
  },
  "order_list": [
    {
      "order_id": "WH10001",
      "shipping": {
        "amount": 800,
        "currency": "CNY"
      },
      "lines": [
        {
          "item_ref": "I001",
          "sub_order_id": "WI10001",
          "title": "Wireless Mouse",
          "spec_title": "Black",
          "quantity": 2,
          "unit_price": {
            "amount": 3500,
            "currency": "CNY"
          },
          "line_total": {
            "amount": 7000,
            "currency": "CNY"
          }
        }
      ]
    }
  ],
  "failed_offers": [],
  "request_id": "req_example"
}

Operaciones existentes

Crear no descuenta saldo ni inicia compras. Use order_id y channel=manual con las API existentes de pago, cancelación, detalle y seguimiento nacional. No envíe pay_amount. Tras comprobar el importe guardado, el almacén realiza el pago habitual y compra solo después de confirmarlo. Cancelar no confirma un reembolso.

• POST /v1/orders/pay
• POST /v1/orders/cancel
• POST /v1/orders/detail
• POST /v1/orders/logistics/trace

{
  "channel": "manual",
  "order_id": "WH10001"
}

{
  "channel": "manual",
  "order_id": "WH10001",
  "cancel_reason": "buyer_request"
}

Reintentos y límites

Si hay tiempo agotado o resultado desconocido, conserve número y clave y consulte el detalle. No cambie automáticamente la clave para volver a pagar. El detalle incluye payment_status, referencias y comisiones. Listas y reembolsos de marketplaces no admiten manual. Límites: 1–100 líneas, cantidad 1–9999, vendedor 200 caracteres, nombre y especificación 500, notas 1000, URL HTTP/HTTPS 2048. Se rechazan importes de texto o decimales.

400 VALIDATION_ERROR · 403 FULFILLMENT_MODE_NOT_SUPPORTED / WAREHOUSE_AUTH_INVALID · 409 IDEMPOTENCY_CONFLICT / ORDER_AMOUNT_CHANGED / ORDER_OPERATION_UNRESOLVED · 502 WAREHOUSE_INVALID_RESPONSE · 503 WAREHOUSE_UNAVAILABLE

Webhooks

procurement.failed / procurement.out_of_stock

{
  "type": "procurement.failed",
  "data": {
    "channel": "manual",
    "order_id": "WH10001",
    "order_sn": "HB202610160001",
    "external_order_id": "EXT-10001",
    "source_platform": "jd",
    "seller_name": "Seller A",
    "status": "partial_failure",
    "reason_code": "OUT_OF_STOCK",
    "items": [
      {
        "item_ref": "I001",
        "sub_order_id": "WI10001",
        "quantity": 1,
        "reason_code": "OUT_OF_STOCK"
      }
    ]
  }
}