SVOYAGER ID Photo API

Envía un encabezado Idempotency-Key (un valor único, por ejemplo, un UUID) para que una solicitud reintentada nunca se cobre o se procese dos veces. Es obligatorio en:

• POST /v1/photo-sessions
• POST /v1/photo-sessions/{id}/finalize

• • Misma clave + mismo cuerpo → se reproduce el resultado original (sin segundo cargo, sin segunda representación).
• • La misma clave + un cuerpo diferente → 409 idempotency_key_reuse.
• • Un error que admite reintentos te permite volver a intentarlo con la misma clave, el mismo cuerpo y el mismo `upload_ref`.
• • Las solicitudes de finalización simultáneas de una misma sesión nunca pueden crear ni cobrar dos pedidos.

Una sesión pasa por distintos estados de vista previa; un pedido, por distintos estados de finalización.

El entorno viene determinado por el prefijo de tu clave; los clientes nunca pueden modificarlo. El modo de prueba muestra la vista previa real con marca de agua para que puedas practicar el flujo real, pero emula el resultado final, por lo que no se utiliza la cuota en vivo ni el renderizado de producción.

Tu plan incluye un número determinado de vistas previas y versiones definitivas por periodo, que se cuentan por separado. Crear una sesión consume una vista previa; finalizarla consume una versión definitiva. La cuota se reserva de forma atómica antes del procesamiento.

• Cuando se agota la cuota de vista previa o la cuota final incluida, la solicitud devuelve el código 402 «quota_exceeded».
• El código 402 supone una interrupción definitiva: los reintentos no tendrán éxito hasta el siguiente periodo o hasta que se produzca un cambio de plan.
• Los límites de cuota de prueba y de producción son totalmente independientes.

Cada error utiliza un sobre. El request_id también aparece en el encabezado de respuesta X-Request-Id; inclúyelo en las solicitudes de asistencia.

{
  "error": {
    "type": "invalid_request_error",
    "code": "quota_exceeded",
    "message": "Your included final quota for this period is exhausted.",
    "request_id": "req_9wTv2c1Kd8QeR7"
  }
}

Errores estándar (todos los puntos finales)

Una vista previa puede devolver cero o más incidencias, cada una de ellas compuesta por un código estable y un mensaje. Muéstralas al usuario final para que pueda volver a hacer la foto. Una señal de origen no reconocida se degrada a «other».

• • Las vistas previas y las versiones definitivas solo se sirven desde URL autenticadas y alojadas por SVOYAGER. El acceso requiere tu clave API y el ámbito correcto; el almacenamiento subyacente nunca se expone públicamente.
• • Las imágenes subidas son privadas y están limitadas a tu cuenta y entorno; los destinos de subida son de corta duración y de un solo uso.
• • Las fotos de los documentos se procesan para generar el resultado y no se comparten entre cuentas.

Consulte las condiciones de SVOYAGER relativas al tratamiento, la conservación y la supresión de datos:Política de privacidad ·Acuerdo y condiciones para socios