Go

Appelez Formerie à partir de n’importe quel serveur Go avec net/http, de la bibliothèque standard, sans rien à installer. Vous n’avez besoin ni d’un paquet Formerie ni d’une clé d’API : l’adresse publique d’un formulaire suffit.

Soumettre un formulaire

Enregistrez ce code sous main.go, puis lancez go run main.go.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

func main() {
	runtimeURL := os.Getenv("FORMERIE_RUNTIME_URL")
	if runtimeURL == "" {
		runtimeURL = "https://forms.formerie.com"
	}
	// Your form. This is the only line that names it.
	form := os.Getenv("FORMERIE_FORM")
	if form == "" {
		form = "acme/contact"
	}

	body, err := json.Marshal(map[string]any{
		"fields": map[string]any{
			"name":    "Jane Example",
			"email":   "jane@example.com",
			"message": "Hello from my server",
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	client := &http.Client{Timeout: 10 * time.Second}
	response, err := client.Post(runtimeURL+"/"+form+"/submit", "application/json", bytes.NewReader(body))
	if err != nil {
		log.Fatal(err)
	}
	defer response.Body.Close()

	var result struct {
		OK            bool   `json:"ok"`
		SubmissionUID string `json:"submissionUid"`
		Error         struct {
			Code string `json:"code"`
		} `json:"error"`
	}
	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.StatusCode, result.SubmissionUID, result.Error.Code)
}

Remplacez acme/contact, sur la ligne indiquée, par vos propres identifiants. Une réussite donne l’état HTTP 202, avec un submissionUid comme sub_p6dr8wq2j7tkan : les réponses sont stockées et leur courriel est en file d’attente. Chaque exemple lit deux réglages facultatifs dans l’environnement : FORMERIE_RUNTIME_URL pour un nom d’hôte que vous avez branché, et FORMERIE_FORM pour les identifiants.

Avant de commencer

Publiez un formulaire, et prenez ses identifiants d’espace de travail et de formulaire dans l’onglet Publication. Votre serveur n’a pas besoin de figurer dans les sites autorisés du formulaire.
Pour faire des essais sans envoyer de courriel, créez une clé de test dans l’onglet Tests du formulaire, et mettez-la dans une variable d’environnement appelée FORMERIE_TEST_KEY :

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

func main() {
	runtimeURL := os.Getenv("FORMERIE_RUNTIME_URL")
	if runtimeURL == "" {
		runtimeURL = "https://forms.formerie.com"
	}
	// Your form. This is the only line that names it.
	form := os.Getenv("FORMERIE_FORM")
	if form == "" {
		form = "acme/contact"
	}

	body, err := json.Marshal(map[string]any{
		"fields": map[string]any{"name": "Jane Example", "email": "jane@example.com", "message": "Just a test"},
	})
	if err != nil {
		log.Fatal(err)
	}
	request, err := http.NewRequest(http.MethodPost, runtimeURL+"/"+form+"/submit", bytes.NewReader(body))
	if err != nil {
		log.Fatal(err)
	}
	request.Header.Set("Content-Type", "application/json")
	// Keep the key out of your code. A test is stored apart and emails nobody.
	request.Header.Set("X-Formerie-Test-Key", os.Getenv("FORMERIE_TEST_KEY"))

	client := &http.Client{Timeout: 10 * time.Second}
	response, err := client.Do(request)
	if err != nil {
		log.Fatal(err)
	}
	defer response.Body.Close()

	var result struct {
		OK            bool   `json:"ok"`
		SubmissionUID string `json:"submissionUid"`
		Error         struct {
			Code string `json:"code"`
		} `json:"error"`
	}
	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.StatusCode, result.SubmissionUID, result.Error.Code)
}

Un test revient sous la forme tst_..., est stocké à part et n’envoie de courriel à personne. Une mauvaise clé reçoit TEST_KEY_INVALID, état HTTP 401, et rien n’est stocké. Retirez l’en-tête avant la mise en ligne, car une clé laissée en place classe tout comme un test. Consultez Tester depuis un serveur ou l’intégration continue.

Vérifier des réponses sans soumettre

validate vérifie les réponses et ne stocke rien, ce qui vous permet de signaler un problème tôt. Il répond 200 quand elles passent, et 422 avec les mêmes erreurs qu’une soumission quand elles ne passent pas. La soumission finale vérifie toujours tout le formulaire de nouveau.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

var client = &http.Client{Timeout: 10 * time.Second}

type issue struct {
	Path    string `json:"path"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

type checked struct {
	OK     bool           `json:"ok"`
	Values map[string]any `json:"values"`
	Error  struct {
		Code   string             `json:"code"`
		Fields map[string][]issue `json:"fields"`
	} `json:"error"`
}

func formURL(action string) string {
	runtimeURL := os.Getenv("FORMERIE_RUNTIME_URL")
	if runtimeURL == "" {
		runtimeURL = "https://forms.formerie.com"
	}
	// Your form. This is the only line that names it.
	form := os.Getenv("FORMERIE_FORM")
	if form == "" {
		form = "acme/contact"
	}
	return runtimeURL + "/" + form + "/" + action
}

// checkAnswers stores nothing. With no step, only the fields you send are checked.
func checkAnswers(fields map[string]any, step string) (*checked, error) {
	payload := map[string]any{"mode": "partial", "fields": fields}
	if step != "" {
		payload = map[string]any{"mode": "step", "step": step, "fields": fields}
	}
	body, err := json.Marshal(payload)
	if err != nil {
		return nil, err
	}
	response, err := client.Post(formURL("validate"), "application/json", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	defer response.Body.Close()

	var result checked
	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
		return nil, err
	}
	if !result.OK && result.Error.Code != "VALIDATION_FAILED" {
		return nil, fmt.Errorf("formerie: %s", result.Error.Code)
	}
	return &result, nil
}

Par défaut, seuls les champs que vous envoyez sont vérifiés. Passez une étape pour vérifier plutôt tous ses champs, sur un formulaire à étapes. Une étape que le formulaire n’a pas reçoit BAD_REQUEST.

Afficher les erreurs par champ

Les réponses refusées reviennent avec VALIDATION_FAILED, état HTTP 422, et rien n’est stocké. error.fields contient les problèmes par champ, et error.issues les mêmes, dans l’ordre. Chacun a un path, un code sur lequel vous fier et un message que vous pouvez afficher, dans la langue du formulaire.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"html"
	"net/http"
	"os"
	"strings"
	"time"
)

var client = &http.Client{Timeout: 10 * time.Second}

type issue struct {
	Path    string `json:"path"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

type submitResult struct {
	OK    bool `json:"ok"`
	Error struct {
		Code   string             `json:"code"`
		Fields map[string][]issue `json:"fields"`
	} `json:"error"`
}

func formURL(action string) string {
	runtimeURL := os.Getenv("FORMERIE_RUNTIME_URL")
	if runtimeURL == "" {
		runtimeURL = "https://forms.formerie.com"
	}
	// Your form. This is the only line that names it.
	form := os.Getenv("FORMERIE_FORM")
	if form == "" {
		form = "acme/contact"
	}
	return runtimeURL + "/" + form + "/" + action
}

func submitAnswers(fields map[string]any) (*submitResult, error) {
	body, err := json.Marshal(map[string]any{"fields": fields})
	if err != nil {
		return nil, err
	}
	response, err := client.Post(formURL("submit"), "application/json", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	defer response.Body.Close()

	var result submitResult
	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
		return nil, err
	}
	return &result, nil
}

// answerAt finds the visitor's answer for a path such as contact.email, so the form can show it again.
func answerAt(answers map[string]any, path string) string {
	var value any = answers
	for _, part := range strings.Split(path, ".") {
		group, ok := value.(map[string]any)
		if !ok {
			return ""
		}
		value = group[part]
	}
	if value == nil {
		return ""
	}
	return fmt.Sprint(value)
}

// renderField is one input with its answer kept and its first message under it.
func renderField(path string, answers map[string]any, result *submitResult) string {
	field := fmt.Sprintf(`<input name="%s" value="%s">`, html.EscapeString(path), html.EscapeString(answerAt(answers, path)))
	if issues := result.Error.Fields[path]; len(issues) > 0 {
		field += fmt.Sprintf(`<p class="error">%s</p>`, html.EscapeString(issues[0].Message))
	}
	return field
}

Un champ dans un groupe a un chemin comme contact.email, et un champ dans une liste, guests[0].email : séparez le chemin pour trouver sa réponse. Consultez Chemins de champs. Réaffichez les réponses du visiteur avec les messages, échappées, pour qu’il n’ait qu’à corriger ce qui ne va pas.

Réessayer en toute sécurité

Une panne de réseau ne vous dit pas si la soumission est arrivée. Envoyez donc une seule metadata.idempotencyKey par soumission, la même à chaque nouvel essai. Formerie la compte et la livre alors une seule fois, et signale une répétition avec DUPLICATE_SUBMISSION, état HTTP 409, qui veut dire que le premier envoi a fonctionné.

package main

import (
	"bytes"
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"math/big"
	"net/http"
	"os"
	"strconv"
	"time"
)

const (
	maxAttempts = 3
	longestWait = 30 // seconds
)

var client = &http.Client{Timeout: 10 * time.Second}

type issue struct {
	Path    string `json:"path"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

type outcome struct {
	Outcome   string  `json:"outcome"`
	ID        string  `json:"id,omitempty"`
	Duplicate bool    `json:"duplicate,omitempty"`
	Reason    string  `json:"reason,omitempty"`
	After     int     `json:"after,omitempty"`
	Code      string  `json:"code,omitempty"`
	Message   string  `json:"message,omitempty"`
	Issues    []issue `json:"issues,omitempty"`
	Key       string  `json:"key"`
	Attempts  int     `json:"attempts"`
	again     bool
}

func submitURL() string {
	runtimeURL := os.Getenv("FORMERIE_RUNTIME_URL")
	if runtimeURL == "" {
		runtimeURL = "https://forms.formerie.com"
	}
	// Your form. This is the only line that names it.
	form := os.Getenv("FORMERIE_FORM")
	if form == "" {
		form = "acme/contact"
	}
	return runtimeURL + "/" + form + "/submit"
}

// sendOnce is one attempt. It says what happened, and whether another attempt could help.
func sendOnce(fields map[string]any, key string) outcome {
	body, err := json.Marshal(map[string]any{
		"fields":   fields,
		"metadata": map[string]any{"idempotencyKey": key},
	})
	if err != nil {
		return outcome{Outcome: "rejected", Reason: "bad-answers"}
	}
	response, err := client.Post(submitURL(), "application/json", bytes.NewReader(body))
	if err != nil {
		return outcome{Outcome: "retry-later", Reason: "network", again: true}
	}
	defer response.Body.Close()

	// Only the short-term limit sends Retry-After. A form's own limit can last an hour, so don't wait for it.
	if response.StatusCode == http.StatusTooManyRequests {
		after, err := strconv.Atoi(response.Header.Get("Retry-After"))
		return outcome{Outcome: "retry-later", Reason: "rate-limited", After: after, again: err == nil && after <= longestWait}
	}

	data, err := io.ReadAll(response.Body)
	if err != nil {
		return outcome{Outcome: "retry-later", Reason: "network", again: true}
	}
	var result struct {
		OK            bool   `json:"ok"`
		SubmissionUID string `json:"submissionUid"`
		Error         struct {
			Code    string  `json:"code"`
			Message string  `json:"message"`
			Issues  []issue `json:"issues"`
		} `json:"error"`
	}
	// Something in front of Formerie may answer without JSON.
	if err := json.Unmarshal(data, &result); err != nil {
		temporary := response.StatusCode == 502 || response.StatusCode == 503 || response.StatusCode == 504
		return outcome{Outcome: "retry-later", Reason: "bad-response", again: temporary}
	}

	if result.OK {
		return outcome{Outcome: "accepted", ID: result.SubmissionUID}
	}
	switch result.Error.Code {
	case "DUPLICATE_SUBMISSION":
		// The first send worked, and only its answer was lost.
		return outcome{Outcome: "accepted", Duplicate: true}
	case "FORM_MAINTENANCE", "QUEUE_FAILED", "INTERNAL_ERROR":
		return outcome{Outcome: "retry-later", Reason: result.Error.Code, again: true}
	case "VALIDATION_FAILED":
		return outcome{Outcome: "invalid", Code: result.Error.Code, Issues: result.Error.Issues}
	}
	return outcome{Outcome: "rejected", Code: result.Error.Code, Message: result.Error.Message}
}

func newKey() (string, error) {
	bytes := make([]byte, 16)
	if _, err := rand.Read(bytes); err != nil {
		return "", err
	}
	return hex.EncodeToString(bytes), nil
}

// backoff is a random wait of up to 500 ms, then 1 s, and at most 4 s.
func backoff(attempt int) time.Duration {
	longest := int64(250*time.Millisecond) << attempt
	if longest > int64(4*time.Second) {
		longest = int64(4 * time.Second)
	}
	wait, err := rand.Int(rand.Reader, big.NewInt(longest))
	if err != nil {
		return time.Duration(longest)
	}
	return time.Duration(wait.Int64())
}

// submitWithRetries takes one key per submission, the same on every retry. Store it with the answers if you retry later.
func submitWithRetries(fields map[string]any, key string) outcome {
	for attempt := 1; ; attempt++ {
		answer := sendOnce(fields, key)
		if !answer.again || attempt == maxAttempts {
			answer.Key, answer.Attempts = key, attempt
			return answer
		}
		wait := backoff(attempt)
		if after := time.Duration(answer.After) * time.Second; after > wait {
			wait = after
		}
		time.Sleep(wait)
	}
}

Réponse	Réessayer?
Pas de connexion, ou délai dépassé	Oui, avec la même clé
`429` avec `Retry-After`	Oui, après cette attente, si elle est courte. La limite à court terme répond avec `Retry-After: 60`
`429` sans `Retry-After`	Non. La limite d’un formulaire peut durer une heure : demandez au visiteur de réessayer plus tard
`FORM_MAINTENANCE`, `QUEUE_FAILED`, `INTERNAL_ERROR`	Oui, après une courte attente
`502`, `503` ou `504` sans JSON	Oui. Quelque chose devant Formerie a répondu
Toute autre réponse sans JSON	Non. Gardez la clé, et voyez ce qui s’est passé
`DUPLICATE_SUBMISSION`	Non. Traitez-le comme un succès
`VALIDATION_FAILED` et tout autre code	Non. La réponse ne changera pas

La clé doit être une chaîne non vide. Tout le reste est ignoré, et il n’y a alors aucune vérification des répétitions.
Une répétition est repérée pendant 300 secondes par défaut, selon la période d’envois répétés du formulaire. Consultez Ce que couvre la période d’envois répétés.
Cette vérification passe en premier : une clé déjà acceptée reçoit DUPLICATE_SUBMISSION, même avec d’autres réponses. Utilisez une nouvelle clé pour chaque nouvelle soumission. Une clé refusée à cause de ses réponses n’a jamais été acceptée : elle peut repartir une fois celles-ci corrigées.
Un nouvel essai après QUEUE_FAILED peut stocker une deuxième copie, que vous verriez sous Soumissions. C’est rare.

Vérification humaine

Si votre formulaire exige une vérification humaine, utilisez vos propres clés, avec votre site dans la liste de domaines du fournisseur et dans les sites autorisés du formulaire. Le widget ajoute son jeton à votre formulaire. Transmettez deux choses :

Le jeton, comme verificationToken, retiré des champs.
L’Origin de la requête du visiteur, parce que Formerie compare le domaine du jeton avec celui-ci. Un serveur n’en envoie pas de lui-même, et la vérification échoue alors avec TURNSTILE_FAILED.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

var client = &http.Client{Timeout: 10 * time.Second}

type submitResult struct {
	OK            bool   `json:"ok"`
	SubmissionUID string `json:"submissionUid"`
	Error         struct {
		Code string `json:"code"`
	} `json:"error"`
}

func submitURL() string {
	runtimeURL := os.Getenv("FORMERIE_RUNTIME_URL")
	if runtimeURL == "" {
		runtimeURL = "https://forms.formerie.com"
	}
	// Your form. This is the only line that names it.
	form := os.Getenv("FORMERIE_FORM")
	if form == "" {
		form = "acme/contact"
	}
	return runtimeURL + "/" + form + "/submit"
}

// submitVerified takes what your form sent, and the Origin header of the visitor's request.
func submitVerified(posted map[string]any, origin string) (*submitResult, error) {
	fields := map[string]any{}
	for name, value := range posted {
		if name != "cf-turnstile-response" {
			fields[name] = value
		}
	}
	body, err := json.Marshal(map[string]any{"fields": fields, "verificationToken": posted["cf-turnstile-response"]})
	if err != nil {
		return nil, err
	}
	request, err := http.NewRequest(http.MethodPost, submitURL(), bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	request.Header.Set("Content-Type", "application/json")
	// Without the visitor's Origin, the provider's hostname can't match, and the check fails.
	if origin != "" {
		request.Header.Set("Origin", origin)
	}
	response, err := client.Do(request)
	if err != nil {
		return nil, err
	}
	defer response.Body.Close()

	var result submitResult
	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
		return nil, err
	}
	return &result, nil
}

Une Origin absente des sites autorisés du formulaire reçoit FORBIDDEN_ORIGIN. Ne la transmettez que pour ça : sur tout autre formulaire, elle active une vérification dont votre serveur n’a autrement pas besoin. Le widget a besoin de JavaScript dans le navigateur du visiteur. Consultez La vérification avec un serveur.

Vérifications antipourriel

Les pages hébergées et les intégrations envoient ces métadonnées pour vous. À partir de votre serveur, envoyez-les vous-même, sinon ces vérifications sont sautées.

package main

import (
	"bytes"
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"strconv"
	"time"
)

var client = &http.Client{Timeout: 10 * time.Second}

type submitResult struct {
	OK            bool   `json:"ok"`
	SubmissionUID string `json:"submissionUid"`
	Error         struct {
		Code string `json:"code"`
	} `json:"error"`
}

func submitURL() string {
	runtimeURL := os.Getenv("FORMERIE_RUNTIME_URL")
	if runtimeURL == "" {
		runtimeURL = "https://forms.formerie.com"
	}
	// Your form. This is the only line that names it.
	form := os.Getenv("FORMERIE_FORM")
	if form == "" {
		form = "acme/contact"
	}
	return runtimeURL + "/" + form + "/submit"
}

func submitWithMetadata(fields map[string]any, startedAt time.Time, visitorID string) (*submitResult, error) {
	key := make([]byte, 16)
	if _, err := rand.Read(key); err != nil {
		return nil, err
	}
	body, err := json.Marshal(map[string]any{
		"fields": fields,
		"metadata": map[string]any{
			"idempotencyKey": hex.EncodeToString(key),
			// When the visitor opened the form, for the minimum submit time check.
			"startedAt": startedAt.UTC().Format(time.RFC3339),
			"pageUrl":   "https://www.example.com/contact",
			// Your own visitor ID, for a limit rule with the deviceToken scope.
			"deviceToken": visitorID,
		},
	})
	if err != nil {
		return nil, err
	}
	response, err := client.Post(submitURL(), "application/json", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	defer response.Body.Close()

	var result submitResult
	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
		return nil, err
	}
	return &result, nil
}

Champ	À quoi il sert
`idempotencyKey`	La vérification des répétitions, comme ci-dessus
`startedAt`	Le moment où le visiteur a ouvert le formulaire, en heure ISO 8601. Envoyé avant le minimum du formulaire, 1 seconde par défaut, il reçoit `SPAM_REJECTED`. Gardez la vraie heure à laquelle vous avez affiché le formulaire, pas celle de cet appel. Une valeur illisible saute la vérification
`pageUrl`	La page d’où le formulaire a été envoyé. Stockée seulement s’il s’agit d’une adresse http ou https
`deviceToken`	Votre propre identifiant de visiteur, pour une limite par visiteur, ci-dessous

La vérification du champ caché s’applique quand votre formulaire envoie ce champ, et les liens et la vérification humaine sont vérifiés sur le serveur dans tous les cas. Consultez Pourriel et limites.

Les limites à partir de votre serveur

Formerie compte les visiteurs par adresse réseau, et d’ici, c’est celle de votre serveur. Chaque visiteur compte comme votre serveur.

Limite	Par défaut	À partir de votre serveur
Par visiteur	30 soumissions toutes les 10 minutes	Partagée par tous vos visiteurs. Augmentez-la avant le lancement, ou laissez-la vide pour n’avoir aucune limite, sous Paramètres, puis Limites de soumission
Tout le formulaire	1 000 soumissions à l’heure	La même. Avec le forfait gratuit, c’est aussi le maximum qu’un formulaire peut accepter
Court terme	120 requêtes à la minute pour chaque formulaire à partir d’une même adresse	Ne peut pas être changée. C’est la seule qui envoie `Retry-After`. `validate` y compte aussi

Au-delà de l’une d’elles, vous recevez RATE_LIMITED, état HTTP 429. Pour garder une limite par visiteur, une règle avec la portée deviceToken compte selon l’identifiant que vous envoyez, comme un hachage de l’adresse du visiteur. Les paramètres de l’application n’offrent pas encore cette règle, alors écrivez-nous pour en mettre une en place, et gardez la limite pour tout le formulaire, car quiconque appelle directement le formulaire peut changer son identifiant. Consultez Les limites avec un serveur pour le raisonnement, et Forfaits et limites pour les compteurs mensuels.

Bon à savoir

http.DefaultClient n’expire jamais : créez votre propre http.Client avec un Timeout, et réutilisez-le.
Gardez les clés de test et les réponses hors de vos journaux. Le requestId d’une erreur, ou l’en-tête X-Request-Id, est ce qu’il faut journaliser et citer quand vous demandez de l’aide.
Fiez-vous à error.code, jamais au message, car un formulaire peut reformuler ses messages et un même état peut couvrir plusieurs codes. Codes d’erreur les énumère tous.

Avec	Note
Votre gestionnaire	Appelez `request.ParseForm()`, puis lisez `request.PostForm` pour les réponses et `request.Header.Get("Origin")` pour l’`Origin` du visiteur.
En combiner plusieurs	Les deux premiers blocs sont des programmes complets, et les autres sont des fonctions à y ajouter. Gardez un seul `client` et un seul `formURL`.

Les routes, les champs et toutes les erreurs se trouvent dans la référence de l’API.