# Zafirox Client SDK y API pública

> API HTTP de Zafirox: creación de pedidos y carga autorizada de diseños en `/api/v2/client`; autenticación, lecturas de órdenes, cuenta, transacciones, cartera y pagos en `/api/v1/client`. Al publicar v2, la creación v1 responde 410; el despliegue de v2 está pendiente. El SDK TypeScript usa la política de pedidos versionada; el alcance lo resuelve el servidor. Dinero como decimal string, paginación por cursor e idempotencia por Idempotency-Key.

Base de lectura y OAuth: https://datacenterv2.joyeriazafirox.com/api/v1/client
Base de creación de pedidos y diseños: https://datacenterv2.joyeriazafirox.com/api/v2/client
Token endpoint: https://datacenterv2.joyeriazafirox.com/api/v1/client/oauth/token
CDN ESM del SDK: https://sdk.joyeriazafirox.com/cdn/v1/index.js

## Comenzar

- [Descripción general](https://sdk.joyeriazafirox.com/docs/introduccion.md): Qué ofrece la API pública de clientes de Zafirox, qué puede hacer el SDK y cómo está organizada esta documentación.
- [Inicio rápido](https://sdk.joyeriazafirox.com/docs/inicio-rapido.md): Obtén un token y consulta órdenes desde Node.js, Replit, navegador, PHP o cURL; prepara la creación v2 con diseños autorizados.
- [Instalación del SDK](https://sdk.joyeriazafirox.com/docs/instalacion.md): Cómo incorporar @zafirox/client-sdk en Node.js, Replit o el navegador desde el CDN, y cómo fijar versiones con integridad.

## Guías

- [Autenticación y scopes](https://sdk.joyeriazafirox.com/docs/autenticacion.md): Dos formas de obtener un access token (client_credentials para servidores y «Acceder con Zafirox» con Authorization Code + PKCE para personas), scopes, caducidad, refresh tokens, alcance titular/master y revocación.
- [Órdenes](https://sdk.joyeriazafirox.com/docs/ordenes.md): Crear pedidos con la política v2, cargar diseños autorizados y consultar órdenes mediante la lectura v1.
- [Cuenta y transacciones](https://sdk.joyeriazafirox.com/docs/cuenta.md): Consultar la cuenta principal del alcance, su saldo exacto y el historial de transacciones con filtros por tipo y fechas.
- [Cartera y pagos](https://sdk.joyeriazafirox.com/docs/cartera-y-pagos.md): Consultar las órdenes con saldo pendiente (cartera) y los pagos aplicados a una o varias órdenes del alcance.
- [Paginación por cursor](https://sdk.joyeriazafirox.com/docs/paginacion.md): Cómo recorrer colecciones grandes con next_cursor y has_more sin perder ni repetir elementos.
- [Errores y reintentos](https://sdk.joyeriazafirox.com/docs/errores.md): Catálogo estable de códigos de error, forma del envelope de error, qué se puede reintentar y cómo lo hace el SDK.
- [Seguridad y CORS](https://sdk.joyeriazafirox.com/docs/seguridad-cors.md): Buenas prácticas para custodiar credenciales, orígenes registrados, límites por cliente, cabeceras y qué registra la API.
- [Barra pública y temas compartidos](https://sdk.joyeriazafirox.com/docs/barra-compartida.md): Importar la navegación ZAFIROX y compartir una preferencia visual entre sus sitios públicos.

## Referencia

- [Referencia de la API](https://sdk.joyeriazafirox.com/docs/referencia-api.md): Creación y diseños v2, lecturas y OAuth v1, cabeceras, respuestas y esquemas OpenAPI 3.1.
- [Referencia del SDK](https://sdk.joyeriazafirox.com/docs/referencia-sdk.md): API del SDK: lecturas v1 y creación v2 gobernada por la política de pedidos generada.
- [CDN y versiones](https://sdk.joyeriazafirox.com/docs/cdn.md): Rutas del CDN del SDK, canales, versiones inmutables, manifiesto con hashes de integridad y cabeceras de caché.

## Agentes de IA

- [Para agentes de IA](https://sdk.joyeriazafirox.com/docs/para-agentes-ia.md): Formatos legibles por máquinas (llms.txt, Markdown, OpenAPI y manifiesto JSON) y reglas que un agente debe respetar al integrar con Zafirox.

## Proyecto

- [Registro de cambios](https://sdk.joyeriazafirox.com/docs/changelog.md): Versiones publicadas del SDK y de la API pública, con los cambios relevantes para las integraciones.

## Referencia legible por máquinas

- [OpenAPI 3.1 de creación v2](https://sdk.joyeriazafirox.com/openapi/v2.yaml): generado por la política de pedidos; payload cerrado y carga de diseños
- [OpenAPI 3.1 de lecturas y OAuth v1](https://sdk.joyeriazafirox.com/openapi/v1.yaml): rutas que conservan v1
- [Manifiesto para agentes](https://sdk.joyeriazafirox.com/ai/manifest.json): URLs, scopes, códigos de error, versiones del CDN e índice de páginas en JSON
- [Manifiesto del CDN](https://sdk.joyeriazafirox.com/cdn/manifest.json): versiones publicadas del SDK con hashes de integridad (SRI)
- [Documentación completa en un solo archivo](https://sdk.joyeriazafirox.com/llms-full.txt)