Bir istek oluşturmak

Paylaş panelinden başlayın

Yayınlanmış formunuzu açın, Paylaş’a tıklayın ve İstekler sekmesini seçin. Oradaki kart, ilk çağrıyı yapmak için ihtiyacınız olan her şeyi verir:

• Kopyalama düğmesiyle birlikte form kimliği.

• Formunuzun gerçek alan anahtarlarından oluşturulmuş bir curl parçacığı ve bir MCP istemi — örnek zaten bu formun gerçekten sahip olduğu alanlara adreslenmiştir.

• Bir isteği elle oluşturan Manuel sekmesi, ve orada doldurduklarınızı test modunda bir isteğe çevirip bağlantısını size veren Kendin dene.

• Bu forma göre filtrelenmiş İstekler sayfasına bir bağlantı.

Adım 1 — Alanları keşfedin

fields.list, formun geçerli yayınlanmış sürümündeki her alanı, adreslemek için kullanılacak anahtarla, aldığı değer biçimiyle ve ait olduğu grupla birlikte döndürür.

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":"j57..."}}'

{
  "ok": true,
  "data": {
    "published": true,
    "items": [
      { "key": "company_name", "type": "text", "title": "Company", "required": true, "prefillable": true },
      {
        "key": "company_size", "type": "select", "title": "Company size", "required": false, "prefillable": true,
        "options": [
          { "key": "1_50", "label": "1–50" },
          { "key": "51_200", "label": "51–200" }
        ]
      },
      { "key": "case_id", "type": "hidden", "title": "Case", "required": false, "prefillable": false, "context": true },
      { "key": "total", "type": "number", "title": "Total", "required": false, "prefillable": false, "calculated": true },
      { "key": "signature", "type": "signature", "title": "Sign here", "required": true, "prefillable": false }
    ],
    "hasMore": false
  }
}

• context: true gizli bir alanı işaretler. Değeri her zaman context içine gider, asla prefill içine değil; bir gizli alanın anahtarı prefill içinde bulunursa UNKNOWN_FIELD_KEY hatasıyla reddedilir.

• calculated: true, hesaplanan bir alanı işaretler. Formun kendisi değerini hesaplar, dolayısıyla kimse bir değer gönderemez; değeri answers içinde kendi anahtarı altında geri okursunuz.

• prefillable: false, kimsenin değer sağlayamayacağı bir alanı işaretler: dosya yükleme, imza, ödeme, randevu ayırma ve Belgeler blokları. Alıcı soruları kendisi doldurur. Gizli alanlar ve hesaplanan alanlar da prefillable: false olarak görünür: gizli alanlar context alır, hesaplanan alanlar ise hiçbir şey almaz.

• options, bir seçim sorusunun seçeneklerini listeler. Etiketi değil, seçeneğin anahtarını gönderin; etiket yalnızca bildiğiniz seçimi kendi anahtarına eşlemeniz için orada. Bir matris de rows ve columns’unu aynı şekilde listeler.

• Tekrarlayan gruplar, type: “group”, repeating: true ve bir members listesiyle tek bir girdi olarak döner.

Adım 2 — İsteği oluşturun

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":"j57...",
        "recipient":{"email":"ada@acme.com","name":"Ada"},
        "context":{"case_id":"CASE-9"},
        "prefill":{"company_name":"Acme","company_size":"51_200"},
        "readonly":["company_name"],
        "delivery":"email",
        "externalId":"run-42",
        "callbackUrl":"https://automation.example/webhook/resume-abc",
        "idempotencyKey":"run-42"}}'

{
  "ok": true,
  "data": {
    "id": "kd7...",
    "status": "pending",
    "url": "https://form.formbase.so/r/rq_...",
    "deliveryStatus": "queued",
    "expiresAt": 1794787200000,
    "createdAt": 1789379200000,
    "externalId": "run-42",
    "deduplicated": false
  }
}

