Borkol Docs startpagina

Formulieren

Inzendingen

Verstuur de antwoorden en uploadtokens van een bezoeker op een actief formulier vanaf je server, met de header voor het bezoekers-IP, honeypot, limiet per uur, Turnstile, validatiefouten en de bedank-response.

Bekijk als Markdown

Een inzending is de set antwoorden van één bezoeker op één formulier. Verstuur haar vanaf je server, nooit vanuit de browser: met de forms:write-sleutel die ervoor nodig is, kan iemand mail versturen namens de merchant (zie Houd forms:write-sleutels op je server).

POST /v1/api/forms/{key}/submissions

Controleert de antwoorden tegen de gepubliceerde versie van het formulier, claimt de geüploade bestanden, slaat de inzending op, nummert haar en antwoordt met de bedankinstellingen. Vereist de scope forms:write. Het formulier moet actief en gepubliceerd zijn.

Padparameters

NaamTypeVerplichtBeschrijving
keystringJaDe key van het formulier, bijvoorbeeld quote-request.

Headers

NaamTypeVerplichtBeschrijving
AuthorizationstringJaBearer {forms_write_key}.
Content-TypestringJaapplication/json.
X-Borkol-Visitor-IpstringNeeHet IP-adres van de bezoeker (IPv4 of IPv6). De limiet per uur telt per bezoekersadres, en de Turnstile-controle wordt ermee verstuurd. Ontbreekt hij of is het geen geldig IP-adres, dan wordt het adres van de verbinding (je server) gebruikt. Zie Bezoekers-IP en de limiet per uur.
User-AgentstringNeeWordt bij de inzending opgeslagen (eerste 500 tekens) en in de inbox als browser getoond. Stuur de eigen User-Agent van de bezoeker door als je die daar wilt zien.

Bodyparameters

NaamTypeVerplichtBeschrijving
answersobjectJaAntwoorden per veld-key; mag {} zijn. De waardetypes per veldtype staan onder Veldtypes. Onbekende keys, heading- en paragraph-velden en antwoorden op velden die door hun regels verborgen zijn, vallen zonder fout weg.
localestringNeeDe taal van de bezoeker, maximaal 16 tekens, bijvoorbeeld nl. Een taal die is ingeschakeld voor de winkel bepaalt de taal van thank_you.message en van de bevestigingsmail aan de bezoeker; anders geldt de standaardtaal van de winkel.
filesobjectNeeBestandsantwoorden: veld-key naar een lijst uploadtokens van POST /v1/api/forms/{key}/uploads, bijvoorbeeld {"photos": ["9b2f0c3e-..."]}. Maximaal max_files tokens per veld. Verplichte bestandsvelden beantwoord je hier; een waarde voor een bestandsveld in answers wordt genegeerd.
turnstile_tokenstringVoorwaardelijkHet token van de Cloudflare Turnstile-widget. Verplicht als het formulier settings.turnstile_site_key teruggeeft; anders genegeerd. Werkt één keer: haal na elke 422 een nieuw token op. Zie Turnstile.
metaobjectNeePaginagegevens die in de inbox van de merchant verschijnen. Alles wat hieronder niet staat, wordt genegeerd.
meta.page_urlstringNeeDe pagina waarop het formulier stond. Wordt alleen bewaard als het een absolute http://- of https://-URL van maximaal 2000 tekens is; anders valt hij weg.
meta.referrerstringNeeDe pagina waar de bezoeker vandaan kwam. Zelfde regel als page_url.
meta.utmobjectNeeCampagnewaarden, bijvoorbeeld {"source": "google", "campaign": "spring"}. Alleen stringwaarden; de eerste 10 keys van maximaal 200 tekens blijven bewaard en waarden worden ingekort tot 200 tekens.
honeypotstringNeeDe waarde van een invoerveld dat mensen nooit zien. Elke andere waarde dan een lege string of null: het request wordt als bot behandeld (zie hieronder).
Request
curl -X POST "https://api.borkol.com/v1/api/forms/quote-request/submissions" \
  -H "Authorization: Bearer {forms_write_key}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Borkol-Visitor-Ip: 203.0.113.24" \
  -d '{
    "locale": "en",
    "answers": {
      "services": ["website"],
      "pages": 8,
      "campaign": "spring",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "consent": true
    },
    "files": {
      "brief": ["9b2f0c3e-5a1d-4f7e-8c2b-1d3e4f5a6b7c"]
    },
    "turnstile_token": "0.AbCdEf...",
    "meta": {
      "page_url": "https://example.com/quote",
      "referrer": "https://www.google.com/",
      "utm": { "source": "google" }
    },
    "honeypot": ""
  }'
