Saltar al contenido

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}/submit

Autenticació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ámetroTipoObligatorioDescripción
tidstring✅Identificador del formulario

Parámetros del cuerpo ​

ParámetroTipoObligatorioDescripción
valuesobject✅Respuestas indexadas por el id del campo
websitestring❌Campo trampa (honeypot). Déjalo fuera; cualquier valor no vacío se trata como bot

Valor por tipo de campo:

TipoValor
text, textarea, email, phone, number, urlString. El formato se valida para email, teléfono, número y URL
dateString, YYYY-MM-DD
dropdown, radioString, una de las options del campo
checkboxesArray de strings tomados de options
checkboxBoolean
ratingNúmero, 1–5
npsNúmero, 0–10
hiddenString, 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 ​

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())

Respuesta ​

Respuesta correcta ​

200 OK

json
{ "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.

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

Formulario cerrado ​

410 Gone

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

error contiene el closed_message que definió el propietario.

Límites ​

LímiteValor
Por IP10 envíos por minuto
Por formulario60 por minuto, 300 por hora
Cuota del propietarioCada 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 ​

EstadoDescripción
400Cuerpo no válido, o fields indica las respuestas que hay que corregir
403El formulario no acepta envíos desde este sitio; consulta orígenes permitidos
404Formulario no encontrado
410El formulario está cerrado
429Demasiados envíos, o el propietario se ha quedado sin mensajes por hoy
500El formulario está mal configurado, o no se pudo crear el mensaje

Documentación de Pocket Alert