formbase daveti e-postayla gönderdiğinde deliveryStatus “queued”, bağlantıyı kendiniz teslim ettiğinizde ise “not_requested” olur.

Önceden doldurma, kilitli alanlar ve bağlam

Bir isteğe üç farklı şey eklenebilir ve bunları karıştırmak en yaygın ilk hatadır.

Prefill

Görünür sorular için başlangıç yanıtları — böylece alıcı sıfırdan yazmak yerine gözden geçirip düzeltir. Onlar hakkında zaten bildiğiniz her şey burada yer alır — CRM’deki şirket adı, faturadaki tutar, geçen yılın yanıtları.

Kilitli alanlar

Önceden doldurulmuş bir anahtarı readonly içine ekleyin, alıcı değeri görür ama değiştiremez. Bunu, alıcının sağladığı değil onayladığı gerçekler için kullanın — sözleşme numarası, üzerinde anlaşılan fiyat. Kilitleme istek bazlıdır: formun kendisi dokunulmamış kalır ve aynı alan bir sonraki istekte özgürce düzenlenebilir.

Kilitli her anahtar aynı zamanda önceden doldurulmuş olmalıdır ve kilitli bir zorunlu alan boş olmayan bir değerle doldurulmuş olmalıdır — aksi takdirde alıcı asla gönderemeyeceği bir formla karşı karşıya kalır ve formbase bu tuzağı oluşturmak yerine çağrıyı reddeder.

Context

Formun gizli alanları için güvenilir değerler — bir dosya numarası, bir workflow çalışma kimliği, bir tutar. Context, değişkenleri, koşullu mantığı, hesaplanan alanları ve e-posta metnini besler, geri çağırmada değişmeden döner ve alıcı bunu değiştiremez. Herkesin sorgu dizesini düzenleyebildiği genel bir bağlantıda URL üzerinden bir gizli alan besleme yönteminden farkı budur; istek bağlantıları URL sorgu parametrelerini tamamen yok sayar. Context değerleri bir metin dizesi, sayı veya boolean olmalıdır.

Context serbest biçimli değildir: her anahtar formun yayınlanmış sürümünde bir gizli alan olmalıdır, bunun dışındaki her anahtar UNKNOWN_FIELD_KEY ile reddedilir. Gizli alanı olmayan kayıt bilgileri, örneğin bir yürütme kimliği, metadata’ya aittir.

Gizli alanlar formda gösterilmez, ama bir context değeri alıcı için gizli değildir. Alıcı bunu, formun veya davetin gösterdiği her yerde görür: form içeriğinde veya e-posta metninde anıldığında, ya da görünür bir sorunun o gizli alanı kendi varsayılan değeri olarak kullanmasında. Bu son durumda, alıcı context değerini o soruda önceden doldurulmuş görür ve yanıtı düzenleyebilir. Context değerinin kendisi değişmeden kalır. O sorunun kendi anahtarı için bir prefill, varsayılana göre önceliklidir.

Metadata

Kendi kayıt tutma bilgileriniz — bir yürütme kimliği, bir CRM kayıt kimliği. Bu hiçbir zaman forma ulaşmaz, dolayısıyla metne aktarılamaz veya mantık tarafından okunamaz; sadece yolculuğa eşlik eder ve her geri çağırmada ve durum okumasında geri döner.

Değer biçimleri

Değerleri fields.list’ten gelen type’ın istediği biçimde gönderin. Yanlış bir biçim, anahtarı, beklenen türü ve — seçim soruları için — kabul edilecek değerleri belirten bir doğrulama hatası olarak döner.

Belgeler

Bir Belgeler bloğu, yanıtlayıcıya dosya verir. Hazırlanmış dosyaları herkes için aynıdır ve her zaman kalır; bir istek, kendi tek alıcısı için dosyaları bunların altına ekler — müşterinin kendi kira sözleşmesi, kontrol edilecek bir kimlik fotokopisi. Baytlar hiçbir zaman API çağrısının kendisinden geçmez: önce yükleyin, sonra referans verin.

