Primi passi: chiave API e prima chiamata.

Cosa può fare l'API

L'API KENJTEC dà ai tuoi programmi accesso al tuo account: leggere i moduli e le relative risposte, i negozi e gli ordini, e anche scrivere: creare e pubblicare siti web, gestire i record DNS, emettere fatture, caricare file multimediali. In più ci sono i webhook: contattiamo il tuo server non appena succede qualcosa. E la tua IA può lavorare tramite MCP con la stessa chiave.

L'indirizzo è https://api.kenjtec.com/v1. L'API è inclusa in ogni piano a pagamento, senza costi aggiuntivi.

Creare una chiave

Ogni programma accede con una propria chiave API. Una chiave porta con sé dei permessi: forms:read legge moduli e risposte, orders:read legge negozi e ordini, webhooks:manage crea ed elimina webhook. Per gli endpoint di scrittura esistono permessi propri per ogni area. Assegna a ogni programma una chiave propria: così puoi revocarne una senza disturbare le altre.

1. 1Apri il dashboard e in “Impostazioni” scegli l'area Sviluppatore.
2. 2In “Chiavi API” assegna un nome alla chiave, ad esempio “Sincronizzazione magazzino”.
3. 3In “Cosa può fare questa chiave?” scegli solo i permessi di cui il programma ha bisogno.
4. 4Fai clic su “Crea chiave” e copia subito la chiave.

La chiave viene mostrata una sola volta. Salviamo solo un checksum: se la perdi, revocala con “Revoca” e creane una nuova.

La prima chiamata

Invia la chiave in ogni richiesta nell'intestazione Authorization. /v1/me ti dice a quale account appartiene la chiave e quali permessi ha.

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"] }
}

Gli endpoint

Questi sono gli endpoint disponibili. La descrizione completa e leggibile dalle macchine si trova in https://api.kenjtec.com/openapi.json: da essa si possono generare librerie client per qualsiasi linguaggio di programmazione.

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}

I file delle risposte ai moduli compaiono con il loro nome, non con un indirizzo. Puoi scaricarli in FormBuilder.

Elenchi, importi, orari

Gli elenchi arrivano dal più recente, con al massimo 100 voci per chiamata (limit, valore predefinito 25). Per la pagina successiva invia l'identificativo dell'ultima voce come starting_after; has_more ti dice se ci sono altre voci.

Gli importi sono numeri interi nella più piccola unità della valuta: centesimi per l'euro, yen interi per lo yen. Gli orari sono in UTC secondo ISO 8601.

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

Errori e limiti

Ogni errore ha la stessa forma: un oggetto error con type e message. 401 significa che la chiave manca, è errata o è stata revocata. 403 significa che alla chiave manca un permesso, oppure che l'account non ha più un piano a pagamento (type plan_required). 404 significa che la risorsa non esiste o non appartiene al tuo account.

Ogni chiave può effettuare 120 richieste al minuto. Oltre questo limite l'API risponde con 429 e indica in Retry-After i secondi che mancano al tentativo successivo.

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

L'API accetta esclusivamente chiavi, mai il tuo accesso nel browser. Una chiave va tenuta sul tuo server, mai in un sito web o in un'app che altri scaricano.