Docs/Long Polling

Long Polling

Utilice long polling cuando su servidor no pueda recibir solicitudes de webhook entrantes — por ejemplo, durante el desarrollo local o cuando esté detrás de un firewall restrictivo.

Cuándo usar long polling

✓

Servidor detrás de un firewall o NAT (sin URL pública)

✓

Hosting compartido que bloquea webhooks entrantes

✓

Hosting con límites restrictivos de tamaño de subida (ya que usted descarga las imágenes, no las recibe)

✓

Desarrollo local sin túneles (ngrok, etc.)

✓

Entornos serverless con tiempos de ejecución cortos

✓

Cuando necesita procesar imágenes a su propio ritmo

Nota para producción

Para uso en producción, se recomiendan los webhooks. Long polling requiere que su servidor mantenga un bucle de consulta continuo y confirme cada imagen individualmente.

Endpoints

GET/api/v1/sessions/:id/poll

Realiza long polling para la siguiente imagen no confirmada. El servidor mantiene la conexión abierta durante un máximo de 30 segundos. Si una imagen está disponible, se devuelve inmediatamente. Si no llega ninguna imagen en 30 segundos, el servidor devuelve una respuesta 204 No Content.

Parámetros de consulta

ParámetroTipoDescripción
timeoutintegerMáximo de segundos de espera. Predeterminado 30, máximo 30.
GET/api/v1/images/:imageId/download

Descarga los bytes sin procesar de la imagen. Devuelve la imagen con el Content-Type correspondiente.

POST/api/v1/images/:imageId/ack

Confirma que su servidor ha recibido y procesado la imagen exitosamente. Las imágenes no confirmadas se devolverán nuevamente en la siguiente solicitud de poll. Debe llamarse dentro de los 5 minutos posteriores a la recepción de la imagen.

Ejemplo de bucle de polling

# Single poll request (returns 200 with image info, 204 if nothing, 410 if done)
curl -H "Authorization: Bearer aptr_xxxx" \
  "https://api.apertur.ca/v1/sessions/sess_01HX.../poll?timeout=30"

# Download an image
curl -H "Authorization: Bearer aptr_xxxx" \
  -o photo.jpg \
  "https://api.apertur.ca/v1/images/img_01HX.../download"

# Acknowledge an image
curl -X POST -H "Authorization: Bearer aptr_xxxx" \
  "https://api.apertur.ca/v1/images/img_01HX.../ack"

Formato de respuesta de poll

{
  "image_id": "img_01HX...",
  "image_index": 0,
  "filename": "photo.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 245000,
  "session_status": "uploading",
  "tags": {
    "user_id": "usr_abc123"
  }
}

Descargue los bytes de la imagen utilizando GET /api/v1/images/:imageId/download.

← WebhooksSiguiente: Errores →