Aller au contenu

Soumettre un formulaire POST ​

Envoyez une réponse. La soumission devient un message sur le compte du propriétaire et est transmise sous forme de notification push sur son téléphone, via le même traitement qu'un appel de webhook. Aucune authentification.

Point de terminaison ​

POST https://api.pocketalert.app/v1/forms/{tid}/submit

Authentification ​

Non requise

Toute personne disposant du lien peut soumettre. Le propriétaire contrôle qui peut le faire : voir origines autorisées et les limites ci-dessous.

Requête ​

Paramètres de chemin ​

ParamètreTypeRequisDescription
tidstring✅Identifiant du formulaire

Paramètres du corps ​

ParamètreTypeRequisDescription
valuesobject✅Réponses indexées par id du champ
websitestring❌Champ piège (honeypot). Ne le renseignez pas : toute valeur non vide est considérée comme un bot

Valeur attendue par type de champ :

TypeValeur
text, textarea, email, phone, number, urlChaîne de caractères. Le format est validé pour email, phone, number et url
dateChaîne de caractères, YYYY-MM-DD
dropdown, radioChaîne de caractères, l'une des options du champ
checkboxesTableau de chaînes de caractères issues de options
checkboxBooléen
ratingNombre, de 1 à 5
npsNombre, de 0 à 10
hiddenChaîne de caractères, généralement tirée de l'URL de la page

Les champs de mise en page (heading, paragraph, divider) n'acceptent aucune valeur, et les clés inconnues sont ignorées. Le corps est limité à 64 Ko.

Exemple de requête ​

bash
curl -X POST "https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "message": "Do you ship to Canada?",
      "src": "newsletter"
    }
  }'
javascript
const response = await fetch(
  'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      values: {
        name: 'Jane Doe',
        email: '[email protected]',
        message: 'Do you ship to Canada?'
      }
    })
  }
);

const result = await response.json();
if (response.status === 400) {
  // result.fields = { email: "Enter a valid email address" }
  console.log(result.fields);
}
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
    json={
        'values': {
            'name': 'Jane Doe',
            'email': '[email protected]',
            'message': 'Do you ship to Canada?',
        }
    }
)

print(response.status_code, response.json())

Réponse ​

Réponse en cas de succès ​

200 OK

json
{ "status": "ok" }

Le propriétaire reçoit une notification push construite à partir des réponses. Aucune information le concernant (son offre, ses appareils, son quota) n'est exposée au visiteur.

Erreurs de validation ​

400 Bad Request

fields associe l'id d'un champ à la raison de son rejet, ce que la page du formulaire affiche sous chaque champ.

json
{
  "error": "Please check the highlighted fields.",
  "fields": {
    "email": "Enter a valid email address",
    "name": "This field is required"
  }
}

Formulaire fermé ​

410 Gone

json
{
  "error": "This form is no longer accepting responses.",
  "closed": true
}

error contient le closed_message défini par le propriétaire.

Limites ​

LimiteValeur
Par IP10 soumissions par minute
Par formulaire60 par minute, 300 par heure
Quota du propriétaireChaque soumission consomme un message de sa limite quotidienne

Une soumission qui dépasserait la limite quotidienne de messages du propriétaire reçoit un 429 neutre accompagné d'un en-tête Retry-After, sans mention de l'offre.

Réponses d'erreur ​

StatutDescription
400Corps invalide, ou fields liste les réponses à corriger
403Le formulaire n'accepte pas les soumissions depuis ce site : voir origines autorisées
404Formulaire introuvable
410Le formulaire est fermé
429Trop de soumissions, ou le propriétaire a épuisé ses messages pour aujourd'hui
500Le formulaire est mal configuré, ou le message n'a pas pu être créé

Documentation de Pocket Alert