1. 1

   Yüklemeyi ayırtın

   formId, name (1–200 karakter), contentType (PDF veya görsel), bayt cinsinden tam boyut ve isteğe bağlı olarak dosyanın sha256 değeri (64 onaltılık karakter) ile documents.create çağrısı yapın. Bir saat geçerli olan bir id ve bir uploadUrl geri alırsınız.

2. 2

   Baytları yükleyin

   Aynı Content-Type ile dosyayı uploadUrl'e PUT edin. Henüz hiçbir şey doğrulanmaz.

3. 3

   İstekte ona referans verin

   requests.create üzerinde documents: [{ documentId, name? }] geçirin. formbase, istek oluşturulmadan önce yüklenen nesneyi (boyut, dosya imzası, gönderdiyseniz sha256) kontrol eder ve alıcı dosyayı blokta görür.

"documents": [
  { "documentId": "kn7...", "name": "Your lease contract" },
  { "documentId": "kn8..." }
]

name, yüklemeyle kaydedilen görünen adı geçersiz kılar. Formda birden fazla Belgeler bloğu varsa hedefi field ile, yani bloğun alan anahtarıyla belirtin (fields.list bunu, her yanıtlayanın zaten aldığı hazır belgelerle birlikte listeler). Dosyalar bu hazır belgelerin altında yer alır: bir istek dosya ekler, hiçbir zaman birini değiştirmez. Bir yükleme, istediğiniz kadar çok istek tarafından referans gösterilebilir — bir kez yüklenen bir fiyat listesi beş yüz isteğe hizmet eder.

Sınırlar: yalnızca PDF ve görseller, belge başına 25 MB, istek başına 100 MB (DOCUMENTS_TOO_LARGE) ve hazırlanmış belgeler dahil blok başına en fazla 20 belge (DOCUMENTS_TOO_MANY). Dosyalar çalışma alanı depolama alanınıza sayılır ve onlara referans veren istekler formun saklama penceresinin dışına çıktığında serbest bırakılır. Gönderim, alıcının bloğun alan anahtarı altında gördüğü listeyi kaydeder, böylece geri çağırma size bu kişiye tam olarak hangi dosyaların verildiğini söyler.

Kalan seçenekler

Test modu

Gerçek bir çalıştırmadan önce tüm yapıyı denemek için test: true geçirin. Bir test isteği, bağlantı açısından önemli olan her şekilde gerçektir: bağlantı açılır ve tamamlanabilir, geri çağırma her zamanki gibi tetiklenir ve requests.get yanıtları döndürür. Asla yapmadığı şey, sonradan temizlemeniz gereken birine veya bir şeye ulaşmaktır:

• delivery ne derse desin, ne davet ne de hatırlatma gönderilir. Hatırlatma gönder bunun üzerinde reddedilir ve aylık kotanızdan hiçbir şey harcamaz.

• Geri çağırma “test”: true taşır, böylece workflow’unuz buna göre dallanabilir veya onu yok sayabilir.

• Gönderim saklanır ama sayılmaz: ne aylık kotanıza karşı (kota tükenmiş olsa bile bir test tamamlanır), ne de formun gönderim sayılarında, gönderimler sekmesinde, dışa aktarımlarda veya entegrasyonlarınızda görünür. Kimse bilgilendirilmez.

• İstek, Test isteklerini göster’in arkasında İstekler sayfasından gizlenir, Analytics’teki istek hunisinden dışlanır ve includeTest: true geçirmediğiniz sürece requests.list’ten dışlanır.

• expiresAt daha uzun bir süre istese bile bağlantı 24 saat içinde kapanır; yanıttaki expiresAt ne zaman olduğunu söyler. Free’de bir workspace günde 10 test isteği oluşturabilir. Sonraki istek RATE_LIMITED ve TEST_REQUEST_LIMIT_REACHED nedeniyle başarısız olur, retryAfterMs ise ne zaman tekrar deneyebileceğinizi söyler. Pro ve Business’ta günlük sınır yoktur.

