Integradores

Esta sección está dirigida a desarrolladores que conectan los flujos de trabajo de Mockomat con sistemas de ingeniería más amplios. Ya sea que estés construyendo un frontend que consume una API mock de Mockomat, automatizando la validación de modelos en CI/CD, o integrando Mockomat en el pipeline de desarrollo de tu equipo, esta página cubre los patrones y prácticas que necesitas.

Resumen de endpoints API

Mockomat expone dos superficies API distintas:

API	Endpoint	Propósito	Autenticación
API de gestión	GET /graphql	CRUD de proyectos, configuración de modelo, gestión de usuarios	JWT (basado en sesión)
API Mock Runtime	POST /mock/{slug}/graphql	Consultar datos mock, probar comportamiento de dominio	Clave API (Authorization: Bearer mck_…); proyectos de invitado: token de compartición

La API de gestión es utilizada por la aplicación web de Mockomat y las herramientas administrativas. La API mock runtime es lo que tus aplicaciones consumen como backend mock.

Autenticación

Cada solicitud a la API mock runtime de un proyecto de tu cuenta lleva una clave API. Las solicitudes sin una clave válida se rechazan, sea cual sea la configuración de compartición de la vista previa del proyecto: un enlace de compartición abre la página de vista previa, no la API.

Claves API

Creas las claves en la aplicación en Cuenta → Claves API, para el proyecto activo. Las claves API están incluidas a partir del plan Professional. Cada clave:

• Pertenece a un solo proyecto y solo responde para ese proyecto
• Se muestra completa una sola vez, al crearla — guárdala como una contraseña
• Puede tener una fecha de caducidad y revocarse en cualquier momento
• Tiene un scope: Runtime consulta datos mock, Full también accede a la API de gestión; una clave Management no puede consultar el runtime

Envía la clave como bearer token:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

La cabecera X-API-Key: mck_your_api_key también funciona.

Mantén la clave fuera del código del navegador

Una clave API es un secreto. Llama a la API mock desde código del lado del servidor, desde tu CI o a través de un proxy del servidor de desarrollo que añada la cabecera (paso 4 del flujo de integración más abajo); nunca incluyas la clave en un bundle de frontend.

Proyectos de invitado

Un proyecto de invitado (sin cuenta) no tiene claves API. Su endpoint acepta el token de compartición del proyecto — el de su enlace de compartición de vista previa — como parámetro de consulta:

curl -X POST "https://api.mockomat.com/mock/my-guest-project/graphql?token=<share-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name } total } }"}'

Las solicitudes de invitado cuentan contra la cuota diaria de la sesión de invitado.

Tokens de actor (opcionales)

Los tokens de actor distinguen a los consumidores de una misma clave API, para poder limitar el uso simultáneo de una clave. Son opcionales: una solicitud solo con la clave API se atiende.

1. Solicita un token con tu clave API:

curl -X POST https://api.mockomat.com/runtime/actors \
  -H "Authorization: Bearer mck_your_api_key"

Respuesta:

{
  "actorToken": "act_abc123...",
  "expiresInSeconds": 900,
  "maxActors": 1,
  "currentActors": 1
}

2. Envíalo con tus solicitudes runtime:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "X-Actor-Token: act_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

3. Caducidad por inactividad — un token caduca tras 15 minutos sin solicitudes; cada solicitud lo prolonga. Mientras todos los espacios de actor de una clave estén ocupados, un actor nuevo recibe 429 MAX_ACTIVE_ACTORS_REACHED con una cabecera Retry-After.

int-01-authenticationMissing

Punto de entrada de integración con configuración de autenticación y contexto.

Patrones de consultas

Consulta de lista básica

query {
  products(page: 1, pageSize: 20) {
    items {
      id
      name
      price
      category {
        id
        name
      }
    }
    total
    page
    pageSize
  }
}

Consulta de detalle

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Consulta con filtrado

Los argumentos son parámetros que la operación define en el diseño de API (aquí minPrice sobre price con gte, category con eq); consulta el Runtime para operadores, búsqueda y paginación.

query {
  products(minPrice: 10, category: "electronics", pageSize: 50) {
    items {
      id
      name
      price
    }
    total
  }
}

Consulta ordenada y paginada

query {
  products(sortField: "price", sortDirection: ASC, page: 2, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
    page
    pageSize
  }
}

Consulta con relaciones anidadas

