Ferretería Clarita
Inicio › Documentación de la API

Documentación de la API

Ferretería Clarita gestiona ventas, stock, compras, caja y su tienda online con ERProva. La parte pública de esa API responde desde este dominio (www.ferreteriaclarita.com.ar) y desde el del sistema (clarita.ferreteriaclarita.com.ar), en formato JSON. Esta página resume los endpoints; la especificación completa y tipada, en formato OpenAPI 3.1, está en /openapi.json (cada operación con operationId, descripción, parámetros y esquemas de respuesta, lista para function calling).

Endpoints

MétodoRutaQué hace
GET/api/healthEstado del servicio
Responde { ok: true, ... } si el sistema está en línea. Sin autenticación.
GET/api/auth/identidadIdentidad pública del comercio
Nombre, razón social, CUIT, domicilio, teléfonos, e-mail, Instagram, colores de marca y las sucursales de Ferretería Clarita con dirección, teléfono y horario. Sin autenticación.
GET/api/tienda/configConfiguración pública de la tienda online
tiendaActiva (si la tienda está publicada), nombre, sucursales, medios de pago y envíos que ve el cliente. Sin autenticación; con CORS abierto (este sitio la consulta para mostrar u ocultar los botones de la tienda).
GET/api/publico/confianzaEstado y transparencia del sistema
Versión en producción, tiempo en línea, HTTPS, base de datos propia y último backup automático. Sin autenticación.
POST/api/auth/loginInicio de sesión (usuarios del comercio)
Cuerpo { "usuario", "clave" }; devuelve un token JWT que se manda como Authorization: Bearer <token> al resto de la API privada (artículos, ventas, stock, clientes...), que no se publica porque expone datos del negocio.
POST/api/asistente/externoAsistente con IA desde afuera del panel
Pregunta en castellano sobre los datos reales del negocio (ventas, stock, caja, deudas). Requiere la clave de integración del comercio (X-Api-Key).
POST/api/mcpServidor MCP (Model Context Protocol)
JSON-RPC 2.0 sobre HTTP (transporte streamable HTTP, sin stream SSE). initialize y ping responden sin clave; tools/list y tools/call requieren X-Api-Key. Herramientas de solo lectura sobre ventas, stock, caja, clientes, cuentas por cobrar/pagar y pedidos.

Autenticación

Los endpoints marcados «sin autenticación» se llaman directamente. La API privada usa el token JWT que devuelve POST /api/auth/login, en el header Authorization: Bearer <token>. Las integraciones externas (asistente y servidor MCP) usan una clave de integración propia del comercio, que la administración de Ferretería Clarita genera desde su panel (Asistente IA → WhatsApp, n8n y MCP → Generar clave), en el header X-Api-Key (o Authorization: Bearer <clave>). No hay claves globales ni acceso público a datos de negocio.

Ejemplos

curl -s https://www.ferreteriaclarita.com.ar/api/auth/identidad
curl -s https://www.ferreteriaclarita.com.ar/api/tienda/config | jq .tiendaActiva
curl -s https://www.ferreteriaclarita.com.ar/api/publico/confianza | jq .version

# inicio de sesión (usuarios del comercio)
curl -s -X POST https://www.ferreteriaclarita.com.ar/api/auth/login -H "Content-Type: application/json" -d '{"usuario":"…","clave":"…"}'

# servidor MCP: initialize no requiere clave; tools/list y tools/call sí
curl -s -X POST https://www.ferreteriaclarita.com.ar/api/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"mi-agente","version":"1.0"}}}'
curl -s -X POST https://www.ferreteriaclarita.com.ar/api/mcp -H "Content-Type: application/json" -H "X-Api-Key: <clave del comercio>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Errores

Siempre JSON, con el mismo formato: { "error": "mensaje legible", "codigo": "CODIGO_ESTABLE", "detalle"?: … }. Los códigos (DATOS_INVALIDOS, NO_AUTENTICADO, SIN_PERMISO, NO_ENCONTRADO, CONFLICTO, DEMASIADAS_SOLICITUDES, METODO_NO_PERMITIDO…) no cambian aunque cambie el texto; el esquema Error está en /openapi.json. Si el sistema no está disponible, este dominio responde 503 con { "codigo": "NO_DISPONIBLE" }.

Versionado y límites

La versión de la API va en el header API-Version (hoy 2.0), no en la URL; las deprecaciones se anuncian con Deprecation y Sunset (RFC 8594) con 90 días de aviso — política completa en /docs/versionado. Hay límite de solicitudes por IP en el ingreso y en las integraciones (429 DEMASIADAS_SOLICITUDES). Cada página de este sitio también existe en Markdown: pedila con Accept: text/markdown.

Enlaces