API de Moon Inventory

La API usa convenciones REST: sustantivos en la ruta, verbos HTTP para la acción, códigos de estado estándar y JSON en peticiones y respuestas.

URL base

https://mooninventoryapi.onrender.com/api

Todas las rutas de esta documentación se muestran completas e incluyen el prefijo /api. La API no está versionada por URL todavía; los cambios incompatibles se anunciarán con antelación por correo a los administradores de la organización.

Comprobación rápida

curl https://mooninventoryapi.onrender.com/api/health

El acceso programático es una funcionalidad del plan Empresarial. Las claves de API solo pueden crearse y usarse si tu organización tiene ese plan activo.

Si tu plan no lo incluye, cualquier petición autenticada con una clave responde 403 con el código FEATURE_NOT_IN_PLAN.

La API acepta dos tipos de credencial. Para integraciones usa siempre una clave de API; el token de sesión (JWT) existe para la aplicación web y caduca a las 24 horas.

1. Crear una clave

Desde la aplicación: Configuración → Claves de API → Crear clave. La clave se muestra una sola vez; guárdala en tu gestor de secretos en ese momento, porque solo almacenamos su hash y no podemos recuperarla después.

Una clave tiene el formato:

mk_live_XSb9m2q7Kv1pLd0zR4tYhN8jWcE3gAuF6oQi5rTvBnM

2. Enviarla en cada petición

Se acepta en cualquiera de estas dos cabeceras — usa una, no ambas:

Authorization: Bearer mk_live_TU_CLAVE
# o bien
X-API-Key: mk_live_TU_CLAVE

Ejemplos

curl -s "https://mooninventoryapi.onrender.com/api/products/products?page=1&limit=20" \
  -H "Authorization: Bearer mk_live_TU_CLAVE"

const res = await fetch("https://mooninventoryapi.onrender.com/api/products/products?limit=20", {
  headers: { "X-API-Key": process.env.MOON_API_KEY },
});

if (!res.ok) {
  const error = await res.json();
  throw new Error(`${res.status} ${error.code ?? ""}: ${error.message}`);
}

const { data } = await res.json();

import os, requests

res = requests.get(
    "https://mooninventoryapi.onrender.com/api/products/products",
    headers={"X-API-Key": os.environ["MOON_API_KEY"]},
    params={"page": 1, "limit": 20},
    timeout=30,
)
res.raise_for_status()
data = res.json()["data"]

Cada clave lleva uno o más scopes, que limitan los verbos HTTP permitidos:

Un intento de escritura con una clave de solo lectura responde 403 con INSUFFICIENT_API_SCOPE.

Las respuestas correctas devuelven status: "success" y el contenido dentro de data.

{
  "status": "success",
  "data": {
    "products": [ { "_id": "66f1…", "name": "Café molido 1lb", "price": 350 } ],
    "total": 128,
    "page": 1,
    "totalPages": 7
  }
}

La forma exacta de data depende del endpoint: la clave interna suele llamarse como el recurso (products, sales…). Los identificadores son ObjectId de 24 caracteres hexadecimales y las fechas van en ISO 8601 (UTC).

Los errores usan códigos HTTP estándar y devuelven status: "error" con un mensaje legible. Cuando el error es accionable incluye además un code estable — usa ese campo en tu lógica, no el texto del mensaje, que puede cambiar.

{
  "status": "error",
  "code": "INSUFFICIENT_API_SCOPE",
  "message": "This API key is read-only. Create a key with the 'write' scope to perform this operation.",
  "data": { "scopes": ["read"] }
}

• 100 peticiones cada 15 minutos por IP sobre la API en general. Al superarlo recibes 429.
• Las respuestas incluyen las cabeceras estándar RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Úsalas para regular tu ritmo en lugar de esperar al 429.
• Tamaño máximo del cuerpo: 10 KB en JSON. Para cargas grandes usa los endpoints de /api/upload.
• Los endpoints de IA consumen además los créditos mensuales de tu plan y responden 402 cuando se agotan.

Los listados aceptan page (desde 1) y limit, y devuelven el total junto a los resultados.

curl -s "https://mooninventoryapi.onrender.com/api/sales/invoices?page=2&limit=50" \
  -H "X-API-Key: mk_live_TU_CLAVE"

Muchos listados aceptan además filtros propios del recurso — rangos de fecha (startDate, endDate), estado, categoría o búsqueda por texto. Los parámetros no reconocidos se ignoran, así que compruébalos con cuidado.

Estos endpoints se usan solo con la sesión de la aplicación. Una clave de API no puede crear ni revocar claves — así, una clave filtrada no puede perpetuarse a sí misma.

Crear una clave

POST /api/api-keys
{
  "name": "Integración ERP",
  "scopes": ["read", "write"],
  "expiresInDays": 365
}

scopes por defecto es ["read"]; expiresInDays es opcional (1–3650) y si se omite la clave no caduca.

{
  "status": "success",
  "message": "Guarda esta clave ahora: por seguridad no volverá a mostrarse completa.",
  "data": {
    "key": {
      "id": "66f1…", "name": "Integración ERP",
      "prefix": "mk_live_XSb9m2q7", "scopes": ["read","write"],
      "expiresAt": "2027-09-04T00:00:00.000Z", "revokedAt": null
    },
    "plaintext": "mk_live_XSb9m2q7Kv1pLd0zR4tYhN8jWcE3gAuF6oQi5rTvBnM"
  }
}

• Guardamos únicamente un hash SHA-256 de la clave. Ni nosotros podemos recuperar el texto plano, por eso solo se muestra al crearla.
• La comparación es de tiempo constante, de modo que no se puede deducir una clave midiendo tiempos de respuesta.
• Concede el mínimo privilegio: usa read salvo que la integración escriba de verdad, y créala desde un usuario de servicio con un rol acotado.
• Rota las claves periódicamente con expiresInDays. Crea la nueva, migra la integración y revoca la anterior.
• Guárdalas en variables de entorno o un gestor de secretos. Nunca en el control de versiones ni en código que llegue al navegador.
• Todo el tráfico va sobre HTTPS. Las peticiones desde un navegador están sujetas a una lista de orígenes permitidos (CORS); las llamadas de servidor a servidor no se ven afectadas.

420 endpoints en 39 módulos. Los módulos marcados con un candado exigen un plan concreto: la comprobación ocurre en el servidor, así que una clave de un plan inferior recibe 403 aunque conozca la ruta.

Preferimos decirte esto por adelantado a que lo descubras integrando:

• No hay webhooks salientes. Hoy no notificamos cambios a sistemas externos; hay que consultar (polling). Ten en cuenta el límite de peticiones al elegir la frecuencia.
• No hay endpoint de refresco de token. El login devuelve un refreshToken, pero no existe una ruta para canjearlo: una sesión JWT caducada exige volver a autenticarse. Es justamente por esto que las integraciones deben usar claves de API, que no caducan salvo que tú lo indiques.
• La API no está versionada por URL. No hay /v1/. Programa de forma defensiva: ignora los campos que no conozcas en lugar de validar la forma exacta de la respuesta.
• Hay dos superficies de proveedores — /api/suppliers y /api/expenses/suppliers. La aplicación usa la segunda; prefiere esa hasta que unifiquemos.
• Sin entorno de pruebas separado. Las claves operan sobre tus datos reales. Prueba con una organización de prueba o con claves read antes de escribir.

¿Dudas o un comportamiento que no cuadra con esta documentación? Escríbenos desde Configuración → Feedback en la aplicación, e incluye el método, la ruta, la hora aproximada y el code del error. No nos envíes nunca tu clave.