Para agentes de IA · Zafirox SDK

Formatos legibles por máquinas (llms.txt, Markdown, OpenAPI y manifiesto JSON) y reglas que un agente debe respetar al integrar con Zafirox.

Esta documentación se publica también en formatos pensados para modelos de lenguaje y agentes de programación. Todos se generan desde la misma fuente que las páginas para personas, así que nunca divergen.

Puntos de entrada

Recurso	URL	Uso
Índice `llms.txt`	/llms.txt	Resumen y enlaces a cada página en Markdown (llmstxt.org)
Documentación completa	/llms-full.txt	Todas las páginas concatenadas en un solo Markdown
Página en Markdown	`/docs/<slug>.md` o `Accept: text/markdown`	Una página concreta sin HTML
Manifiesto para agentes	/ai/manifest.json	URLs, operaciones, scopes, códigos de error, versiones del CDN e índice de páginas
OpenAPI 3.1 de creación v2	/openapi/v2.yaml	Esquema generado por la política de pedidos
OpenAPI 3.1 de lecturas v1	/openapi/v1.yaml	OAuth, órdenes, cuenta, cartera y pagos
Manifiesto del CDN	/cdn/manifest.json	Versiones del SDK con hashes de integridad
Tipos del SDK	`/cdn/v1/index.d.ts`	Firmas TypeScript exactas

Ejemplo de instrucción para un agente:

Lee https://sdk.joyeriazafirox.com/llms.txt y, para la integración,
https://sdk.joyeriazafirox.com/docs/ordenes.md y
https://sdk.joyeriazafirox.com/openapi/v2.yaml para crear y
/openapi/v1.yaml para lecturas y OAuth. Verifica en /cdn/manifest.json
que la versión publicada del SDK incluya la creación v2 antes de usarla.

Reglas que un agente debe respetar

**Nunca escribas el client_secret en código de navegador ni en repositorios.** Léelo de variables de entorno o secretos del entorno de ejecución.
Pide los scopes mínimos para la tarea (orders:read para leer, orders:create sólo si vas a crear).
Trata el dinero como cadena decimal. No uses parseFloat/Number sobre balance, price, amount, order_total, paid_total; usa una biblioteca decimal.
**Envía Idempotency-Key** en cada POST /api/v2/client/orders y reutilízala en los reintentos; un timeout no significa que la orden no se haya creado.
No inventes campos. La creación v2 es cerrada y exige policy_version y policy_sha256; una clave desconocida responde 422. Consulta el OpenAPI v2 antes de añadir un campo.
**Pagina con next_cursor** hasta has_more: false; nunca construyas cursores.
**Reintenta sólo retryable: true, timeouts y fallos de red**, respetando Retry-After. No reintentes 401, 403, 404, 409 IDEMPOTENCY_CONFLICT ni 422.
**Conserva request_id** en los registros de tu integración para poder citarlo a soporte.
**No cambies de empresa con un uid.** El alcance lo decide el servidor; subject_uid sólo filtra dentro del alcance autorizado.
Fija una versión del SDK en producción y verifica el hash del manifiesto. El CDN 1.1.0 todavía no implementa creación v2.
Carga primero los diseños mediante POST /api/v2/client/order-designs con 1–5 archivos. Usa únicamente las referencias opacas data.design_refs; el SDK no sube archivos.
Aplica las extensiones de política x-order-policy-*: los límites de texto se miden después de String.trim() ECMAScript en unidades UTF-16. Un validador JSON Schema genérico no ejecuta matches/cook.

Resumen del contrato para prompts

OAuth y lecturas: https://datacenterv2.joyeriazafirox.com/api/v1/client
Creación y diseños: https://datacenterv2.joyeriazafirox.com/api/v2/client (publicación pendiente)
Auth servidor: POST /oauth/token (client_credentials, Basic o cuerpo) → Bearer 15 min
Auth persona («Acceder con Zafirox»): GET /oauth/authorize (code + PKCE S256, redirect_uri exacta, state)
  → 302 accounts.joyeriazafirox.com → redirect_uri?code&state → POST /oauth/token grant_type=authorization_code
  (code, redirect_uri, code_verifier, client_id) → access_token + refresh_token (rotación, grant_type=refresh_token)
Envelope v1 lecturas: { data, meta: { api_version:"1", request_id, pagination? }, errors[] }
Envelope v2 creación: { data, meta: { api_version:"2", request_id, policy_version, policy_sha256 }, errors[] }
Operaciones v2: POST /order-designs (orders:create, multipart files 1..5),
  POST /orders (orders:create, Idempotency-Key, jewel.design_refs 1..5)
Operaciones v1: GET /orders (orders:read),
  GET /account (account:read), GET /account/transactions (account:transactions:read),
  GET /portfolio (portfolio:read), GET /portfolio/payments (portfolio:payments:read)
Dinero: "150000.00" (string). Fechas: AAAA-MM-DD; instantes RFC 3339.
Paginación: limit 1..100, cursor opaco. Errores: code estable + retryable.
SDK: import { ZafiroxClient, createClientCredentialsProvider, createAuthorizationCodeProvider, createStaticTokenProvider } from '@zafirox/client-sdk'
POST /api/v1/client/orders: 410 ORDER_CREATE_VERSION_RETIRED al publicar v2.

Cómo se mantiene

Las páginas viven como Markdown con front matter en el repositorio del sitio; el HTML, llms.txt, llms-full.txt y el manifiesto se generan en cada petición desde ese Markdown. Si detectas una discrepancia entre esta documentación y el comportamiento real de la API, informa a Zafirox citando la URL de la página y el request_id de la respuesta.