Primeiros passos: chaves de API e primeira chamada.

O que a API faz

A API KENJTEC dá aos teus próprios programas acesso à tua conta: ler formulários e as respetivas respostas, lojas e encomendas — e escrever: criar e publicar sites, gerir registos DNS, emitir faturas, carregar multimédia. Além disso, há webhooks — contactamos o teu servidor assim que algo acontece. E a tua própria IA pode trabalhar através de MCP com a mesma chave.

O endereço é https://api.kenjtec.com/v1. A API está incluída em todos os planos pagos, sem custo adicional.

Criar uma chave

Cada programa autentica-se com a sua própria chave de API. Uma chave tem permissões: forms:read lê formulários e respostas, orders:read lê lojas e encomendas, webhooks:manage cria e elimina webhooks. Para os endpoints de escrita existem permissões próprias por área. Dá a cada programa a sua própria chave — assim podes revogar uma sem afetar as outras.

1. 1Abre o painel e, em “Definições”, escolhe a área Programador.
2. 2Em “Chaves de API”, dá um nome à chave, por exemplo “Sincronização de stock”.
3. 3Em “O que pode esta chave fazer?”, escolhe apenas as permissões de que o programa precisa.
4. 4Clica em “Criar chave” e copia a chave de imediato.

A chave é mostrada exatamente uma vez. Guardamos apenas uma soma de verificação — se a perderes, revoga-a com “Revogar” e cria uma nova.

A primeira chamada

Envia a chave em cada pedido, no cabeçalho Authorization. /v1/me indica-te a que conta pertence a chave e que permissões tem.

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

Os endpoints

Estes são os endpoints disponíveis. A descrição completa, legível por máquina, está em https://api.kenjtec.com/openapi.json — a partir dela, é possível gerar bibliotecas de cliente para qualquer linguagem de programação.

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}

Os ficheiros das respostas de formulários aparecem com o respetivo nome, não com um endereço. Podes descarregá-los no FormBuilder.

Listas, montantes, horas

As listas vêm das mais recentes para as mais antigas, com no máximo 100 entradas por chamada (limit, predefinição 25). Para obter a página seguinte, envia o identificador da última entrada como starting_after; has_more indica se ainda há mais.

Os montantes são números inteiros na unidade mais pequena da moeda — cêntimos no euro, ienes inteiros no iene. As horas estão em UTC, segundo a norma ISO 8601.

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

Erros e limites

Todos os erros têm a mesma forma: um objeto error com type e message. 401 significa que a chave está em falta, é incorreta ou foi revogada. 403 significa que falta uma permissão à chave — ou que a conta já não tem um plano pago (type plan_required). 404 significa que isso não existe ou não pertence à tua conta.

Cada chave pode fazer 120 pedidos por minuto. Acima disso, a API responde com 429 e indica em Retry-After os segundos até à próxima tentativa.

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

A API aceita exclusivamente chaves, nunca a tua sessão iniciada no navegador. Uma chave deve ficar no teu servidor — nunca num site nem numa app que outras pessoas descarreguem.