Tek çağrıda bir form ve bir istek oluşturun

Ne zaman kullanılır

Bir istek normalde birinin düzenleyicide oluşturup yayınladığı bir formu gösterir. Sorular duruma bağlı olduğunda çağıran onları isteğin içinde gönderir: requests.create, formId yerine form alır. Formstep bloklardan sıradan bir form oluşturur, onu yayınlar ve isteği tek adımda oluşturur; böylece ya ikisi birden oluşur ya da hiçbiri. Buna satır içi form (inline form) diyoruz.

Aynı biçimde birçok kişiye gönderdiğiniz ve düzenleyicide elle tasarlamak istediğiniz bir form için formId kullanmaya devam edin. Neyin sorulacağına bir otomasyon karar verdiğinde form kullanın.

Çağrı

curl -X POST https://api.formstep.io/api/v1 \
  -H "Authorization: Bearer $FORMSTEP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method":"requests.create","params":{
        "form":{
          "name":"Documents and fee for your mortgage application",
          "logo":{"type":"image","url":"https://acme.example/logo.png"},
          "cover":{"type":"color","color":"#0f4c81"},
          "emoji":"🏦",
          "blocks":[
            {"type":"paragraph","content":"Upload the two documents and pay the processing fee."},
            {"type":"file","key":"payslips","title":"Your last two payslips","maxFiles":2},
            {"type":"payment","key":"fee","title":"Processing fee","amount":40,"currency":"EUR"},
            {"type":"scheduleAppointment","key":"call","title":"Pick a time for our call","eventType":"15 min call"}]},
        "recipient":{"email":"ada@example.com","name":"Ada"},
        "delivery":"email",
        "idempotencyKey":"call-8841"}}'

İsteğin geri kalanı anlamını korur: recipient, prefill, context, readonly, delivery, hatırlatmalar, son kullanma tarihi, callbackUrl, test ve idempotencyKey, yeni forma göre tıpkı elle oluşturulmuş bir forma göre olduğu gibi denetlenir. Yanıt ayrıca formu ve formun yanıtlarının hangi anahtarlarla döneceğini içerir:

{
  "id": "kd7...",
  "status": "pending",
  "url": "https://form.formstep.io/r/rq_...",
  "form": {
    "id": "j58...",
    "name": "Documents and fee for your mortgage application",
    "reused": false,
    "fields": [
      { "key": "payslips", "type": "file" },
      { "key": "fee", "type": "payment" },
      { "key": "call", "type": "schedule-appointment" }
    ]
  }
}

Aynı çağrıda bir seçim sorusunu önceden doldurmak için, her formda olduğu gibi seçenek anahtarlarını gönderin. Bir seçeneğin anahtarı etiketinden türetilir; Self-employed, self_employed olur. Anahtar yerine etiket gönderilirse çağrı INVALID_PREFILL_VALUE ile başarısız olur ve hata geçerli anahtarları listeler.

Form nesnesi

Bloklar

Bir blok, MCP sunucusundaki eşleşen editor_insert* aracının parametrelerini formId ve after olmadan alır; bunlara ek olarak isteğe bağlı bir key alır. Anahtar verilmezse başlıktan türetilir; böylece “Full name”, full_name olur. Bloğun tanımadığı bir parametre atlanmaz, reddedilir.

Başlık (header) ve paragraf (paragraph) metni, liste öğeleri ve tablo hücreleri bold, italic, struck, <u>underlined</u>, code, $$equation$$, text, düzenleyici araç çubuğunun renk, yazı tipi ve boyutlarıyla <span color=“red” background=“yellow” font=“font-georgia” size=“1.25”>…</span> ve o anahtara sahip alanın değerini gösteren {{key}} biçimlerini okur. Biçimler iç içe geçebilir; eşi olmayan bir işaret düz metin olarak kalır. Bir satırın sütunu pageDivider, logic, hiddenField, calculatedField, repeatingGroup, row ve scheduleAppointment dışında her bloğu alabilir. Bir decision bloğu title değerini ve onay, ret ve değişiklik için labels değerlerini formun dilinde alır.

Bloklar birbirine öğe kimliğiyle değil, her zaman anahtarla başvurur: bir logic bloğu rule değerini editor_insertLogic gibi alır; kimlik beklenen yerlerde alan anahtarlarını, koşul değeri olarak seçenek etiketlerini ve setNextPage için sayfa adlarını kullanır.

Ödemeler

Bir payment bloğu amount ve currency alır ya da amountFromField alır: bir gizli alanın veya bir sayı sorusunun anahtarı. Gizli alanla her istek kendi tutarını context içinde gönderir; böylece tek bir form her müşteriden kendi tutarını tahsil eder:

{
  "form": {
    "name": "Pay your invoice",
    "blocks": [
      { "type": "hiddenField", "key": "invoice_total" },
      { "type": "payment", "key": "invoice", "title": "Invoice", "currency": "EUR", "amountFromField": "invoice_total" }
    ]
  },
  "recipient": { "email": "ada@example.com" },
  "context": { "invoice_total": 1200 }
}

Tutarı belirleyen bir sayı sorusu zorunlu olmalı ve 0’dan büyük bir min değerine sahip olmalıdır; böylece kimse checkout adımına boş, sıfır ya da negatif bir tutarla ulaşmaz.

