# 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](https://info.pocketalert.app/api/webhooks/create.md). **Aucune authentification**.

## Point de terminaison

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

## Authentification

> **Tip: Non requise**
>
> Toute personne disposant du lien peut soumettre. Le propriétaire contrôle qui peut le faire : voir [origines autorisées](https://info.pocketalert.app/api/forms/create.md#allowed-origins) et les limites ci-dessous.

## Requête

### Paramètres de chemin

| Paramètre | Type | Requis | Description |
|-----------|------|:--------:|-------------|
| `tid` | string | ✅ | Identifiant du formulaire |

### Paramètres du corps

| Paramètre | Type | Requis | Description |
|-----------|------|:--------:|-------------|
| `values` | object | ✅ | Réponses indexées par `id` du champ |
| `website` | string | ❌ | 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 :

| Type | Valeur |
|------|-------|
| `text`, `textarea`, `email`, `phone`, `number`, `url` | Chaîne de caractères. Le format est validé pour email, phone, number et url |
| `date` | Chaîne de caractères, `YYYY-MM-DD` |
| `dropdown`, `radio` | Chaîne de caractères, l'une des `options` du champ |
| `checkboxes` | Tableau de chaînes de caractères issues de `options` |
| `checkbox` | Booléen |
| `rating` | Nombre, de 1 à 5 |
| `nps` | Nombre, de 0 à 10 |
| `hidden` | Chaî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

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "message": "Do you ship to Canada?",
      "src": "newsletter"
    }
  }'
```

**JavaScript**

```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: 'jane@example.com',
        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**

```python
import requests

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

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

## Réponse

### Réponse en cas de succès

> **Tip: 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

> **Warning: 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é

> **Danger: 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

| Limite | Valeur |
|-------|-------|
| Par IP | 10 soumissions par minute |
| Par formulaire | 60 par minute, 300 par heure |
| Quota du propriétaire | Chaque 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

| Statut | Description |
|:------:|-------------|
| `400` | Corps invalide, ou `fields` liste les réponses à corriger |
| `403` | Le formulaire n'accepte pas les soumissions depuis ce site : voir [origines autorisées](https://info.pocketalert.app/api/forms/create.md#allowed-origins) |
| `404` | Formulaire introuvable |
| `410` | Le formulaire est fermé |
| `429` | Trop de soumissions, ou le propriétaire a épuisé ses messages pour aujourd'hui |
| `500` | Le formulaire est mal configuré, ou le message n'a pas pu être créé |
