Inicio rápido de la API REST v400
Usa la especificación OpenAPI pública como contrato de rutas, parámetros, esquemas y autenticación. La Referencia de API presenta ese contrato de forma interactiva. Las peticiones alcanzan los datos reales del proyecto elegido; empieza con lecturas.
Proyecto, idioma y autenticación
La URL base es https://api.ordering.co/v400/<language>/<project>. Usa el código y el idioma reales del proyecto, por ejemplo en; el valor demo de la especificación no identifica tu proyecto ni ofrece un sandbox. Cambiar credenciales no corrige un código de proyecto equivocado.
Crea una API key REST en API Keys del Dashboard. El quickstart público para desarrolladores permite obtener una clave REST separada al seleccionar Also give my agent the REST API. Clonar el helper no requiere pertenecer a GitHub; acceder a los datos de un proyecto sí requiere tu propia cuenta Ordering y consentimiento.
Revisa el bloque security de cada operación:
| Esquema de seguridad | Credencial |
|---|---|
apiKeyAuth | API key REST en X-Api-Key. Nunca en Authorization. |
bearerAuth | JWT de sesión obtenido de POST /auth en Authorization: Bearer <session token>. |
Seguridad vacía de la operación ([]) | Operación pública, sin credencial. |
Una clave MCP no autentica peticiones REST. Las API keys no tienen scope MCP read/write ni vencen: actúan con tus permisos hasta que las revoques. Guárdalas en variables de entorno del servidor o un gestor de secretos, fuera de bundles web/móviles y de Git. No registres cabeceras de autorización ni respuestas con datos de clientes.
Consulta los cinco pedidos más recientes
GET /orders acepta autenticación por API key o sesión. Sin mode=dashboard, limita los resultados a los pedidos del usuario como cliente. El modo Dashboard aplica los permisos del rol operativo; no evita controles de acceso. El ejemplo actual del quickstart ordena por ID descendente:
# Dentro de un quickstart autorizado; el helper lee sus credenciales locales.
./ordering api GET "/orders?orderBy=-id&page=1&page_size=5&mode=dashboard"
En una integración de servidor, configura ORDERING_API_KEY, ORDERING_PROJECT y ORDERING_LANGUAGE en su entorno privado. Este ejemplo Node.js hace una lectura sin credenciales hardcodeadas:
const { ORDERING_API_KEY, ORDERING_PROJECT, ORDERING_LANGUAGE } = process.env;
if (!ORDERING_API_KEY || !ORDERING_PROJECT || !ORDERING_LANGUAGE) {
throw new Error('Configura API key, código de proyecto e idioma en el servidor');
}
const base = `https://api.ordering.co/v400/${encodeURIComponent(ORDERING_LANGUAGE)}/${encodeURIComponent(ORDERING_PROJECT)}`;
const url = new URL(`${base}/orders`);
url.search = new URLSearchParams({
orderBy: '-id', page: '1', page_size: '5', mode: 'dashboard',
}).toString();
const response = await fetch(url, {
headers: { 'X-Api-Key': ORDERING_API_KEY, Accept: 'application/json' },
});
const body = await response.json();
if (!response.ok || body.error) {
throw new Error(`Falló la petición a Ordering (HTTP ${response.status})`);
}
const orders = body.result;
Revisa Listar pedidos para los parámetros específicos. ID descendente es el orden documentado por el quickstart; no garantiza orden por otra fecha de negocio. Un resultado vacío puede ser válido. No publiques datos de clientes como evidencia de configuración.
Paginación, campos y filtros
El soporte de listas varía según la operación. Consulta sus parámetros antes de usar page (desde 1), page_size, orderBy, params o where. orderBy=-id ordena por ID descendente. params selecciona campos admitidos; una selección inválida puede devolver todos los campos, por lo que no es una barrera de seguridad. where es un filtro JSON sobre campos declarados filtrables: consulta x-ordering-whereable en el esquema en lugar de inventar campos u operadores.
Lee el bloque pagination, cuando exista, antes de pedir la siguiente página. No combines paginación por página con limit/offset/start salvo que la operación lo documente. Consulta Paginación. Comprueba tanto el estado HTTP como error en el envelope. Ante 429, espera y reintenta más tarde; evita bucles sin límite.
Permisos read/write del MCP y cambios REST
Configurar MCP conecta un cliente AI con una clave personal separada. Empieza con read: descubre operaciones con search_operations, inspecciónalas con describe_operation y usa read_operation. Solo una clave write expone write_operation, limitada al catálogo y sus campos admitidos. Ningún scope concede acceso REST arbitrario.
No hay aprobación implícita para cambiar datos reales. Antes de escribir, identifica proyecto, destino, método y cambios exactos, y solicita confirmación explícita del usuario. Con el quickstart, las llamadas REST que no sean GET requieren esa confirmación antes de usar ./ordering api --yes. Si el resultado es incierto, lee el destino antes de repetir. Revocar una API key REST y una clave MCP son operaciones separadas.