Form, çalışma alanının varsayılan Stripe hesabı ya da connection ile belirtilen hesap üzerinden ödeme alır. Stripe’ı çalışma alanı için bir kez bir kişi bağlar; bir otomasyon bağlayamaz. Kullanılabilir bir hesap yoksa çağrı başarısız olur ve hesabı nerede bağlayacağınızı söyler.

Randevular

Bir scheduleAppointment bloğu eventType alır: çalışma alanının Cal.com bağlantısındaki bir etkinlik türünün başlığı veya kimliği. Çalışma alanında birden fazla bağlantı varsa connection da alır. Formstep etkinlik türünü istek oluşturulurken arar. prefill: { name, email }, yanıtları randevu bilgilerini dolduran soruları belirtir.

Markanız

Bir otomasyon görünümünüzü kendisi uyduramaz; bu yüzden onu bir kez verirsiniz ve otomasyon her istekle gönderir: blokların yanında logo, cover ve emoji, renkler ve yazı tipleri için de theme.

Bir görsel bloğunun src değeri dahil her görsel, herkese açık bir JPEG, PNG veya WebP olmalıdır. Formstep her birini form oluşturulurken bir kez indirir ve kendi kopyasını saklar; böylece form ve gönderimlerinin PDF’leri kaynaktan daha uzun yaşar. İndirilemeyen bir URL, alanı belirten INLINE_FORM_IMAGE_UNREACHABLE ile çağrıyı başarısız kılar. Marka olmadan form, panodan oluşturulmuş yeni bir form gibi görünür.

Çeviriler

translations, formu aynı anda başka dillerde de yayınlar ve alıcı, çevrilmiş bir formun sahip olduğu dil seçiciyi alır: { "de": { "Your name": "Ihr Name", "Order for **{{customer}}**": "Bestellung für **{{customer}}**" } }. Formun her metni, tam olarak blokların yazdığı hâliyle anahtarlanmış olarak bulunmalıdır: soru başlıkları, seçenekler, yer tutucular, başlıklar, paragraflar, liste öğeleri, tablo hücreleri, grup adları ve düğme etiketleri. Biçimlendirme ve {{key}} kaynaktaki gibi kalır. Eksik bir metin, eklenecek metinleri listeleyen INLINE_FORM_TRANSLATION_MISSING ile çağrıyı başarısız kılar. E-posta metinleri çevrilmez.

Bir tanım, bir form

Aynı form nesnesiyle yapılan sonraki bir çağrı aynı formu yeniden kullanır ve yanıt “reused”: true içerir. Tek bir tanımla yapılan yüz istek tek bir form oluşturur ve dışa aktarılacak tek bir yanıt kümesi olur. Bir bloğu, adı, markayı veya bir çeviriyi değiştirmek yeni bir form oluşturur; daha önce gönderilmiş istekler oluşturuldukları formu korur. Kapatılan veya yayından kaldırılan bir form yeniden kullanılmaz: aynı tanımla yapılan sonraki çağrı yeni bir form oluşturur.

Açık bir satır içi form aynı blok türlerini aynı sırayla içerdiği hâlde bir çağrı yeni bir form oluşturursa, yanıt o formu form.similarForm içinde belirtir. Bunun nedeni genellikle değişen bir ad veya başlıktır. Bir satır içi formun tüm yanıtlarını okumak için her isteği tek tek okumak yerine gönderimlerini listeleyin.

Panoda

Satır içi bir form isteğine aittir; bu yüzden Formlar sayfasında değil, isteğin sayfasında yer alır. Sayfa yanıtları alan anahtarına göre listeler ve Önizle, formu alıcının gördüğü gibi, yanıtlarıyla doldurulmuş olarak açar. Satır içi bir formun düzenleyicisine veya gönderimlerine giden bir bağlantı, bunun yerine o forma göre filtrelenmiş İstekler sayfasını açar. Ajanlar satır içi formları form_list içinde görmeye devam eder ve API bunları değiştirmeyi reddeder.

Satır içi bir formun paylaşım bağlantısı yoktur ve eklenemez: ona yalnızca istekleri üzerinden ulaşılır ve geri çağırma her yanıtı taşır. Entegrasyonu da yoktur.

Kendi sayfası olmadığı için satır içi bir form asla elle silinmez. Son isteğiyle birlikte gider: bir isteği sildiğinizde ya da formun saklama süresi onu aldığında ve başka hiçbir istek formu hâlâ kullanmıyorsa, form da silinir.

Çağrı reddedildiğinde

Her ret, otomasyonunuzun details.reason değerine göre dallanabileceği bir VALIDATION_ERROR hatasıdır. Hiçbir şey oluşturulmaz.

Bir ajandan

MCP sunucusunda request_create aynı form nesnesini alır. Ödeme veya randevu içeren bir form oluşturmadan önce ajan workspaceConnection_list aracını okur: bu araç bağlı Stripe ve Cal.com hesaplarını ve biri eksikse bir kişinin bir kez açması gereken sayfanın adresini gösterir. scheduler_listEventTypes bir randevunun belirtebileceği etkinlik türlerini listeler, paymentConnection_setDefault ise varsayılan Stripe hesabını değiştirir. REST API’de bu üçü connections.list, scheduler.listEventTypes ve paymentConnections.setDefault metodlarıdır.