Pedidos

Los compradores colocan pedidos en su portal de comercio. Los proveedores manejan la facturación. Pueden ofrecer opcionalmente pagos de clientes alojados por Stripe después de confirmar el total final. Las solicitudes de pedido y el crédito de comercio permanecen disponibles. Use la API para extraer pedidos en su ERP o sistema contable y mantener actualizado su estado.

Estados de los pedidosEnlace a esta sección#

El personal puede omitir etapas intermedias de selección. Moverse hacia atrás o reabrir un pedido completado o cancelado requiere un correctionReason interno. El historial anterior permanece. Las correcciones nunca alteran el estado de pago. Lea revision y envíe expectedRevision con las actualizaciones para rechazar ediciones obsoletas.

Crear un pedido para un clienteEnlace a esta sección#

POST/api/v1/orders/previewescribir clave

Requiere orders.create y acceso al cliente. Envíe customerAccountId y lines que contengan productId y un entero qty (de 1 a 1.000.000). Elija cada producto ordinario una vez, como máximo 100 líneas. Una línea puede incluir un configuration opcional que contenga las claves de medición y elección devueltas; las diferentes configuraciones de un mismo producto permanecen separadas. El lineKey opcional otorga a cada línea de vista previa una identidad de llamada estable. Un additionalDiscountBp adicional requiere permiso de precios y discountReason. Las órdenes configuradas incluyen un configuration inmutable con una instantánea de entradas, especificación, versión, redondeo y cargos. La vista previa devuelve total, fingerprint, precios y moneda del cliente actual. Las cuentas pausadas, productos no disponibles y cantidades inferiores al mínimo son rechazadas. Un catálogo solo de precios sigue aceptando un pedido ingresado aquí; los compradores no pueden enviar uno ellos mismos mientras esté desactivado.

POST/api/v1/ordersescribir clave

Envíe el mismo cliente y líneas, expectedTotal de la vista previa, expectedBasket establecido en su huella dactilar, y un UUID nuevo requestKey. Se admiten poNumber opcional (60 caracteres) y notes visible para el cliente (2.000 caracteres). Reutilice exactamente la misma solicitud y clave después de una respuesta incierta: un reintentó exitoso devuelve el pedido original en lugar de crear otro. Los precios modificados requieren otra revisión. El resultado es placed con orderId y reference, o prices_changed, empty o unavailable.

El personal actúa bajo su propia identidad. La cesta del cliente no se ve afectada. Los contactos por correo electrónico del cliente pueden recibir una copia; esto no carga el pago. El Representante de Ventas tiene acceso de creación por defecto; las actualizaciones de procesamiento y entrega requieren el permiso separado orders.process.

Entrega y seguimientoEnlace a esta sección#

PATCH/api/v1/orders/{id}/deliveryescribir clave

Requiere orders.process. Envíe deliveryMethod: unspecified, courier, own_delivery o collection. Se admiten courierName (100 caracteres), trackingReference (120 caracteres) y trackingUrl (1.000 caracteres) visibles para el cliente. Los enlaces de seguimiento deben usar HTTPS sin credenciales de inicio de sesión incrustadas. Los detalles opcionales omitidos los borran. Envíe expectedRevision del pedido actual. Hay un registro de entrega por pedido; las integraciones de transportistas y envíos divididos no están incluidas. Los detalles del transportista en blanco nunca implican entrega propia.

Listar pedidosEnlace a esta sección#

GET/api/v1/orders

Pedidos más recientes primero. La lista cubre los 200 pedidos más recientes que coincidan con sus filtros. Para capturar nuevos pedidos, consulte con status=new.

