Kroel Graphics
API · MCP · A2A

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

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: herramienta de terminal (CLI), habilidad para agentes, manifiesto de plugin y reglas para agentes (AGENTS.md). Licencia MIT.

Paquete en npm: kroel-graphics. Instala el comando kroel:

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étodoRutaQué devuelve
GET/api/v1/serviciosLista paginada de servicios (limit, offset), cómo se cotiza y límites
GET/api/v1/preciosPrecios de arranque en MXN por servicio
GET/api/v1/contactoWhatsApp, formulario de cotización y redes
GET/api/v1/healthEstado del servicio
POST/api/v1/cotizacionesEnvía una solicitud de cotización; responde 202 con un id
GET/api/v1/cotizaciones/{id}Estado de esa solicitud
POST/askRespuesta a una pregunta en lenguaje natural (NLWeb 0.55)

Autenticación

Ninguna: no hay cuentas ni tokens. Detalle en auth.md.

Enviar una solicitud de cotización

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.

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):

{ "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

ServidorURLHerramientas
Estudiohttps://kroelgraphics.com/mcpget_services, get_contact, prepare_quote, send_quote_request
Documentaciónhttps://kroelgraphics.com/docs/mcplist_pages, read_page, search_docs

Transporte Streamable HTTP, sin estado y sin autenticación. Publicados en el directorio oficial de MCP como com.kroelgraphics/estudio y com.kroelgraphics/docs. Tarjetas: /mcp/server-card y /docs/mcp/server-card. Catálogo: /.well-known/ai-catalog.json.

Para agregarlo a un cliente MCP:

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

Agente A2A

Tarjeta en /.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 o platicar con el asistente del sitio. Hay precios de arranque; el precio final se cotiza a la medida.