Formlar API

Herkesin doldurabileceği formlar; yanıtlar potansiyel müşteri veya Base kaydı olarak gelir.

Modül kodu forms · 7 işlem · 3 veri modeli · 8 olay. Bir anahtar ya da token, arkasındaki kişinin bu modülde yapabildiğinden fazlasını asla yapamaz; satır düzeyindeki güvenlik uygulamadakiyle birebir aynıdır. Yetki kapsamları: forms (hepsi), forms:read (yalnız okuma) ya da forms:<yetenek>.

Kaynaklar

Listeler limit (en çok 200), cursor, order (ör. -created_at), fields ve q alır; diğer her sorgu parametresi bir sütun süzgecidir: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

İşlemler

forms.close_form

Formu kapat — Adres çalışmaya devam eder ve ziyaretçilere formun kapalı olduğunu söyler.

Gereken izin forms:manage · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır) · Era çalıştırırken bir kişiye onaylatır

• Asıl adres: POST /api/v1/actions/forms.close_form

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: forms.form_closed

Neye yazar: public_form (update) — Stops it answering

curl -X POST https://app.getera.io/api/v1/public_forms/PUBLIC_FORM_ID/actions/close_form \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "forms.form_closed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.publicForms.closeForm("PUBLIC_FORM_ID")

era public_forms close_form PUBLIC_FORM_ID

{
  "name": "era__forms__close_form",
  "arguments": {
    "id": "PUBLIC_FORM_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde forms:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 form_not_open · 429 çok sık istek

forms.discard_submission

Başarısız gönderimi at — Kayıtta tutar, başarısızlar listesinden çıkarır. Ondan hiçbir şey oluşturulmaz.

Gereken izin forms:manage · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır) · Era çalıştırırken bir kişiye onaylatır

• Asıl adres: POST /api/v1/actions/forms.discard_submission

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: forms.submission_discarded

Neye yazar: form_submission (update) — Marks it discarded

curl -X POST https://app.getera.io/api/v1/form_submissions/FORM_SUBMISSION_ID/actions/discard_submission \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "forms.submission_discarded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.formSubmissions.discardSubmission("FORM_SUBMISSION_ID")

era form_submissions discard_submission FORM_SUBMISSION_ID

{
  "name": "era__forms__discard_submission",
  "arguments": {
    "id": "FORM_SUBMISSION_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde forms:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 submission_not_found, submission_not_failed · 429 çok sık istek

forms.export_submissions

Gönderimleri dışa aktar — Bir formun her gönderimi tablo olarak: soruya göre yanıtlar, durum, kayıt ve onay.

Gereken izin forms:export · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır)

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: forms.submissions_exported

curl -X POST https://app.getera.io/api/v1/actions/forms.export_submissions \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"formId":"PUBLIC_FORM_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "forms.submissions_exported"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("forms.export_submissions", {
  formId: "PUBLIC_FORM_ID"
})

era forms export_submissions \
  --form-id "PUBLIC_FORM_ID"

{
  "name": "era__forms__export_submissions",
  "arguments": {
    "formId": "PUBLIC_FORM_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde forms:export izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 form_not_found · 429 çok sık istek

forms.record_retry

Yeniden denenen gönderimi kaydet — Başarısız bir gönderimi dönüştüğü kayıtla kabul edildi ya da yeniden başarısız işaretler.

Gereken izin forms:manage · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/forms.record_retry

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: forms.submission_recovered, forms.submission_failed

Neye yazar: form_submission (update) — Writes the retry outcome

curl -X POST https://app.getera.io/api/v1/form_submissions/FORM_SUBMISSION_ID/actions/record_retry \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"recordType":"Record type"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "forms.submission_recovered",
    "forms.submission_failed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.formSubmissions.recordRetry("FORM_SUBMISSION_ID", {
  recordType: "Record type"
})

era form_submissions record_retry FORM_SUBMISSION_ID \
  --record-type "Record type"