Request (JS)
// A Next.js route handler: the browser posts { locale, answers, files, turnstile_token } here, never to Borkol.
export async function POST(request) {
  const body = await request.json();
  // Only trust an IP header your own proxy or host sets.
  const visitorIp = request.headers.get("x-real-ip") ?? "";
  const res = await fetch("https://api.borkol.com/v1/api/forms/quote-request/submissions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BORKOL_FORMS_KEY}`,
      "Content-Type": "application/json",
      Accept: "application/json",
      "X-Borkol-Visitor-Ip": visitorIp,
      "User-Agent": request.headers.get("user-agent") ?? "",
    },
    body: JSON.stringify({ ...body, meta: { page_url: request.headers.get("referer") ?? undefined } }),
  });
  return new Response(res.body, { status: res.status, headers: { "Content-Type": "application/json" } });
}

Status: 201 Created. Het resultaat is verpakt in data.

NaamTypeVerplichtBeschrijving
numberstring of nullaltijdHet nummer van de inzending, bijvoorbeeld INQ-0042, uit de nummerreeks voor aanvragen van de winkel (standaard INQ- en een doorlopend nummer van vier cijfers). Alleen null bij een honeypot-hit.
thank_you.messagestring of nullaltijdHet bedankbericht in de taal van de inzending, of null als de merchant er geen heeft geschreven.
thank_you.redirect_urlstring of nullaltijdEen https://-adres om de bezoeker naartoe te sturen, of null om het bericht te tonen.
Response
{
  "data": {
    "number": "INQ-0042",
    "thank_you": {
      "message": "Thanks! We will get back to you soon.",
      "redirect_url": null
    }
  }
}

Hoe een inzending wordt gecontroleerd

In deze volgorde:

  1. Het formulier wordt opgezocht: 404 als het niet actief is of nooit is gepubliceerd.
  2. Honeypot. Heeft honeypot een andere waarde dan een lege string of null, dan antwoordt de API meteen 201 met {"number": null, "thank_you": {...}}. Er wordt niets opgeslagen, er gaat geen mail of webhook uit, Turnstile wordt niet gecontroleerd, en de poging telt niet mee voor de limiet per uur. Vertel de bezoeker niets anders: de response lijkt met opzet op een succes.
  3. Limiet per uur. De poging wordt geteld voor dit formulier en dit bezoekersadres (uit X-Borkol-Visitor-Ip). Boven de limiet van het formulier (de merchant stelt 1 tot 100 per uur in, standaard 5) antwoordt de API 429. Elke getelde poging gaat van het budget af, ook pogingen die daarna met 422 stranden.
  4. Turnstile, alleen als het formulier settings.turnstile_site_key teruggeeft. Het turnstile_token wordt bij Cloudflare gecontroleerd; een mislukte controle geeft 422 op turnstile. Vanaf hier is het token opgebruikt, wat er daarna ook gebeurt.
  5. Antwoorden. Eerst wordt de vorm van de body gecontroleerd, daarna de antwoorden tegen de gepubliceerde versie: regels bepalen welke stappen en velden worden getoond, antwoorden op velden die door hun regels verborgen zijn vallen weg en zijn niet verplicht, verplichte zichtbare velden moeten zijn beantwoord, en elke waarde moet bij zijn type passen. Uploadtokens in files worden hier als lijst gecontroleerd (fouten op files.{key}).
  6. Bestanden. Alleen als de antwoorden kloppen: elk token van een zichtbaar bestandsveld wordt geclaimd. Elk token moet bestaan, bij dit formulier en dit veld horen, ongebruikt en niet verlopen zijn, en één keer voorkomen; anders antwoordt de API 422 op files.{key}. Het claimen gebeurt in dezelfde transactie als het opslaan, dus een geweigerde inzending claimt niets: de bezoeker kan de antwoorden verbeteren en dezelfde tokens opnieuw sturen (met een nieuw Turnstile-token).
  7. Opgeslagen. De zichtbare antwoorden (inclusief waarden van hidden-velden) worden opgeslagen met de versie, de taal en meta; de geclaimde bestanden worden aan de inzending gekoppeld. Het ruwe bezoekers-IP wordt nooit opgeslagen, alleen een HMAC-SHA256-hash ervan. De inzending wordt aan een contact gekoppeld als het e-mailadres overeenkomt met precies één contact van de winkel (hoofdletterongevoelig); er wordt nooit een contact aangemaakt.
  8. Gemeld nadat het antwoord is opgeslagen: een e-mail aan de merchant, een bevestigingsmail aan de bezoeker (als het formulier die aan heeft staan en de bezoeker een e-mailadres gaf), een melding in het dashboard en de webhook form_submission.created. Als een van deze stappen mislukt, wordt dat voor de merchant vastgelegd; de 201 verandert nooit.

Adresvelden en het werkgebied