query {
  customers(pageSize: 10) {
    items {
      id
      firstName
      lastName
      orders {
        id
        totalAmount
        createdAt
      }
    }
    total
  }
}

Flujo de integración recomendado

1. Definir un alcance de dominio estable

Antes de integrar, identifica qué entidades y consultas tu aplicación consumirá. No integres contra un modelo que aún cambia frecuentemente — espera hasta que la estructura principal sea estable.

2. Fijar nombrado y contratos de campos

Trata el esquema GraphQL como un contrato. Una vez que tu aplicación depende de nombres de consultas y estructuras de campos específicos, los cambios en esos nombres romperán la integración. Usa la vista de diseño API en Mockomat para finalizar nombres de consultas antes de conectar consumidores.

3. Validar el comportamiento runtime

Ejecuta consultas completas a través de la previsualización runtime y verifica:

• Los tipos de campos coinciden con lo que tu aplicación espera
• El anidamiento de relaciones funciona correctamente
• Los filtros devuelven los subconjuntos esperados
• La paginación produce transiciones de página limpias

4. Integrar sistemas consumidores

Conecta tu suite de pruebas, tu backend-for-frontend u otros consumidores al endpoint mock. Mantén el endpoint y la clave API en la configuración para poder cambiar entre Mockomat y tu backend real.

Una aplicación frontend llega a la API mock a través del proxy de su servidor de desarrollo, que añade la clave en el lado del servidor; así la clave nunca acaba en el bundle:

// vite.config.ts — reenvía /mock-api a Mockomat y añade la clave API
export default defineConfig({
  server: {
    proxy: {
      '/mock-api': {
        target: 'https://api.mockomat.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/mock-api/, '/mock/my-project'),
        headers: { Authorization: `Bearer ${process.env.MOCKOMAT_API_KEY}` },
      },
    },
  },
});

// environment.ts — la aplicación solo conoce la ruta del proxy
export const environment = {
  apiUrl: '/mock-api/graphql',
  // Cambiar al backend real cuando esté listo:
  // apiUrl: 'https://api.myapp.com/graphql',
};

5. Promover a exportación/implementación

Cuando el contrato de API mock es estable y tu frontend funciona correctamente contra él, usa la funcionalidad de Exportación para generar un backend de producción que implemente el mismo contrato.

int-02-ci-cd-flowMissing

Patrón de integración CI/CD con puntos de control de modelo y runtime.

CI/CD y automatización

Las APIs mock de Mockomat pueden integrarse en tu pipeline CI/CD para validar el comportamiento frontend contra un backend mock estable.

Patrones de integración en pipeline

Validación de contrato — ejecuta verificaciones de comparación de esquema cuando los modelos cambian para detectar cambios que rompan antes de que lleguen a los consumidores.

Pruebas de integración — apunta tu suite de pruebas de integración al endpoint de Mockomat para verificar el comportamiento frontend contra datos mock realistas.

Validación de previsualización — antes de hacer merge de cambios de modelo, valida que el runtime produce los resultados esperados consultando el endpoint de previsualización programáticamente.

Ejemplo de pasos de pipeline

# Ejemplo de paso de pipeline CI
steps:
  - name: Run integration tests against mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: npm run test:integration

  - name: Smoke-check the mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: |
      # Hace fallar el paso con 401/403/404: clave ausente, revocada o de otro proyecto
      curl -sf "$API_URL" \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"query":"{ products(page: 1, pageSize: 1) { items { id } total } }"}'

Versionado de artefactos generados

Al usar la funcionalidad de exportación, versione el código backend generado junto con tu aplicación:

• Haz commit del código generado en una rama o repositorio dedicado.
• Etiqueta las exportaciones con la versión del modelo o la fecha.
• Incluya un changelog resumiendo los cambios de modelo desde la última exportación.
• Revisa los diffs del código generado antes de hacer merge a la rama principal.

Limitación de tasa

Se aplican tres límites a la API mock runtime:

Alcance	Límite	Al alcanzarlo
Por dirección IP	60 solicitudes por minuto	429 TOO_MANY_REQUESTS — reintenta un minuto después
Por cuenta	La cuota de solicitudes de tu plan (por día o por mes)	429 TOO_MANY_REQUESTS hasta que la cuota se restablezca
Por clave API	Actores simultáneos — solo si envías tokens de actor	429 MAX_ACTIVE_ACTORS_REACHED con una cabecera Retry-After