{
  "name": "era__forms__record_retry",
  "arguments": {
    "id": "FORM_SUBMISSION_ID",
    "recordType": "Record type"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde forms:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 submission_not_found, submission_not_failed · 429 çok sık istek

forms.save_form

Form oluştur veya düzenle — Herkese açık bir forma ad verir, ne oluşturacağına ve yanıt alıp almadığına karar verir.

Gereken izin forms:manage · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/forms.save_form

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: forms.form_saved

Neye yazar: public_form (upsert) — Writes the form

curl -X POST https://app.getera.io/api/v1/public_forms/PUBLIC_FORM_ID/actions/save_form \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"slug":"Address","title":"Title"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "forms.form_saved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.publicForms.saveForm("PUBLIC_FORM_ID", {
  slug: "Address",
  title: "Title"
})

era public_forms save_form PUBLIC_FORM_ID \
  --slug "Address" \
  --title "Title"

{
  "name": "era__forms__save_form",
  "arguments": {
    "id": "PUBLIC_FORM_ID",
    "slug": "Address",
    "title": "Title"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde forms:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 invalid_slug, slug_taken, unknown_form_kind, target_module_off, form_table_not_found, view_not_form, invalid_redirect · 429 çok sık istek

forms.set_fields

Formun alanlarını belirle — Tüm alan listesini, gösterilecekleri sırayla ve kurallarıyla değiştirir.

Gereken izin forms:manage · siler ya da geri alınamaz

• Asıl adres: POST /api/v1/actions/forms.set_fields

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: forms.fields_changed

Neye yazar: public_form_field (delete) — Clears the old list; public_form_field (insert) — Writes the new one, in order

curl -X POST https://app.getera.io/api/v1/public_form_fields/actions/set_fields \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"formId":"PUBLIC_FORM_ID","fields":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "forms.fields_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.publicFormFields.setFields({
  formId: "PUBLIC_FORM_ID",
  fields: {}
})

era public_form_fields set_fields --data '{"formId":"PUBLIC_FORM_ID","fields":{}}'

{
  "name": "era__forms__set_fields",
  "arguments": {
    "formId": "PUBLIC_FORM_ID",
    "fields": {}
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde forms:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 form_not_found, invalid_fields, duplicate_target, unknown_target, type_not_submittable, invalid_visibility, invalid_validation · 429 çok sık istek

forms.submit

Web sitesinden form gönder — Bir ziyaretçi sitenizdeki formlarınızdan birini doldurur.

Gereken izin forms:write · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır) · Yayındaki bir siteden de çağrılabilir (visitor)

• Asıl adres: POST /api/v1/actions/forms.submit

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: forms.submitted

Neye yazar: form_submission (insert) — Logs the answers; a lead form also creates its lead

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde forms:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 form_not_answering, form_writes_table, answers_invalid, consent_required, too_many_submissions · 429 çok sık istek

Veri modelleri

FormSubmission

Tablo form_submission · Kaynak form_submissions

• GET /api/v1/form_submissions
• GET /api/v1/form_submissions/{id}

Birincil anahtar: id

Denetimler:

• CHECK ((jsonb_typeof(answers) = 'object'::text))
• CHECK (((status <> 'accepted'::text) OR (record_id IS NOT NULL)))

PublicFormField

Tablo public_form_field · Kaynak public_form_fields

• GET /api/v1/public_form_fields
• GET /api/v1/public_form_fields/{id}

Birincil anahtar: id

Tekil: form_id, target, target_key

Denetimler:

• CHECK ((length(btrim(label)) > 0))
• CHECK ((col_span = ANY (ARRAY[1, 2])))
• CHECK (((jsonb_typeof(validation) = 'object'::text) AND ((visible_when IS NULL) OR (jsonb_typeof(visible_when) = 'object'::text))))

PublicForm

Tablo public_form · Kaynak public_forms

• GET /api/v1/public_forms
• GET /api/v1/public_forms/{id}

Birincil anahtar: id

Denetimler:

• CHECK (((redirect_url IS NULL) OR (redirect_url ~ '^https?://'::text)))
• CHECK ((jsonb_typeof(settings) = 'object'::text))
• CHECK (((slug ~ '^[a-z0-9]+(-[a-z0-9]+)*$'::text) AND ((length(slug) >= 1) AND (length(slug) <= 80))))
• CHECK (((kind = 'table'::text) = (data_table_id IS NOT NULL)))

Olaylar

İş akışları ve webhook'lar bu olaylara tepki verir.