Voor elk zichtbaar address-veld met opzoeken (config.lookup: true) zoekt de server de postcode en het huisnummer opnieuw op voordat hij het werkgebied controleert:

  • Gevonden: de coördinaten van de treffer vervangen lat en lon als je er geen stuurde, of als de jouwe meer dan 1 km van de treffer liggen.
  • Niet gevonden: de coördinaten die je stuurde kunnen niet worden geverifieerd, dus lat en lon worden weggelaten (null).
  • Opzoeken niet beschikbaar: de coördinaten die je stuurde blijven zoals ze zijn.

Voor een veld met config.service_area meet de server daarna de afstand hemelsbreed van het startpunt tot de coördinaten van het adres en bewaart {distance_km, in_area} voor het veld in meta.address van de inzending, op veld-key (de merchant ziet het in de inbox). distance_km en in_area zijn null als het adres geen coördinaten heeft. Een veld zonder werkgebied voegt niets toe aan meta.address.

  • mode: "notice": de inzending wordt geaccepteerd, wat het oordeel ook is; de bezoeker heeft de melding al in jouw formulier gezien.
  • mode: "block": een inzending waarvan het adres aantoonbaar buiten het gebied ligt (in_area is false) geeft 422 op answers.{key} met de message van het veld in de taal van de inzending. Een adres zonder coördinaten (niet gevonden, of opzoeken niet beschikbaar en geen coördinaten van jou) wordt geaccepteerd. block vereist lookup: true, omdat alleen een opgezocht adres geverifieerde coördinaten heeft.

Fouten

422 validatie. De standaard envelope (zie Errors en rate limits), met fouten per pad:

KeyWanneer
answersanswers ontbreekt of is geen object.
localeGeen string, of langer dan 16 tekens.
files, metaAanwezig maar geen object.
turnstileHet formulier heeft Turnstile aan en het token ontbreekt, is ongeldig, verlopen of al gebruikt, of Cloudflare kon het niet bevestigen.
answers.{key}Het antwoord op een zichtbaar veld ontbreekt of past niet bij zijn type.
files.{key}Een verplicht zichtbaar file-veld heeft geen tokens, de waarde is geen lijst tokens of heeft er meer dan max_files, of een token kan niet worden geclaimd.
Response
{
  "message": "This field is required. (and 1 more error)",
  "errors": {
    "answers.name": ["This field is required."],
    "answers.email": ["Must be an email address."]
  }
}

De meldingen op answers.{key} en files.{key}:

MeldingType
This field is required.Elk verplicht veld dat leeg is gelaten, behalve consent.
You must accept this.consent: verplicht en leeg gelaten (false telt als leeg), of een antwoord dat true noch leeg is.
Must be text of at most 255 characters.text.
Must be text of at most 10000 characters.textarea.
Must be a number.number.
Must be an email address.email.
Must be a phone number.phone.
Must be a date in YYYY-MM-DD format.date.
Must be one of the configured options.select.
Must be a link., A link needs a url., A link must be absolute, root-relative, mailto: or tel:., A link label may be at most 200 characters.link.
Choose one of the options.choice: een waarde die geen optie is (of geen lijst bij multiple).
Choose at least {min}., Choose at most {max}.choice met multiple, buiten min of max.
Must be text of at most 500 characters.hidden.
Must be a valid address.address: geen object, een ongeldige postcode of coördinaten buiten bereik. Een ontbrekende postcode, een ontbrekend huisnummer, een ontbrekende straat of plaats geeft This field is required.
Must be a list of files., At most {max} files are allowed.file.
This upload is invalid or has expired. Upload the file again.file: een token dat niet bestaat, bij een ander formulier of veld hoort, al is gebruikt, verlopen is (24 uur na de upload) of twee keer voorkomt.

De melding op turnstile is The spam check failed. Reload the page and try again. Reset na elke 422 de Turnstile-widget: het token is gebruikt.

@borkol/forms geeft precies deze meldingen terug uit check (behalve de upload- en Turnstile-meldingen, die alleen de server kan geven), zodat je de fouten van de server en je eigen fouten op dezelfde manier kunt tonen.

429 limiet per uur.

Response
{
  "message": "Too many submissions. Try again later."
}

Deze response heeft geen Retry-After-header. Ook de winkelbrede limiet van 120 requests per minuut kan 429 geven, met de melding Too Many Attempts. en een Retry-After-header.

Andere fouten.

  • 404 als geen formulier van de winkel deze key heeft, of als het een concept is, gearchiveerd, nooit gepubliceerd of verwijderd.
  • 403 {"error":"Module not enabled: forms"} als de module forms uit staat voor de winkel, en 403 {"message":"Invalid ability provided."} als de sleutel forms:write mist.
  • 401 zoals op elke /v1/api-route.