Enviar traces por la API

La API v1 se hizo para la app de Android: con ella la app inicia sesión, envía los traces y lee los informes. No hay una clave de API aparte: un script inicia sesión como la app, con usuario, contraseña y el código del segundo paso, y usa el token que devuelve el inicio de sesión. Esta página muestra el camino del envío con curl; el contrato completo, con todos los campos y códigos de error, está en API v1.

Antes de empezar

• Una cuenta con la verificación en dos pasos por app de autenticación y los términos aceptados en el navegador. Antes de la aceptación, las llamadas responden 403 termos_pendentes.
• El inicio de sesión por la API cuenta en el límite de sesiones simultáneas de la cuenta, junto con el navegador y la app. Con el límite de una sesión, iniciar sesión desde el script cierra la sesión más antigua, como la del navegador.
• curl, jq y bash en Linux. Los ejemplos usan stat y dd de GNU.

Iniciar sesión y obtener el token

1. Envíe usuario y contraseña para recibir el desafío del segundo paso:

   BASE=https://app.waitscope.com/api/v1
   DESAFIO=$(curl -sS "$BASE/sessao" \
     -H 'Content-Type: application/json' \
     -d '{"username": "zz-exemplo", "password": "<contraseña>", "method": "app", "device_name": "script"}' |
     jq -r .desafio)

2. Cambie el desafío y el código de 6 dígitos de la app de autenticación por el token:

   TOKEN=$(curl -sS "$BASE/sessao/codigo" \
     -H 'Content-Type: application/json' \
     -d "{\"desafio\": \"$DESAFIO\", \"codigo\": \"123456\"}" |
     jq -r .token)

Resultado: TOKEN tiene 43 caracteres. Vale hasta 90 días, vence tras 30 días sin uso y aparece en Mi cuenta como App Android · script. El desafío vale 10 minutos.

Para cerrar la sesión al final:

curl -sS -X DELETE "$BASE/sessao" -H "Authorization: Bearer $TOKEN"

Enviar el archivo

1. Abra el envío con el nombre y el tamaño de cada archivo. Con "juntar": true, los archivos se convierten en un solo análisis (analizar juntos):

   ARQ=exemplo-10046.trc
   TAM=$(stat -c %s "$ARQ")
   ENVIO=$(curl -sS "$BASE/envios" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d "{\"juntar\": false, \"arquivos\": [{\"nome\": \"$ARQ\", \"tamanho\": $TAM}]}" |
     jq -r .id)

   Resultado: la respuesta 201 trae el id del envío, cada archivo con la posición n y lo que ya llegó en recebido, y pedaco_max, de 8388608 bytes (8 MiB).

2. Envíe el archivo en fragmentos de hasta 8 MiB, en orden, cada uno con el Content-Range de su fragmento y el tamaño total:

   PEDACO=8388608
   INI=0
   while [ "$INI" -lt "$TAM" ]; do
     FIM=$(( INI + PEDACO - 1 ))
     [ "$FIM" -ge "$TAM" ] && FIM=$(( TAM - 1 ))
     dd if="$ARQ" bs="$PEDACO" skip=$(( INI / PEDACO )) count=1 status=none |
       curl -fsS -X PUT "$BASE/envios/$ENVIO/arquivos/0" \
         -H "Authorization: Bearer $TOKEN" \
         -H 'Content-Type: application/octet-stream' \
         -H "Content-Range: bytes $INI-$FIM/$TAM" \
         --data-binary @- || break
     INI=$(( FIM + 1 ))
   done

   Resultado: cada fragmento aceptado responde 200 con el nuevo total en recebido.

3. Concluya el envío y guarde el id del análisis:

   ANALISE=$(curl -sS -X POST "$BASE/envios/$ENVIO/concluir" \
     -H "Authorization: Bearer $TOKEN" |
     jq -r '.analises[0].id // .repetidas[0]')

   Resultado: la respuesta 201 trae en analises los análisis nuevos y en repetidas los ids de los que ya existían con el mismo contenido (envío repetido).

Si un fragmento falla, el bucle se detiene. Pregunte al servidor cuánto ya llegó y ejecute de nuevo solo el while, que continúa desde ese punto:

INI=$(curl -sS "$BASE/envios/$ENVIO" -H "Authorization: Bearer $TOKEN" | jq '.arquivos[0].recebido')

Seguir el análisis

1. Consulte el estado cada pocos segundos:

   curl -sS "$BASE/analises/$ANALISE" -H "Authorization: Bearer $TOKEN" | jq '{status, progress, error}'

   Resultado: status pasa de queued a running, con el avance en progress, y termina en done o en error, con el motivo en error.

2. Con done, descargue el informe:

   curl -sS -o relatorio.html "$BASE/analises/$ANALISE/relatorio.html" -H "Authorization: Bearer $TOKEN"

relatorio.html es el mismo archivo de Descargar HTML en la consola. La ruta /relatorio, sin extensión, devuelve el informe en JSON, sección por sección. Antes del fin del análisis, o si terminó con error, las dos responden 409 conflito.

Cancelar y retomar

• DELETE $BASE/envios/$ENVIO cancela el envío y borra lo que llegó.
• El envío pertenece al token que lo creó y desaparece después de 24 horas sin un fragmento nuevo, o cuando termina la sesión del token.
• Repetir el concluir devuelve el mismo resultado, sin crear el análisis de nuevo: puede repetirlo si perdió la respuesta.

Problemas frecuentes

Próximos pasos

• Todos los campos, rutas y códigos de error: API v1.
• Los límites de cada cuenta: límites y envío repetido.
• El mismo envío con pantalla: enviar por el navegador.