Referencia de la API v1

La API v1 es la interfaz que usa la app de Android para comunicarse con la consola: inicio de sesión, cuenta, análisis, informes y envío de traces. Se hizo para la app y sigue las mismas reglas que la consola en el navegador. Esta página resume el contrato; para enviar un trace por script, siga Enviar traces por la API.

Dirección y formato

• Base: https://app.waitscope.com/api/v1, solo por HTTPS. La dirección anterior, https://waitscope.io/api/v1, todavía responde, para la app configurada con ella.
• JSON en UTF-8 en los dos sentidos, salvo las descargas y los fragmentos de archivo del envío. Un campo desconocido en el cuerpo se rechaza con 400.
• Las rutas siguen las de la consola, en portugués: /analises, /envios, /conta.
• Instantes en RFC 3339 con zona horaria, como 2026-10-17T13:50:48-03:00. Tiempos del trace en microsegundos enteros, en los campos que terminan en _us, y tamaños en bytes. Formatear números y fechas para mostrarlos le corresponde al cliente.
• Sin CORS: la API no atiende una página de otro sitio abierta en el navegador.

Autenticación

El inicio de sesión tiene los dos pasos de la consola: la contraseña y después el código de la app de autenticación. Al final, la API devuelve un token de 43 caracteres, que va en toda llamada en el encabezado Authorization: Bearer <token>.

curl -s https://app.waitscope.com/api/v1/sessao \
  -H 'Content-Type: application/json' \
  -d '{"username": "zz-exemplo", "password": "...", "method": "app", "device_name": "zz-script"}'

La respuesta trae "etapa": "codigo" y un desafio, que vale 10 minutos. Envíe el desafío con el código de 6 dígitos de la app, o con un código de recuperación:

curl -s https://app.waitscope.com/api/v1/sessao/codigo \
  -H 'Content-Type: application/json' \
  -d '{"desafio": "...", "codigo": "123456"}'

La respuesta trae el token, la validez en expira_em y los datos de la cuenta, los mismos de GET /eu.

• El token vale hasta 90 días y caduca con 30 días sin uso. DELETE /sessao termina el token en el acto.
• Cuenta en el límite de sesiones simultáneas de la cuenta, junto con las del navegador, y aparece en Mi cuenta como “App Android · dispositivo”, con el device_name del inicio de sesión.
• La cookie de la consola no vale en la API, y el token no vale en la consola.
• method es app, el valor predeterminado, o email, este solo cuando la cuenta tiene el correo electrónico confirmado y el servidor envía correo. El rechazo trae los medios aceptados en metodos_disponiveis.
• La cuenta todavía sin verificación en dos pasos recibe "etapa": "cadastro" y un token que solo abre el registro, durante 30 minutos.
• Hasta que usted acepte en la consola la versión vigente de los Términos de Servicio y de la Política de Privacidad, toda ruta responde 403 termos_pendentes, salvo GET /eu y DELETE /sessao.

Idioma

Los mensajes, el diagnóstico, las tarjetas del informe y el catálogo de errores de Oracle vienen traducidos por el servidor. Con token, en el idioma de la cuenta, que PUT /conta/idioma cambia. Sin token, por el encabezado Accept-Language: pt, en o es, y cualquier otro pasa a pt.

Errores

El error viene con el estado HTTP y un cuerpo así:

{"erro": {"codigo": "nao_encontrado", "mensagem": "La dirección solicitada no existe."}}

El codigo es estable y sirve para que el programa decida qué hacer; el campo mensagem ya viene traducido, para mostrarlo al usuario. Algunos errores traen campos al lado de erro: bloqueado_ate, con el encabezado Retry-After, tentativas_restantes y metodos_disponiveis.

Las rutas de la cuenta y del registro usan también senha_atual_incorreta (401), senha_invalida, metodo_indisponivel, email_indisponivel, email_invalido y codigo_expirado (400).

Rutas

Todas las rutas piden el token, salvo GET /versao y las del inicio de sesión. La ruta con el id de un recurso de otra cuenta responde 404 nao_encontrado, sin confirmar que existe: ni el administrador ve los análisis de otra cuenta.

Versión

curl -s https://app.waitscope.com/api/v1/versao

Con la app publicada, la respuesta trae su versión; sin APK publicado, app viene nulo:

{"api":1,"app":{"bytes":...,"codigo":7,"download":"/api/v1/app/apk","minima":...,"pagina":"/app","sha256":"...","versao":"1.2.1"},"servidor":"1.6.0"}

Sesión

Cuenta

Las acciones sensibles (contraseña, app, correo electrónico y códigos de recuperación) piden la senha_atual, con el mismo bloqueo de la consola para quien se equivoca.

Análisis

Cada análisis trae id, name, status (queued, running, done o error), progress, size_bytes, las fechas, el response_time_us, el tipo de trace y el mensaje de error ya traducido. No hay descarga del trace ni reprocesamiento: el trace no se queda en el servidor.

curl -s "https://app.waitscope.com/api/v1/analises?limite=20" -H "Authorization: Bearer $TOKEN"

Informe

relatorio y relatorio.html aceptan ?top=N, de 1 a 300, o ?todos=1, como Sentencias por lista; sin ellos, 10. Mientras el análisis no termina, o si terminó con error, las rutas del informe responden 409 conflito. El SQL sale con la máscara de literales de la cuenta. Con una de las opciones de la máscara activada, el sql_id de las variantes (top_variants) viene vacío y el sql_ids de los textos compartibles viene []: el sql_id se calcula a partir del texto con los valores.

Envío

El envío se puede reanudar: el archivo va en fragmentos de hasta 8 MiB, uno por vez, y después de una caída de la red sigue desde donde se detuvo.

curl -s https://app.waitscope.com/api/v1/envios \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"juntar": false, "arquivos": [{"nome": "exemplo-10046.trc", "tamanho": 1845}]}'

curl -s -X PUT "https://app.waitscope.com/api/v1/envios/$ENVIO/arquivos/0" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Range: bytes 0-1844/1845" \
  --data-binary @exemplo-10046.trc

El ejemplo envía el trace sintético, de 1.845 bytes, en un solo fragmento; $ENVIO es el id devuelto por el POST /envios. Con "juntar": true, los archivos pasan a ser una colección, analizada como un solo trace. El envío pertenece al token que lo abrió y desaparece tras 24 horas sin un fragmento nuevo o cuando termina la sesión del token.

Límites

• Límite de solicitudes por dirección IP y bloqueo progresivo del inicio de sesión después de 5 errores de contraseña o de código. Quien supera el límite recibe 429.
• Los límites de la cuenta (tamaño por envío, análisis en cola y análisis guardados) vienen en GET /eu, en el campo limits. Si supera el tamaño: 413 grande_demais. Cola o análisis guardados en el límite: 429 limite.
• Un envío en curso por usuario, en fragmentos de hasta 8 MiB. El envío detenido desaparece en 24 horas.
• Hasta 200 análisis por página en la lista, hasta 200 ids en la eliminación en lote y hasta 500 elementos por consulta de cambios.
• Token por hasta 90 días, o 30 días sin uso; token de registro por 30 minutos; desafío del segundo paso por 10 minutos.

Adónde ir después

• Enviar traces por la API: el paso a paso del envío por script.
• Enviar traces con la app de Android: la app que usa esta API.
• Límites y envío repetido: los límites de tamaño y qué pasa con el archivo enviado de nuevo.
• Retención, eliminación y privacidad de los datos: qué se guarda y quién lo ve.