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
uidlibre 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
codeestable,message,retryabley, cuando aplica,fieldydiagnostic_id. - Idempotencia en escrituras. Crear una orden exige la cabecera
Idempotency-Key; repetir la misma clave con el mismo payload devuelve la misma orden conreplayed: true. - Versionado independiente. La versión HTTP (
v1para lectura,v2para 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 con ejemplos para Node.js, Replit, navegador, PHP y cURL, e instalación del SDK desde el CDN o como paquete npm.
- Guías: autenticación, órdenes, cuenta, cartera y pagos, paginación, errores y reintentos y seguridad y CORS.
- Referencia: rutas y payloads, clases del SDK y el CDN. Esquemas: creación v2 y lecturas/OAuth v1.
- Agentes de IA: esta documentación también se publica en formatos para modelos de lenguaje; ver para agentes de IA.
Nota: para obtener credenciales (
client_idyclient_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.