Introducción
Todo lo que necesita para integrar la API de Piloterr en su aplicación.
Comience con la API de Piloterr en minutos. Realice solicitudes HTTP a nuestros endpoints y reciba respuestas JSON estructuradas.
Inicio rápido
Obtenga su clave API
Regístrese en su panel de control y copie su clave API desde la página Configuración.
Realice su primera solicitud
Incluya su clave en el encabezado x-api-key y llame a cualquier endpoint:
curl "https://api.piloterr.com/v2/usage" \
-H "x-api-key: YOUR_API_KEY"Gestione la respuesta
Cada solicitud exitosa devuelve un objeto JSON con datos estructurados. Consulte las páginas individuales de los endpoints para ver esquemas de respuesta y ejemplos.
Autenticación
Todas las solicitudes API deben incluir un encabezado x-api-key. Puede encontrar su clave en su panel de control > claves API.
curl -H "x-api-key: xxxx" https://api.piloterr.com/v2/usageMantenga su clave API en secreto. No la exponga en código del lado del cliente ni en repositorios públicos.
Códigos de estado
Las llamadas síncronas se facturan con el 200. Las llamadas asíncronas (is_async=true) devuelven un 202 (no facturado) y se facturan cuando el trabajo termina con éxito — registrado como 201 en sus registros de solicitudes. El sondeo GET /v1/jobs/{job_id} es siempre gratuito. Los trabajos fallidos (500) nunca se facturan. La facturación del 404 varía según el endpoint (consulte la página de cada endpoint). Todas las demás respuestas 4xx/5xx son gratuitas. Si el cliente cierra el socket antes de enviar una respuesta síncrona, la llamada se sigue facturando cuando el resultado es un estado facturable. Un 401 de límite de tasa es una respuesta JSON normal: el servidor no corta el socket.
| Código | Facturado | Estado | Acción |
|---|---|---|---|
200 | Sí | Llamada API exitosa (síncrona) | No se requiere ninguna acción. |
201 | Sí | Trabajo asíncrono completado | Aparece en sus registros de solicitudes cuando un trabajo asíncrono termina con éxito — es en ese momento cuando se factura. Nunca se devuelve como respuesta HTTP. |
202 | No | Aceptado (asíncrono) | El trabajo fue aceptado y puesto en cola. Consulte GET /v1/jobs/{job_id} para obtener el resultado — el sondeo es siempre gratuito. |
400 | No | Solicitud incorrecta | Verifique sus parámetros y sus tipos. Consulte la documentación para más información. |
401 | No | Clave API inválida | Verifique su clave API (encabezado x-api-key o cadena de consulta x_api_key). |
401 | No | Clave API inactiva | Active su clave API en la sección Claves API de la configuración de su cuenta. |
401 | No | Clave API expirada | Actualice su clave API o genere una nueva. |
401 | No | Rate limit exceeded | El servidor devuelve este 401 con un cuerpo JSON y no corta el socket. Espere y reintente. Mejore su plan o aumente las cuotas por clave si esto ocurre con frecuencia. |
402 | No | Payment required | Recargue créditos, mejore su plan, active la Recarga automática o liquide las facturas pendientes. |
403 | No | Prohibido | Verifique sus permisos. Para API Stats, un HTTP 403 significa que el endpoint no está habilitado en su cuenta: contacte al soporte para activarlo. |
404 | Según el caso | No encontrado | La facturación es específica de cada endpoint. Consulte la página del endpoint correspondiente. |
413 | No | Carga demasiado grande | El archivo subido o el cuerpo de la solicitud supera el límite de tamaño. Consulte la documentación para los tamaños máximos. |
500 | No | Error interno | Reintente la acción o contacte a nuestro equipo de soporte. |
Consulte la página de Créditos para un desglose completo por endpoint, Stats para la salud de infraestructura, Claves API para la gestión de claves, y Buenas prácticas y Gestión de errores para orientación de integración. ¿Nuevo en la plataforma? El Glosario define todos los términos clave.
Endpoints
Consulta cada endpoint en la Referencia de la API, o abre uno directamente: