Primeros pasos: claves de API y primera llamada.

Qué puede hacer la API

La API de KENJTEC da a tus propios programas acceso a tu cuenta: leer formularios y sus respuestas, tiendas y pedidos, y también escribir: crear y publicar sitios web, gestionar registros DNS, emitir facturas y subir medios. Además, están los webhooks: avisamos a tu servidor en cuanto ocurre algo. Y tu propia IA puede trabajar a través de MCP con la misma clave.

La dirección es https://api.kenjtec.com/v1. La API está incluida en todos los planes de pago, sin coste adicional.

Crear una clave

Cada programa se identifica con su propia clave de API. Una clave lleva permisos: forms:read lee formularios y respuestas, orders:read lee tiendas y pedidos, y webhooks:manage crea y elimina webhooks. Las rutas de escritura tienen permisos propios para cada área. Da a cada programa su propia clave: así podrás revocar una sin afectar a las demás.

1. 1Abre el panel y, en “Ajustes”, elige el área Desarrollador.
2. 2En “Claves de API”, ponle un nombre a la clave, por ejemplo “Sincronización de inventario”.
3. 3En “¿Qué puede hacer esta clave?”, elige solo los permisos que necesita el programa.
4. 4Haz clic en “Crear clave” y copia la clave de inmediato.

La clave se muestra exactamente una vez. Solo guardamos una suma de comprobación: si la pierdes, revócala con “Revocar” y crea una nueva.

La primera llamada

Envía la clave en cada solicitud en la cabecera Authorization. /v1/me te indica a qué cuenta pertenece la clave y qué permisos tiene.

curl https://api.kenjtec.com/v1/me \
  -H "Authorization: Bearer kt_api_…"

{
  "id": 1042,
  "object": "account",
  "email": "ana@deine-firma.com",
  "handle": "cafe-lumen",
  "address": "https://cafe-lumen.kenjtec.ai",
  "key": { "name": "Lager-Abgleich", "scopes": ["orders:read"] }
}

Las rutas

Estas son las rutas disponibles. La descripción completa y legible por máquina está en https://api.kenjtec.com/openapi.json; a partir de ella se pueden generar bibliotecas de cliente para cualquier lenguaje de programación.

GET    /v1/me
GET    /v1/forms
GET    /v1/forms/{id}
GET    /v1/forms/{id}/responses
GET    /v1/forms/{id}/responses/{id}
GET    /v1/shops
GET    /v1/orders          ?shop_id=  &status=  &payment_status=
GET    /v1/orders/{id}
GET    /v1/webhooks
POST   /v1/webhooks
DELETE /v1/webhooks/{id}

GET    /v1/sites
GET    /v1/sites/{id}
POST   /v1/sites
POST   /v1/sites/{id}/edit
POST   /v1/sites/{id}/publish
POST   /v1/sites/{id}/unpublish
GET    /v1/domains
GET    /v1/domains/{id}/dns_records
POST   /v1/domains/{id}/dns_records
PATCH  /v1/domains/{id}/dns_records/{id}
DELETE /v1/domains/{id}/dns_records/{id}
GET    /v1/customers
POST   /v1/customers
GET    /v1/invoices        ?kind=invoice|quote
GET    /v1/invoices/{id}
POST   /v1/invoices
POST   /v1/invoices/{id}/issue
POST   /v1/invoices/{id}/cancel
GET    /v1/media
POST   /v1/media/uploads
POST   /v1/media/{id}/confirm
GET    /v1/brands
GET    /v1/brands/{id}

Los archivos de las respuestas de formularios aparecen con su nombre, no con una dirección. Puedes descargarlos en FormBuilder.

Listas, importes, horas

Las listas se devuelven con los elementos más recientes primero, con un máximo de 100 elementos por llamada (limit, valor predeterminado 25). Para la página siguiente, envía el identificador del último elemento como starting_after; has_more indica si quedan más.

Los importes son números enteros en la unidad más pequeña de la moneda: céntimos para el euro y yenes enteros para el yen. Las horas se expresan en UTC según ISO 8601.

curl "https://api.kenjtec.com/v1/orders?payment_status=paid&limit=50" \
  -H "Authorization: Bearer kt_api_…"

Errores y límites

Todos los errores tienen la misma forma: un objeto error con type y message. 401 significa que la clave falta, es incorrecta o ha sido revocada. 403 significa que a la clave le falta un permiso, o que la cuenta ya no tiene un plan de pago (type plan_required). 404 significa que eso no existe o que no pertenece a tu cuenta.

Cada clave admite 120 solicitudes por minuto. Por encima de eso, la API responde con 429 e indica en Retry-After los segundos que faltan para el siguiente intento.

{
  "error": {
    "type": "permission_error",
    "message": "This API key lacks the scope 'orders:read'."
  }
}

La API solo acepta claves, nunca tu inicio de sesión en el navegador. Una clave debe estar en tu servidor, nunca en un sitio web ni en una app que otros descarguen.