Paylaş panelindeki Kendin dene, bu modu tek tıkla çalıştırır: Manuel sekmesinin taslağını — önceden doldurma, kilitler, bağlam, geri çağırma, süre dolumu — alır, isteği kendi hesabınıza adresler, hiçbir e-posta göndermez ve size kendinizin açacağı bağlantıyı verir.

Bir isteğin maliyeti

Her planda, her iki kanalın paylaştığı tek bir aylık kota vardır: bir paylaşım bağlantısı gönderimi bir birim harcar, oluşturduğunuz her istek de öyle — alıcı yanıtlasın, yok saysın veya siz iptal edin, fark etmez. Bir isteğin topladığı gönderim zaten ödenmiştir ve hiçbir yerde sayılmaz. Ücretsiz plan ayda 1.000 birim içerir, Pro ve Business 50.000; sayaç her ayın 1’inde, UTC olarak sıfırlanır. Kotaya ulaşıldığında requests.create, UPGRADE_REQUIRED hatasıyla ve MONTHLY_ALLOWANCE_REACHED nedeniyle başarısız olur; zaten oluşturduğunuz istekler yanıtlanabilir kalmaya devam eder.

Ücretsiz planda, “delivery”: “email” ile oluşturulan bir istek ayrıca hesabın 10 ücretsiz davetinden birini harcar. Bunlar asla sıfırlanmaz; bittiklerinde e-posta teslimatı UPGRADE_REQUIRED hatasıyla ve FREE_INVITATIONS_USED nedeniyle başarısız olur.

Idempotency (aynı sonuç garantisi)

Aynı gövdeyle aynı idempotencyKey’i geçirin, deduplicated: true ile birlikte orijinal isteği ve orijinal bağlantıyı geri alırsınız — ikinci bir istek yok, ikinci bir e-posta yok. Anahtarı farklı bir gövdeyle yeniden kullanırsanız formbase, hangisini kastettiğinizi tahmin etmek yerine IDEMPOTENCY_CONFLICT ile reddeder. Anahtarlar çalışma alanına kapsamlıdır ve 30 gün boyunca geçerlidir; bu sürenin ardından aynı anahtar yeni bir istek başlatır.

Bir workflow aracında, yürütme kimliği doğal anahtardır: bir ağ kesintisinden sonra yeniden denenen bir çalışma, zaten oluşturduğu isteği devralır.

Hız sınırı

requests.create ve documents.create, API tokeni başına (tokensiz yapılan bir çağrı için kullanıcı başına) sayılan, dakikada 60 çağrılık bir bütçeyi paylaşır. Boşalttığınız bir birikim kendi hızını ayarlamalıdır; bütçeyi aşan bir patlama reddedilir ve yeniden denenebilir.

Özel alan adları

Form zaten özel alan adlarınızdan birinde yayınlanmışsa, istek bağlantıları orada otomatik olarak oluşturulur — https://forms.yourcompany.com/r/rq_…. Form birden fazla alan adında yayınlanmışsa domainId’yi açıkça belirtin. Alan adı, formla aynı çalışma alanına ait olmalıdır.

Alıcı ne görür

Tam olarak yazdığınız form — aynı tema, aynı logo, aynı dil — değerleri yerinde, kilitli alanlar salt okunur ve çözülecek bir captcha yok. Gönderdiklerinde, teşekkür sayfanızı görürler. Daha sonra bağlantıya geri dönerlerse, boş bir form yerine sonuç sayfasını görürler.

Sayfada otomasyonunuzdan bir mesaj yoktur. Alıcının bilmesi gereken her şey formun kendisinde yer almalıdır; burada bir bağlam değerini veya önceden doldurulmuş bir alanı anarak kişiselleştirebilirsiniz.

Bir AI ajanı, fields_list ve request_create ile aynı iki adımı, aynı seçeneklerle — documents ve domainId dahil — çalıştırır. Bkz. MCP sunucusundaki İstekler.