---
title: "Kroel Graphics para desarrolladores"
description: "API pública, servidores MCP y agente A2A de Kroel Graphics."
canonical: https://kroelgraphics.com/developers
last-updated: 2026-11-15
lang: es
---

# Kroel Graphics para desarrolladores y agentes

API pública de Kroel Graphics, estudio de diseño en Tijuana, México. Sirve para que programas y asistentes consulten servicios y contacto, hagan preguntas y envíen una solicitud de cotización a nombre de una persona. No requiere cuenta, llave ni registro.

## Inicio rápido

```bash
curl -s https://kroelgraphics.com/api/v1/servicios
curl -s https://kroelgraphics.com/ask -H 'Content-Type: application/json' -d '{"query":{"text":"¿Hacen portadas de discos?"}}'
```

## Código abierto y terminal

El kit es público en [github.com/kroel-graphics/kroel-graphics](https://github.com/kroel-graphics/kroel-graphics): herramienta de terminal (CLI), habilidad para agentes, manifiesto de plugin y reglas para agentes (`AGENTS.md`). Licencia MIT.

Paquete en npm: [kroel-graphics](https://www.npmjs.com/package/kroel-graphics). Instala el comando `kroel`:

```bash
npx kroel-graphics servicios
npx kroel-graphics cotizar --nombre "Ana" --contacto "+52 664 000 0000" --detalle "Logo para mi cafetería" --prueba
npm install -g kroel-graphics   # deja el comando kroel instalado
```

La herramienta no tiene dependencias y usa esta misma API. Con `--prueba` trabaja contra el sandbox.

## Endpoints

| Método | Ruta | Qué devuelve |
|---|---|---|
| GET | `/api/v1/servicios` | Lista paginada de servicios (`limit`, `offset`), cómo se cotiza y límites |
| GET | `/api/v1/precios` | Precios de arranque en MXN por servicio |
| GET | `/api/v1/contacto` | WhatsApp, formulario de cotización y redes |
| GET | `/api/v1/health` | Estado del servicio |
| POST | `/api/v1/cotizaciones` | Envía una solicitud de cotización; responde `202` con un `id` |
| GET | `/api/v1/cotizaciones/{id}` | Estado de esa solicitud |
| POST | `/ask` | Respuesta a una pregunta en lenguaje natural (NLWeb 0.55) |

- Especificación: [OpenAPI 3.1](https://kroelgraphics.com/openapi.json)
- Catálogo: [/.well-known/api-catalog](https://kroelgraphics.com/.well-known/api-catalog) (RFC 9727)

## Autenticación

Ninguna: no hay cuentas ni tokens. Detalle en [auth.md](https://kroelgraphics.com/auth.md).

## Enviar una solicitud de cotización

```bash
curl -s https://kroelgraphics.com/api/v1/cotizaciones \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: pedido-ana-001' \
  -d '{"nombre":"Ana López","contacto":"+52 664 000 0000","servicio":"Identidad de marca","detalle":"Logo para una cafetería que abre en diciembre.","agente":"mi-asistente"}'
```

Obligatorios: `nombre`, `contacto` (WhatsApp, teléfono o correo de la persona, con su permiso) y `detalle`. La respuesta es `202 Accepted` con `id`, `status: "recibida"` y `status_url`; es un proceso asíncrono: Luis la revisa y contesta a la persona directamente. La respuesta no incluye precio: los precios de arranque están en `GET /api/v1/precios`.

- **Idempotency-Key:** repetir la misma llave durante 24 horas devuelve la misma respuesta (`Idempotency-Replayed: true`) sin crear otra solicitud. La misma llave con otros datos responde `409`.
- **Estado:** `GET /api/v1/cotizaciones/{id}` devuelve el estado. No expone los datos de la persona.
- **Tope:** 6 solicitudes por día por red.

## Entorno de pruebas (sandbox)

`https://kroelgraphics.com/sandbox/api/v1` es la misma API. Las solicitudes de cotización se validan igual y responden `202` con un `id` que empieza con `prueba-`, pero no se guardan ni le llegan a nadie. Las respuestas llevan `X-Sandbox: true`. Úsalo para probar tu integración antes de enviar algo real.

## Versiones

La versión va en la ruta: `/api/v1`. Cada respuesta incluye el encabezado `API-Version`.

**Política de retiro.** Un cambio incompatible sale siempre en una versión nueva (`/api/v2`). La versión anterior sigue funcionando al menos 12 meses después del aviso, y durante ese tiempo responde con los encabezados `Deprecation` y `Sunset` (RFC 9745 y RFC 8594) y un `Link` con `rel="successor-version"`. Hoy aplica a las rutas antiguas sin versión (`/api/servicios`, `/api/contacto`, `/api/health`): ya responden con `Deprecation` y dejarán de funcionar el 15 de noviembre de 2027; usa `/api/v1/...`.

## Paginación

`/api/v1/servicios` pagina por cursor: manda `limit` (1 a 50, por defecto 20) y, para la página siguiente, `cursor` con el valor de `pagination.next_cursor` (`null` cuando no hay más; `has_more` lo indica). También acepta `offset` como alternativa. La respuesta incluye un encabezado `Link` con `rel="next"`.

## Límite de solicitudes

120 solicitudes por minuto por dirección IP. Las respuestas incluyen `RateLimit-Limit` y `RateLimit-Policy`. Al excederlo se responde `429` con `Retry-After`.

## Errores

Los errores llegan como `application/problem+json` (RFC 9457):

```json
{ "type": "https://kroelgraphics.com/developers#errores", "title": "Invalid Parameter", "status": 400, "detail": "limit debe ser un entero entre 1 y 50.", "code": "invalid_parameter" }
```

Códigos: `invalid_parameter` (400), `not_found` (404), `method_not_allowed` (405), `idempotency_conflict` (409), `validation_failed` (422, con la lista `errors` por campo), `too_many_requests` (429).

## Preguntas en lenguaje natural

`POST /ask` con `{"query":{"text":"..."}}`. Con `{"prefer":{"streaming":true}}` responde como `text/event-stream` con los eventos `start`, `result` y `complete`. Responde con la información publicada en el sitio; no genera texto nuevo.

## Servidores MCP

| Servidor | URL | Herramientas |
|---|---|---|
| Estudio | `https://kroelgraphics.com/mcp` | `get_services`, `get_contact`, `prepare_quote`, `send_quote_request` |
| Documentación | `https://kroelgraphics.com/docs/mcp` | `list_pages`, `read_page`, `search_docs` |

Transporte Streamable HTTP, sin estado y sin autenticación. Publicados en el [directorio oficial de MCP](https://registry.modelcontextprotocol.io/v0/servers?search=kroelgraphics) como `com.kroelgraphics/estudio` y `com.kroelgraphics/docs`. Tarjetas: [/mcp/server-card](https://kroelgraphics.com/mcp/server-card) y [/docs/mcp/server-card](https://kroelgraphics.com/docs/mcp/server-card). Catálogo: [/.well-known/ai-catalog.json](https://kroelgraphics.com/.well-known/ai-catalog.json).

Para agregarlo a un cliente MCP:

```json
{ "mcpServers": { "kroel-graphics": { "type": "http", "url": "https://kroelgraphics.com/mcp" } } }
```

## Agente A2A

Tarjeta en [/.well-known/agent-card.json](https://kroelgraphics.com/.well-known/agent-card.json). El punto `https://kroelgraphics.com/a2a` contesta `message/send` con un mensaje de texto directo.

## Límites de uso

Enviar una solicitud de cotización solo le avisa a Luis; la cotización exacta la da él y nada aquí cierra tratos. Envía solo datos de personas que lo autorizaron. La persona también puede escribir por [WhatsApp](https://wa.me/5216641554842) o platicar con el [asistente del sitio](https://kroelgraphics.com/#cotiza). Hay [precios de arranque](https://kroelgraphics.com/pricing); el precio final se cotiza a la medida.
