Órdenes

Estado de publicación

Las órdenes se crean con la API v2 y el SDK 2.x. El CDN publica el SDK 2.0.3 en los canales v2 y latest, con la política 1.0.5. POST /api/v1/client/orders responde 410 ORDER_CREATE_VERSION_RETIRED, así que no uses el antiguo orders.create() del SDK 1.x (canal v1, versión 1.1.0) para pedidos nuevos. GET /api/v1/client/orders y las demás lecturas v1 siguen disponibles.

Crear una orden con v2

POST /api/v2/client/orders · scope orders:create · cabecera Idempotency-Key obligatoria. La entrada es cerrada: solo se aceptan los campos del OpenAPI v2 y la política external-create-v2. El SDK actualizado incorpora policy_version y policy_sha256 automáticamente; una llamada HTTP directa debe tomarlos del OpenAPI publicado (info.x-order-policy-version y info.x-order-policy-sha256).

El cuerpo siguiente muestra la forma del contrato. Sustituye el SHA y la referencia de diseño por valores publicados o emitidos para tu actor: los marcadores no son valores válidos para enviar.

{
  "policy_version": "1.0.5",
  "policy_sha256": "<VALOR info.x-order-policy-sha256 DEL OPENAPI V2>",
  "initial_date": "2026-10-01",
  "delivery_date": "2026-10-15",
  "performed_by": "integracion-erp",
  "jewel": {
    "customer_id": "123456789",
    "customer": "Cliente Demo",
    "phone": "3000000000",
    "type": "Anillo",
    "material": "Plata",
    "invoice_name": "Cliente Demo",
    "details": "Grabado interior",
    "measurement_system": "Americana",
    "measurements": { "anillo": "7" },
    "weight": { "total": "0.8" },
    "design_refs": ["<REFERENCIA OPACA EMITIDA POR FILES>"]
  }
}

order_subject_uid es opcional y solo puede señalar a una persona dentro del alcance que el servidor resuelve para el token. No permite escoger un uid arbitrario ni cambiar de empresa. urgent_authorization_code es opcional y obligatorio si el plazo de entrega requiere autorización urgente. El cliente no envía precio, propietario, estado, URLs de diseño ni blobs de imagen en este JSON.

Diseños antes de crear

Primero envía 1–5 archivos al servicio autorizado POST /api/v2/client/order-designs como multipart/form-data con el campo files; se requiere el mismo scope orders:create. El servidor devuelve data.design_refs, referencias opacas emitidas y verificadas por Files. Usa de 1 a 5 de esas referencias en jewel.design_refs al crear. Un texto que imite su formato, una URL o una referencia emitida para otro actor/alcance no sirve. El SDK de pedidos no contiene un método de carga: usa HTTP autorizado para esa operación y entrega las referencias resultantes a client.orders.create() del SDK v2.

curl -sS -X POST https://datacenterv2.joyeriazafirox.com/api/v2/client/order-designs \
  -H "Authorization: Bearer $TOKEN" \
  -F "files=@diseno-1.png"
# Respuesta: {"data":{"design_refs":["odr1.…"]},"meta":{"api_version":"2"}}

Reglas de contenido

Los límites de texto se miden tras String.trim() de ECMAScript y en unidades UTF-16. Las extensiones x-order-policy-* del OpenAPI 3.1 publican esa semántica; un validador JSON Schema genérico comprueba solo la forma y no reemplaza el ejecutor de políticas. Consulta el OpenAPI para todos los campos, catálogos y condiciones. Una recomendación de diseño no equivale a un rechazo de servidor.

Para una joya Otros, la medida no es obligatoria. Un ejemplo válido con talla opcional es "measurement_system": "Americana", "measurements": {"solitario": "6 (1/2)"}; también se puede omitir measurements. La talla 3 (1/4) es válida con "measurement_system": "Americana" y se rechaza con "measurement_system": "Nacional". Desde la política 1.0.5, el catálogo Nacional incluye las tallas 33 y 33 (1/2). Otras claves de medida, como anillo, se rechazan para Otros.

Respuesta e idempotencia

El envelope v2 contiene data y meta.api_version: "2", meta.policy_version, meta.policy_sha256 y meta.request_id. Guarda el request_id para diagnóstico. Idempotency-Key debe tener 1–255 caracteres sin espacios ni caracteres de control; reutiliza la misma clave y el mismo cuerpo después de un timeout. El SDK genera una clave cuando no se proporciona y verifica que la respuesta ateste la misma política que compiló.

Listar órdenes

GET /api/v1/client/orders · scope orders:read · continúa en v1. El SDK actualizado conserva client.orders.list() sobre esta ruta.

Cada elemento conserva serial, subject_uid, status, customer, invoice_name, jewel_type, initial_date, delivery_date, price como cadena decimal, currency y performed_by. La paginación sigue meta.pagination.next_cursor; consulta paginación.