Opprette et skjema og en forespørsel i ett kall

Når du bør bruke det

En forespørsel peker vanligvis på et skjema noen har bygget i editoren og publisert. Når spørsmålene avhenger av saken, sender avsenderen dem med i stedet: requests.create tar form i stedet for formId. Formstep bygger et vanlig skjema av blokkene, publiserer det og oppretter forespørselen i ett steg, så enten finnes begge eller ingen av dem. Vi kaller det et skjema fra forespørsel.

Fortsett å bruke formId for et skjema du sender til mange med samme innhold og vil utforme for hånd i editoren. Bruk form når en automatisering bestemmer hva som skal spørres om.

Kallet

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

Alt annet ved forespørselen beholder sin betydning: recipient, prefill, context, readonly, delivery, påminnelser, utløp, callbackUrl, test og idempotencyKey kontrolleres mot det nye skjemaet akkurat som mot et skjema bygget for hånd. Responsen får i tillegg skjemaet, med nøklene svarene kommer tilbake under:

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

For å forhåndsutfylle et valgspørsmål i samme kall sender du valgnøkler, som for ethvert skjema. Et valgs nøkkel avledes fra etiketten, så Self-employed blir self_employed. En etikett i stedet for en nøkkel feiler med INVALID_PREFILL_VALUE, som lister de gyldige nøklene.

Skjemaobjektet

Blokker

En blokk tar parameterne til det tilsvarende editor_insert*-verktøyet på MCP-serveren , uten formId og after, pluss en valgfri key. Uten nøkkel utledes den fra tittelen, så “Fullt navn” blir fullt_navn. En parameter blokken ikke kjenner, avvises i stedet for å bli ignorert.

Tekst i header og paragraph, listepunkter og tabellceller forstår bold, italic, struck, <u>underlined</u>, code, $$equation$$, text, <span color=“red” background=“yellow” font=“font-georgia” size=“1.25”>…</span> med fargene, skriftene og størrelsene fra editorens verktøylinje, og {{key}}, som viser verdien til feltet med den nøkkelen. Formateringer kan nøstes; en markør uten motpart blir vanlig tekst. En kolonne i en rad tar alle blokker unntatt pageDivider, logic, hiddenField, calculatedField, repeatingGroup, row og scheduleAppointment. En decision-blokk tar title og labels for godkjenn, avslå og endringer på skjemaets språk.

Blokker refererer til hverandre med nøkkel, aldri med element-ID: en logic-blokk tar rule slik editor_insertLogic gjør, med feltnøkler der den vil ha ID-er, alternativenes etiketter som betingelsesverdier og sidenavn for setNextPage.

Betalinger

En payment-blokk tar amount og currency, eller amountFromField: nøkkelen til et skjult felt eller et tallspørsmål. Med et skjult felt sender hver forespørsel sitt eget beløp i context, så ett skjema tar betalt riktig beløp fra hver kunde:

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

Et tallspørsmål som setter beløpet, må være påkrevd og ha en min over 0, slik at ingen kommer til checkout med et tomt beløp, null eller et negativt beløp.

Skjemaet tar betalt via arbeidsområdets standard Stripe-konto, eller kontoen connection peker på. En person kobler til Stripe én gang for arbeidsområdet; en automatisering kan ikke. Uten en brukbar konto feiler kallet og forteller deg hvor du kobler den til.

Bookinger

En scheduleAppointment-blokk tar eventType, tittelen eller ID-en til en hendelsestype på arbeidsområdets Cal.com-tilkobling, og connection når arbeidsområdet har flere. Formstep slår opp hendelsestypen når forespørselen opprettes. prefill: { name, email } angir spørsmålene som fyller ut bookingen med svarene sine.

Merkevaren din

En automatisering kan ikke finne på utseendet ditt, så du gir det til den én gang, og den sender det med hver forespørsel: logo, cover og emoji ved siden av blokkene, og theme for farger og skrift.

Hvert bilde, også src i en bildeblokk, må være en offentlig JPEG, PNG eller WebP. Formstep henter hvert bilde én gang når skjemaet opprettes og beholder sin egen kopi, så skjemaet og PDF-ene av innsendingene varer lenger enn kilden. En URL som ikke kan hentes, får kallet til å feile med INLINE_FORM_IMAGE_UNREACHABLE, som nevner feltet. Uten merkevare ser skjemaet ut som et nytt skjema fra dashbordet.

Oversettelser

translations publiserer skjemaet på flere språk med en gang, og mottakeren får språkvelgeren et oversatt skjema har: { "de": { "Your name": "Ihr Name", "Order for **{{customer}}**": "Bestellung für **{{customer}}**" } }. Hver tekst i skjemaet må være med, med teksten nøyaktig slik blokkene skrev den som nøkkel: spørsmålstitler, alternativer, plassholdere, overskrifter, avsnitt, listepunkter, tabellceller, gruppenavn og knappetekster. Formatering og {{key}} blir stående som i kilden. En tekst som mangler, får kallet til å feile med INLINE_FORM_TRANSLATION_MISSING, som lister tekstene som må legges til. E-postteksten oversettes ikke.

Én definisjon, ett skjema

Et senere kall med det samme form-objektet gjenbruker det samme skjemaet, og responsen sier “reused”: true. Hundre forespørsler med én definisjon gir ett skjema, med ett sett svar å eksportere. Endrer du en blokk, navnet, merkevaren eller en oversettelse, blir det et nytt skjema; forespørsler som allerede er sendt, beholder skjemaet de ble opprettet med. Et skjema du lukker eller avpubliserer, blir ikke gjenbrukt: neste kall med samme definisjon lager et nytt.

Når et kall lager et nytt skjema selv om et åpent skjema fra forespørsel har de samme blokktypene i samme rekkefølge, nevner svaret det skjemaet i form.similarForm. Som oftest skyldes det et endret navn eller en endret tittel. For å lese alle svar på ett skjema fra forespørsel, list innsendingene i stedet for å lese hver forespørsel.

På dashbordet

Et skjema fra en forespørsel hører til forespørselen, så det ligger på forespørselens side i stedet for på Skjemaer-siden. Siden viser svarene etter feltnøkkel, og Forhåndsvis åpner skjemaet slik mottakeren så det, utfylt med svarene deres. En lenke til editoren eller innsendingene for et slikt skjema åpner i stedet Forespørsler-siden, filtrert på det skjemaet. Agenter ser fortsatt disse skjemaene i form_list, og API-et nekter å endre dem.

Et skjema fra en forespørsel har ingen delingslenke, og du kan ikke legge til en: forespørslene er eneste vei inn, og callbacken har med hvert svar. Det har heller ingen integrasjoner.

Fordi det ikke har noen egen side, slettes et inline-skjema aldri for hånd. Det følger med den siste forespørselen sin: når du sletter en forespørsel, eller skjemaets oppbevaringsperiode tar den, og ingen andre forespørsler fortsatt bruker skjemaet, slettes skjemaet også.

Når kallet avvises

Hver avvisning er en VALIDATION_ERROR med en details.reason automatiseringen din kan forgrene på. Ingenting opprettes.

Fra en agent

På MCP-serveren tar request_create det samme form. Før en agent bygger et skjema med en betaling eller en booking, leser den workspaceConnection_list: den viser de tilkoblede Stripe- og Cal.com-kontoene og, når en mangler, lenken en person må åpne én gang. scheduler_listEventTypes lister hendelsestypene en booking kan nevne, og paymentConnection_setDefault endrer standard Stripe-konto. I REST-API-et heter de samme tre connections.list, scheduler.listEventTypes og paymentConnections.setDefault.