Integracion mediante API

Claves de API

Genere y revoque claves de API desde su perfil de usuario (requiere Business plan). Las claves se muestran una sola vez al crearse; envielas en cada peticion dentro del encabezado X-API-Key.

Servicios disponibles

Las claves de API dan acceso a los mismos puntos finales utilizados por la aplicacion web. Esta guia documenta dos flujos: transformacion de coordenadas en /api/v1/axis y control de calidad en /api/v1/quality-analysis. Los limites del plan se aplican de forma identica.

Transformacion de coordenadas

Envie una peticion POST a /api/v1/axis/transform con el CRS de origen, destino, coordenadas y el encabezado X-API-Key. La respuesta reproduce los datos de Axis incluyendo la ruta de transformacion.

Flujo completo de control de calidad

1. Carga de archivos: POST a /api/v1/quality-analysis/upload como multipart/form-data (campo files, hasta 20 archivos por peticion) con el encabezado X-API-Key. La respuesta devuelve los registros correspondientes.
2. Creacion de la tarea: POST a /api/v1/quality-analysis/tasks con JSON {"config": {"tool": "<mode id>"}, "files": [<registros del paso anterior>]}. Identificadores de modo: "fast" para Fast Mode, "flash" para Flash Mode, "full" para Full Mode, "teqc" para TEQC Mode.
3. Consulta periodica: GET a /api/v1/quality-analysis/tasks/{taskId} hasta que el estado indique completed; la respuesta contendra el objeto completo de resultados.
4. Descarga del informe: obtenga el documento PDF mediante GET a /api/v1/quality-analysis/tasks/{taskId}/report.pdf.

Webhooks y notificaciones asincronas

En lugar de consultar periodicamente, configure un webhook para recibir avisos automaticos al finalizar un trabajo. Gestione webhooks en /api/v1/webhooks: POST para crear (cuerpo JSON con url, events y parametros opcionales secret y description), GET para listar, DELETE /api/v1/webhooks/{id} para eliminar y POST /api/v1/webhooks/{id}/test para enviar una prueba. La URL debe ser https publica; las direcciones IP privadas seran rechazadas.

Eventos y estructura del webhook

Actualmente se emiten tres eventos: "analysis.completed" al finalizar con exito un analisis de calidad o procesamiento, y "processing.completed" / "processing.failed" al concluir una conversion. Cada envio es un JSON POST con event, timestamp, un id unico y un objeto data con los detalles del trabajo. El evento se incluye tambien en el encabezado X-Webhook-Event.

Verificacion de firma y fiabilidad

Si define un secreto, cada envio incluira la firma HMAC-SHA256 del cuerpo sin procesar en el encabezado X-POSFLOW-Signature ("sha256=<hex>"; X-Webhook-Signature contiene la cadena hexadecimal). Calcule el hash y compruebe su coincidencia. Los envios fallidos se reintentan hasta 3 veces con retroceso progresivo; los webhooks que fallen 10 veces consecutivas se desactivaran automaticamente.

Buenas practicas de uso

Las peticiones estan sujetas a limites de frecuencia segun el plan contratado. Agrupe peticiones siempre que sea factible y aplique retroceso ante errores; para volumenes intensivos continuados, contacte con soporte para planificar recursos.