REST API ile istek gönderin

Yayınlanmış bir forma ihtiyacınız var. Bu kılavuz, Bir yapay zeka ajanıyla form oluşturun kılavuzunda oluşturulan formu kullanır: şirket adı, iletişim e-postası, KDV numarası, ödeme koşulları hakkında bir evet ya da hayır sorusu ve bir dosya yükleme. Burada kullanılan her metot ve seçenek API metodları sayfasında anlatılır.

1. Bir API token’ı oluşturun

formbase’de, çalışma alanı kenar çubuğunda OAuth ve API Anahtarları’nı açın ve bir token oluşturun. Değer yalnızca bir kez gösterilir. Kodunuzda değil bir ortam değişkeninde saklayın:

export FORMBASE_TOKEN='fb_...'

Bir token, yalnızca oluşturulduğu tek çalışma alanına ulaşır. Aşağıdaki her çağrı, token’ı Authorization başlığında taşıyan aynı URL’ye yapılan bir POST’tur; gövde metodu ve parametrelerini adlandırır.

2. Form kimliğini bulun

Formu düzenleyicide açın. Form kimliği, adresin /forms/’tan sonraki bölümüdür:

https://app.formbase.so/<workspace ID>/forms/jx75hdx8vb5hy1x85gm17nqgkn8f674g/edit

Aşağıdaki komutlar bu kılavuzun form kimliğini kullanır. Kendi kimliğinizi onun yerine koyun.

3. Alan anahtarlarını listeleyin

Bir istek soruları alan anahtarına göre doldurur ve yanıtlar da aynı şekilde geri gelir. Anahtarları başlıklardan tahmin etmek yerine formdan isteyin:

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method": "fields.list", "params": {"formId": "jx75hdx8vb5hy1x85gm17nqgkn8f674g"}}'

Yanıt, yayınlanmış formun her sorusunu listeler. Kısaltılmış hâli:

{
  "ok": true,
  "data": {
    "published": true,
    "items": [
      { "key": "company_name", "type": "text", "title": "Company name", "required": true, "prefillable": true },
      { "key": "contact_email", "type": "email", "title": "Contact email", "required": true, "prefillable": true },
      { "key": "vat_number", "type": "text", "title": "VAT number", "required": false, "prefillable": true },
      {
        "key": "do_you_accept_our_30_day_payment_terms", "type": "radio", "title": "Do you accept our 30-day payment terms?", "required": true, "prefillable": true,
        "options": [{ "key": "yes", "label": "Yes" }, { "key": "no", "label": "No" }]
      },
      { "key": "certificate_of_incorporation", "type": "file", "title": "Certificate of incorporation", "required": true, "prefillable": false }
    ],
    "hasMore": false
  }
}

Bir seçim sorusunu önceden doldurmak için seçeneğin key’ini gönderin, burada “yes”, etiketini değil. Dosya yüklemesi gibi prefillable: false olan bir soruyu yalnızca alıcı yanıtlayabilir. Diğer bayraklar fields.list altında açıklanmıştır.

4. Bir test isteği oluşturun

İsteği, şirket adı doldurulmuş ve kilitli olarak Ada Lovelace’a gönderin. test: true, bunu bir test isteğine dönüştürür: hiç kimseye e-posta göndermez ve hiçbir yerde sayılmaz, bu yüzden bu adımı her seferinde yeni bir idempotencyKey ile istediğiniz kadar tekrarlayabilirsiniz.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "requests.create",
    "params": {
      "formId": "jx75hdx8vb5hy1x85gm17nqgkn8f674g",
      "recipient": { "email": "ada@acme.example", "name": "Ada Lovelace" },
      "prefill": { "company_name": "Analytical Engines Ltd" },
      "readonly": ["company_name"],
      "externalId": "supplier-2043",
      "idempotencyKey": "supplier-2043",
      "test": true
    }
  }'

• prefill, alıcının hâlâ değiştirebileceği yanıtları doldurur. readonly içindeki bir anahtar ayrıca kilitlidir.

• externalId, bu iş parçası için kendi kimliğinizdir — bir tedarikçi numarası gibi. Her okumada ve geri çağırmada geri gelir.

• idempotencyKey, bir yeniden denemeyi güvenli kılar. Kodunuz aynı çağrıyı iki kez gönderirse formbase, ikinci bir istek oluşturmak yerine deduplicated: true ile ilk isteği döndürür.

Yanıt, istek kimliğini ve alıcı için bağlantıyı taşır:

{
  "ok": true,
  "data": {
    "id": "m17ayhcnj9xvzkff3atek49bdd8f6872",
    "status": "pending",
    "url": "https://form.formbase.so/r/rq_...",
    "deliveryStatus": "not_requested",
    "externalId": "supplier-2043",
    "deduplicated": false,
    "createdAt": 1790539225370,
    "expiresAt": 1793131225370
  }
}

deliveryStatus: “not_requested”, formbase’in hiçbir e-posta göndermediği anlamına gelir; bağlantıyı siz kendiniz teslim edersiniz. formbase’in daveti ve hatırlatmaları göndermesi için, Pro veya Business plan gerektiren “delivery”: “email” ekleyin. Bkz. Davetler, hatırlatmalar ve süre dolumu. Formda Hatırlatma gönder açıksa, bir alıcı e-postasına sahip gerçek bir istek yine de zamanlanmış hatırlatmaları alır; hiç göndermemek için “reminders”: [] ekleyin.

5. Tamamlayın ve yanıtları okuyun

url’yi bir tarayıcıda açın. Şirket adı doldurulmuş ve kilitlidir; gerisini yanıtlayın ve gönderin. Ardından isteği kimliğiyle geri okuyun:

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method": "requests.get", "params": {"requestId": "m17ayhcnj9xvzkff3atek49bdd8f6872"}}'

status completed olduğunda, yanıt alan anahtarına göre anahtarlanmış iki harita taşır. answers kod içindir: bir seçim yanıtı seçenek anahtarıdır, bir dosya yanıtı indirme URL’leri olan bir dosya listesidir. display insanlar içindir: etiketler ve dosya adları.

"answers": {
  "company_name": "Analytical Engines Ltd",
  "do_you_accept_our_30_day_payment_terms": "yes",
  "certificate_of_incorporation": [{ "name": "certificate-of-incorporation.pdf", "type": "application/pdf", "size": 635, "url": "https://api.formbase.so/api/storage/..." }]
},
"display": {
  "company_name": "Analytical Engines Ltd",
  "do_you_accept_our_30_day_payment_terms": "Yes",
  "certificate_of_incorporation": "certificate-of-incorporation.pdf"
}

Durum değişene kadar tekrar tekrar sormak bir test için işe yarar, ama üretimde işe yaramaz. İsteğe bir callbackUrl verin, formbase bittiğinde sizi çağırır; sıradaki kılavuz bunu kurar.

Sırada