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é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
- Catálogo: /.well-known/api-catalog (RFC 9727)
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.
- 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 responde409. - 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):
{ "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 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.