Enviar formulario POST
Envía una respuesta. El envío se convierte en un mensaje en la cuenta del propietario y se entrega como notificación push a su teléfono: pasa por el mismo flujo que una llamada a un webhook. Sin autenticación.
Endpoint
POST https://api.pocketalert.app/v1/forms/{tid}/submitAutenticación
No requerida
Cualquiera que tenga el enlace puede enviar. El propietario controla quién puede hacerlo: consulta orígenes permitidos y los límites de abajo.
Solicitud
Parámetros de ruta
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
tid | string | ✅ | Identificador del formulario |
Parámetros del cuerpo
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
values | object | ✅ | Respuestas indexadas por el id del campo |
website | string | ❌ | Campo trampa (honeypot). Déjalo fuera; cualquier valor no vacío se trata como bot |
Valor por tipo de campo:
| Tipo | Valor |
|---|---|
text, textarea, email, phone, number, url | String. El formato se valida para email, teléfono, número y URL |
date | String, YYYY-MM-DD |
dropdown, radio | String, una de las options del campo |
checkboxes | Array de strings tomados de options |
checkbox | Boolean |
rating | Número, 1–5 |
nps | Número, 0–10 |
hidden | String, normalmente tomado de la URL de la página |
Los campos de diseño (heading, paragraph, divider) no admiten valor, y las claves desconocidas se ignoran. El cuerpo tiene un límite de 64 KB.
Ejemplo de solicitud
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"
}
}'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);
}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())Respuesta
Respuesta correcta
200 OK
{ "status": "ok" }El propietario recibe una notificación push creada a partir de las respuestas. No se muestra al visitante nada sobre el propietario: ni su plan, ni sus dispositivos, ni su cuota.
Errores de validación
400 Bad Request
fields asigna el id de un campo al motivo por el que se rechazó, que es lo que la página del formulario muestra debajo de cada campo.
{
"error": "Please check the highlighted fields.",
"fields": {
"email": "Enter a valid email address",
"name": "This field is required"
}
}Formulario cerrado
410 Gone
{
"error": "This form is no longer accepting responses.",
"closed": true
}error contiene el closed_message que definió el propietario.
Límites
| Límite | Valor |
|---|---|
| Por IP | 10 envíos por minuto |
| Por formulario | 60 por minuto, 300 por hora |
| Cuota del propietario | Cada envío usa un mensaje de su límite diario |
Un envío que superaría el límite diario de mensajes del propietario recibe un 429 neutro con una cabecera Retry-After y sin mencionar el plan.
Respuestas de error
| Estado | Descripción |
|---|---|
400 | Cuerpo no válido, o fields indica las respuestas que hay que corregir |
403 | El formulario no acepta envíos desde este sitio; consulta orígenes permitidos |
404 | Formulario no encontrado |
410 | El formulario está cerrado |
429 | Demasiados envíos, o el propietario se ha quedado sin mensajes por hoy |
500 | El formulario está mal configurado, o no se pudo crear el mensaje |