curl "https://tradecatalog.app/api/v1/orders?status=new" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch('https://tradecatalog.app/api/v1/orders?status=new', {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: orders } = await res.json()

{
  "data": [
    {
      "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
      "reference": "SO-000142",
      "status": "new",
      "total": 31460,
      "currency": "GBP",
      "poNumber": "PO-88231",
      "createdAt": "2026-09-27T07:48:12.000Z",
      "customer": "Oakfield Joinery"
    }
  ],
  "nextOffset": null
}

Obtener una ordenEnlace a esta sección#

GET/api/v1/orders/{id}

La orden con sus líneas y historial de estados.

curl https://tradecatalog.app/api/v1/orders/5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch(`https://tradecatalog.app/api/v1/orders/${orderId}`, {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: order } = await res.json()

{
  "data": {
    "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
    "customerAccountId": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
    "placedBy": "Fq3L0cZ7tN1pW9aYx2Rk",
    "reference": "SO-000142",
    "poNumber": "PO-88231",
    "notes": "Deliver to the Hebden Road site, gate 2.",
    "status": "new",
    "cancelReason": null,
    "currency": "GBP",
    "total": 31460,
    "createdAt": "2026-09-27T07:48:12.000Z",
    "updatedAt": "2026-09-27T07:48:12.000Z",
    "customer": { "name": "Oakfield Joinery", "accountCode": "OAK01" },
    "lines": [
      {
        "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
        "orderId": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
        "productId": "3f8a2c1e-9b4d-4e6f-a7c8-1d2e3f4a5b6c",
        "sku": "HX-8510",
        "name": "Hex bolt M10 x 50 zinc",
        "unitLabel": "Box of 100",
        "qty": 20,
        "unitPrice": 1573,
        "listPrice": 1850,
        "priceLabel": "Brand discount −15%",
        "lineTotal": 31460
      }
    ],
    "events": [
      {
        "status": "new",
        "note": null,
        "createdAt": "2026-09-27T07:48:12.000Z",
        "actor": "Sam Patel"
      }
    ]
  }
}

Actualizar o corregir una ordenEnlace a esta sección#

PATCH/api/v1/orders/{id}escribir clave

Cambia el estado de una orden. Devuelve la orden actualizada en la misma estructura que GET /orders/{id}.

• Los movimientos normales de envío siguen las etapas de cumplimiento anteriores. Otros movimientos requieren un motivo de corrección privada; un estado actual repetido no hace ningún cambio.
• Cancelar requiere un note, que se muestra al comprador como razón.
• Los cambios de estado pueden enviar correos electrónicos a los contactos del cliente, incluida la nota pública. Un correo electrónico generado no demuestra la entrega.
• El cambio se registra en el historial de la orden contra la persona que hizo la clave.

curl -X PATCH https://tradecatalog.app/api/v1/orders/5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "dispatched", "note": "DPD tracking 1554 2210 0931" }'

const res = await fetch(`https://tradecatalog.app/api/v1/orders/${orderId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ status: 'acknowledged' }),
})
const { data: order } = await res.json()

Volver a intentar un PATCH que ya tuvo éxito devuelve 400 invalid_request, porque la orden ha avanzado. Compruebe el estado de la orden antes de tratarlo como un error.

No disponibleEnlace a esta sección#

La API no puede colocar órdenes para un comprador, ni cambiar las líneas, cantidades o precios de una orden. Los compradores colocan órdenes en su portal comercial; los cambios en una orden se acuerdan con el cliente y se facturan en su propio sistema.

Las listas de órdenes también incluyen paymentStatus: null para términos de cuenta normales, o el estado de pago opcional de Stripe. El estado de cumplimiento es separado y nunca demuestra el pago. La página de detalles de la orden es el lugar para revisar el total final confirmado y aprobar el pago. La API no puede crear ni aprobar un pago.

internalNote (2.000 caracteres) y correctionReason (1.000 caracteres) son campos de historial solo para personal. note permanece público, incluyendo notas antiguas. Envíe expectedRevision para rechazar una edición concurrente con una solicitud inválida. Las lecturas de la API de personal incluyen historial privado; las lecturas de herramientas de comprador y portal excluyen identidades de personal y campos privados. Cancelar aún requiere una razón pública y la retirada o el reembolso completo de un pago pendiente.