Los proyectos de invitado cuentan contra la cuota diaria de la sesión de invitado.

Gestión de errores

Una solicitud rechazada responde con un estado HTTP de error y un cuerpo JSON. Decide según su code:

Estado HTTP	Código	Significado	Acción
400	Bad Request	GraphQL no válido, operación desconocida o desactivada, cuerpo mal formado	Leer message; corregir la consulta o el nombre de la operación
401	UNAUTHENTICATED	No se envió ninguna clave API (proyecto de invitado: token de compartición ausente o incorrecto)	Enviar Authorization: Bearer mck_…
401	API_KEY_INVALID	Clave desconocida, revocada o eliminada	Crear una clave nueva
401	API_KEY_EXPIRED	La fecha de caducidad de la clave ha pasado	Crear una clave nueva
401	ACTOR_TOKEN_INVALID	X-Actor-Token mal formado	Solicitar un token en /runtime/actors u omitir la cabecera
403	API_KEY_SCOPE_INSUFFICIENT	Clave solo de gestión	Usar una clave Runtime o Full
404	PROJECT_NOT_FOUND	Slug desconocido, o un proyecto al que la clave no pertenece (en /runtime/actors: el proyecto de la clave fue eliminado)	Verificar el slug; usar una clave de este proyecto
429	TOO_MANY_REQUESTS	Límite por IP o cuota del plan alcanzados	Esperar y reintentar
429	MAX_ACTIVE_ACTORS_REACHED	Todos los espacios de actor de la clave están ocupados	Esperar la duración de Retry-After
429	RATE_LIMIT_EXCEEDED	Demasiadas solicitudes de token de actor para una clave (POST /runtime/actors)	Esperar la duración de Retry-After; reutilizar un token mientras siga activo
503	QUERY_TIMEOUT	La consulta tardó demasiado	Reintentar; acotar la consulta

Formato de respuesta de error

{
  "statusCode": 401,
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID",
  "path": "/mock/my-project/graphql",
  "timestamp": "2026-10-05T09:30:00.000Z"
}

Un 429 con una cabecera Retry-After también incluye retryAfter (segundos) en el cuerpo. Una solicitud atendida responde 200 con un cuerpo GraphQL; los problemas a nivel de datos llegan en errors[] — por ejemplo, extensions.code NOT_READY significa que la tabla aún no está vinculada a datos.

Observabilidad y diagnósticos

Sigue estas señales clave a través de los entornos para mantener la fiabilidad de la integración:

Métricas clave

• Estabilidad de consultas — ¿las respuestas están estructuradas de manera consistente? Vigila los cambios de esquema inesperados.
• Deriva de la forma de respuesta — ¿los tipos de campos o niveles de anidamiento cambian entre actualizaciones del modelo?
• Fiabilidad de lookups de relación — ¿las consultas anidadas se resuelven sistemáticamente de forma correcta?
• Patrones de errores y timeouts — ¿algunas consultas son sistemáticamente lentas o fallan?
• Proximidad de límites de tasa — ¿qué tan cerca está de alcanzar los límites de solicitudes o concurrencia?

Recomendaciones de monitoreo

• Registra todas las respuestas API (o al menos los códigos de estado y tiempos de respuesta) en tu aplicación consumidora.
• Configura alertas para respuestas HTTP 429 y 401 — indican problemas de configuración o capacidad.
• Compara periódicamente los esquemas de respuesta contra una baseline para detectar derivas no intencionales.
• Monitorea los patrones de renovación de tokens de actor para optimizar tu estrategia de concurrencia.

int-03-observabilityMissing

Puntos de control de observabilidad para la fiabilidad de la integración.

Buena práctica

Developer / Integrator

Trata los artefactos de Mockomat como activos contract-first. Mantén la intención del modelo, el comportamiento runtime y las decisiones de implementación trazables en el mismo conjunto de cambios. Cuando tu frontend dependa de una forma de consulta específica, documenta esa dependencia y valídela en CI.

Nota de integración Enterprise

Enterprise User

Para entornos Enterprise, usa claves API separadas por entorno (desarrollo, staging, producción). Esto te permite seguir el uso por entorno y rotar claves independientemente. Combina con tokens de actor para controlar exactamente cuántos consumidores concurrentes soporta cada entorno.