# Referencia de la API

> Creación y diseños v2, lecturas y OAuth v1, cabeceras, respuestas y esquemas OpenAPI 3.1.

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](/openapi/v2.yaml) generado por la política, y [OpenAPI de lecturas/OAuth v1](/openapi/v1.yaml). 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

```json
{
  "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](/docs/ordenes): `serial`, `subject_uid`, `status`, `customer`, `invoice_name`, `jewel_type`, `initial_date`, `delivery_date`, `price`, `currency`, `performed_by`.
- [Recibo de creación v2](/docs/ordenes): `serial`, `subject_uid`, `status`, `replayed`, `initial_date`, `delivery_date`, más identidad de política en `meta`.
- [Cuenta](/docs/cuenta): `account_id`, `uid`, `balance`, `currency`, `status`, `created_at`, `updated_at`.
- [Transacción](/docs/cuenta): `transaction_id`, `account_id`, `subaccount_id`, `type`, `amount`, `balance_before`, `balance_after`, `description`, `reference`, `occurred_at`, `currency`.
- [Elemento de cartera](/docs/cartera-y-pagos): `order_serial`, `subject_uid`, `status`, `customer`, `description`, `order_total`, `paid_total`, `balance`, `currency`, `updated_at`.
- [Pago](/docs/cartera-y-pagos): `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](/docs/errores).
