# Descripción general

> Qué ofrece la API pública de clientes de Zafirox, qué puede hacer el SDK y cómo está organizada esta documentación.

La **API pública de clientes** permite que un programa de un cliente de Zafirox —un ERP, un backend en Node.js o Replit, una app estática en el navegador— trabaje con su propia información sin usar la aplicación web. OAuth y las lecturas están en `/api/v1/client`; la creación de pedidos y carga de diseños usan `/api/v2/client` una vez publicado el soporte v2. El **SDK TypeScript/JavaScript** `@zafirox/client-sdk` es el cliente oficial y se distribuye desde este sitio.

## Qué puedes hacer

| Capacidad | Operación | Scope necesario |
| --- | --- | --- |
| Cargar diseños autorizados para una orden | `POST /api/v2/client/order-designs` | `orders:create` |
| Crear una orden desde la cuenta principal o uno de sus masters | `POST /api/v2/client/orders` | `orders:create` |
| Listar las órdenes de la cuenta y de sus masters | `GET /orders` | `orders:read` |
| Consultar la cuenta principal y su saldo | `GET /account` | `account:read` |
| Consultar el historial de transacciones | `GET /account/transactions` | `account:transactions:read` |
| Consultar la cartera (órdenes con saldo) | `GET /portfolio` | `portfolio:read` |
| Consultar los pagos aplicados | `GET /portfolio/payments` | `portfolio:payments:read` |

No se publican depósitos, retiros, transferencias, liquidaciones, reversas, administración de usuarios ni operaciones contables.

## Principios del contrato

- **El servidor decide el alcance.** El token identifica a un actor; Zafirox resuelve si es el titular de una empresa o un master activo y qué UIDs puede ver. Ninguna petición acepta un `uid` libre para cambiar de empresa.
- **Dinero exacto.** Los importes son cadenas con dos decimales históricos (`"150000.00"`) o cuatro para COP operativo (`"0.0001"`). Se conserva el texto exacto, sin redondear ni convertir a números de coma flotante.
- **Fechas claras.** Fechas civiles en `AAAA-MM-DD`; instantes en RFC 3339 con desplazamiento horario.
- **Envelope estable.** Toda respuesta JSON tiene la forma `{ "data": …, "meta": { "api_version", "request_id", "pagination"? }, "errors": [] }`.
- **Errores con código.** Cada error lleva un `code` estable, `message`, `retryable` y, cuando aplica, `field` y `diagnostic_id`.
- **Idempotencia en escrituras.** Crear una orden exige la cabecera `Idempotency-Key`; repetir la misma clave con el mismo payload devuelve la misma orden con `replayed: true`.
- **Versionado independiente.** La versión HTTP (`v1` para lectura, `v2` para creación) y la versión de política de pedidos son identidades distintas. El SDK valida el envelope correspondiente a cada ruta.

## Cómo está organizada la documentación

- **Comenzar:** [inicio rápido](/docs/inicio-rapido) con ejemplos para Node.js, Replit, navegador, PHP y cURL, e [instalación](/docs/instalacion) del SDK desde el CDN o como paquete npm.
- **Guías:** [autenticación](/docs/autenticacion), [órdenes](/docs/ordenes), [cuenta](/docs/cuenta), [cartera y pagos](/docs/cartera-y-pagos), [paginación](/docs/paginacion), [errores y reintentos](/docs/errores) y [seguridad y CORS](/docs/seguridad-cors).
- **Referencia:** [rutas y payloads](/docs/referencia-api), [clases del SDK](/docs/referencia-sdk) y el [CDN](/docs/cdn). Esquemas: [creación v2](/openapi/v2.yaml) y [lecturas/OAuth v1](/openapi/v1.yaml).
- **Agentes de IA:** esta documentación también se publica en formatos para modelos de lenguaje; ver [para agentes de IA](/docs/para-agentes-ia).

> **Nota:** para obtener credenciales (`client_id` y `client_secret`) y registrar los orígenes de tu aplicación, contacta con Zafirox. Las credenciales se emiten por integración, con los scopes mínimos que necesites.