OAuth y lecturas usan https://datacenterv2.joyeriazafirox.com/api/v1/client; creación y carga de diseños usan /api/v2/client. Esquemas: OpenAPI de pedidos v2 generado por la política, y OpenAPI de lecturas/OAuth v1. La creación v2 y el sitio actualizado están pendientes de publicación coordinada con el backend y SDK.
Rutas
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
POST | /oauth/token | — | Emite un access token (client_credentials, authorization_code + PKCE o refresh_token) |
GET | /oauth/authorize | — | Inicia «Acceder con Zafirox»: 302 a accounts.joyeriazafirox.com con client_id, redirect_uri, scope, state, code_challenge |
POST | /oauth/authorize/{begin,login,decision} | — | Pasos reservados a la pantalla de cuentas (cabecera X-Zafirox-Accounts-Key); una integración no los llama |
POST | /api/v2/client/order-designs | orders:create | Recibe 1–5 imágenes y emite design_refs opacas |
POST | /api/v2/client/orders | orders:create | Crea orden con política versionada e Idempotency-Key |
POST | /api/v1/client/orders | orders:create | Creación retirada: 410 ORDER_CREATE_VERSION_RETIRED al publicar v2 |
GET | /orders | orders:read | Lista órdenes del alcance en v1 |
GET | /account | account:read | Cuenta principal |
GET | /account/transactions | account:transactions:read | Historial de la cuenta |
GET | /portfolio | portfolio:read | Cartera |
GET | /portfolio/payments | portfolio:payments:read | Pagos |
OPTIONS | rutas autorizadas | — | Preflight CORS (204) según origen registrado |
Envelope
{
"data": {},
"meta": {
"api_version": "1",
"request_id": "req_…",
"pagination": { "next_cursor": null, "has_more": false }
},
"errors": []
}meta.pagination sólo aparece en colecciones. En errores data es null y errors tiene un elemento.
La creación v2 responde con meta.api_version: "2", meta.policy_version y meta.policy_sha256. El SDK v2 rechaza una respuesta cuya identidad de política no coincida con la compilada. Un replay idempotente íntegro conserva la identidad original de política.
Cabeceras
| Cabecera | Dirección | Detalle |
|---|---|---|
Authorization | petición | Bearer <token> |
Idempotency-Key | petición | 1..255 caracteres sin espacios; obligatoria en POST /api/v2/client/orders |
Content-Type: multipart/form-data | petición | Carga v2 de diseños en files (1–5 archivos) |
X-Request-Id | ambas | Propagado si es válido; generado (req_…) si no |
Cache-Control: no-store | respuesta | Nunca se cachean datos de negocio |
Retry-After | respuesta | Segundos de espera en 429 y 503 |
X-RateLimit-Limit, X-RateLimit-Remaining | respuesta | Cuota del cliente en la ventana actual |
Parámetros de consulta
| Ruta | Parámetros |
|---|---|
GET /orders | cursor, limit, status, category, search, start_date, end_date, subject_uid |
GET /account/transactions | cursor, limit, type, from, to |
GET /portfolio | cursor, limit, status, order_serial, subject_uid |
GET /portfolio/payments | cursor, limit, order_serial, from, to, subject_uid |
Un parámetro desconocido responde 422 VALIDATION_ERROR con field.
Tipos comunes
| Tipo | Forma | Ejemplo |
|---|---|---|
| Decimal | cadena con dos decimales históricos o cuatro para COP operativo, opcional signo | "150000.00", "0.0001" |
| Fecha civil | AAAA-MM-DD | "2026-09-20" |
| Instante | RFC 3339 con desplazamiento | "2026-09-15T17:00:00-05:00" |
| Identificador | cadena opaca | "10", "uid_…" |
| Moneda | ISO 4217 | "COP" |
Recursos
- Orden:
serial,subject_uid,status,customer,invoice_name,jewel_type,initial_date,delivery_date,price,currency,performed_by. - Recibo de creación v2:
serial,subject_uid,status,replayed,initial_date,delivery_date, más identidad de política enmeta. - Cuenta:
account_id,uid,balance,currency,status,created_at,updated_at. - Transacción:
transaction_id,account_id,subaccount_id,type,amount,balance_before,balance_after,description,reference,occurred_at,currency. - Elemento de cartera:
order_serial,subject_uid,status,customer,description,order_total,paid_total,balance,currency,updated_at. - Pago:
payment_id,subject_uid,order_serials,amount,currency,payment_type,reference,occurred_at.
La solicitud de creación v2 es cerrada: rechaza campos fuera de perfil, incluidos price, uid, status y design_urls. Los límites de texto en x-order-policy-* se calculan tras String.trim() ECMAScript en unidades UTF-16; un validador JSON Schema genérico no ejecuta las recetas matches/cook.
Errores
Ver el catálogo completo.