Conectar un proveedor

Un proveedor necesita un token de sincronización antes de poder decirle nada al servicio, y lo consigue como un televisor consigue una cuenta: muestra un código, una persona aprueba ese código en un sitio donde ya ha iniciado sesión, y el proveedor recoge su credencial. Nada se copia, se escribe ni se pega.

Esto sustituyó a mostrarle al dueño un token para pegarlo en un comando. La app ya no muestra a nadie un token de sincronización, así que el emparejamiento es la única manera de conseguir uno.

El flujo

1. El proveedor le pide al servicio un emparejamiento, y recibe un código, un enlace y un secreto de consulta (poll secret).
2. El proveedor abre el enlace en un navegador o, si no tiene pantalla, lo imprime junto con el código. El enlace funciona en cualquier dispositivo, así que el dueño puede abrirlo en su móvil.
3. En esa página el dueño inicia sesión, o crea una cuenta, le pone nombre a la biblioteca y aprueba. La página dice qué dispositivo lo solicita y muestra el código, para que el dueño pueda comprobar que la solicitud es suya.
4. El proveedor consulta con su secreto de consulta. La primera consulta tras la aprobación devuelve el token de sincronización, y ninguna posterior lo hará.

Iniciar

POST https://api.lets.dj/providers/pair/start
Content-Type: application/json

{ "deviceName": "Ryan’s MacBook" }

Esta ruta no requiere credencial, porque un proveedor que no se ha emparejado no tiene ninguna. El cuerpo es opcional. deviceName se muestra al dueño en la página de aprobación, junto al código, así que ponle algo que reconozca. Es la más débil de las dos comprobaciones — un nombre es como se llamó a sí misma esa máquina, mientras que el código es un valor que ambos extremos tienen por separado — pero es la que le dice cuál de sus ordenadores está pidiendo. Se recorta a 60 caracteres y los caracteres de control se sustituyen por espacios.

{
  "code": "K7QM-X4NP",
  "pollSecret": "…",
  "pairUrl": "https://app.lets.dj/pair?code=K7QM-X4NP",
  "expiresAt": 1790000000000,
  "pollIntervalSeconds": 2
}

• code son ocho caracteres de un alfabeto sin nada fácil de confundir con otra cosa (sin 0 ni O, sin 1 ni I ni L), mostrados como dos grupos de cuatro. La gente los lee en voz alta y los reescribe cuando un enlace no se abre. Es como la página del dueño encuentra el emparejamiento. No es con lo que tú te identificas.
• pollSecret es con lo que te identificas. Guárdalo para ti y úsalo solo para consultar.
• pairUrl es el enlace que hay que abrir. Úsalo tal cual, en lugar de construirlo.
• expiresAt son milisegundos desde la época (epoch).
• pollIntervalSeconds es cuánto esperar entre consultas.

Un 429 con "code": "too_many_pairings" y una cabecera Retry-After significa que el servicio tiene un tope de emparejamientos abiertos a la vez, que existe porque esta es la única ruta a la que puede llamar cualquiera. Espera y vuelve a pedirlo.

Cuánto dura

Un emparejamiento está abierto treinta minutos desde que se crea. Cada vez que el dueño llega a la página de aprobación con la sesión iniciada, el reloj se reinicia, pero nunca más allá de dos horas desde la creación. Una vez aprobado, hay otros treinta minutos para recoger el token.

La generosidad es deliberada y es para la persona para quien esto existe, que puede tener que crear una cuenta, esperar un correo de verificación y buscarlo en la carpeta de spam antes de poder aprobar nada. Diez minutos fue la primera cifra y habría fallado justo a esa persona.

Trata las cifras como el comportamiento actual del servicio y guíate por expiresAt, que devuelve la consulta y que se mueve. Cuando un emparejamiento caduca, pide uno nuevo y muestra el código nuevo. Un proveedor que lo haga puede dejarse funcionando mientras alguien se registra.

Consultar

POST https://api.lets.dj/providers/pair/poll
Authorization: Bearer <poll secret>

Esta es la única ruta donde el bearer no es un token de sincronización.

Mientras el dueño aún no ha aprobado:

{ "status": "pending", "expiresAt": 1790000000000 }

Tras la aprobación, una sola vez:

{
  "status": "approved",
  "syncToken": "…",
  "bridgeId": "0123456789abcdef",
  "hostname": "0123456789abcdef.letsdj.io",
  "label": "Karaoke at Ryan’s"
}

• syncToken se crea en el momento en que se construye esta respuesta. El servicio solo guarda un hash y no puede volver a decirlo. Guárdalo antes de hacer nada más que pueda fallar. Si se pierde, el único remedio es emparejar de nuevo, y emparejar de nuevo crea una biblioteca nueva; la antigua queda vacía para que el dueño la borre.
• bridgeId y hostname son el nombre de la biblioteca en el dominio del servicio, descrito en Un nombre y un certificado. Usa hostname tal cual.
• label es como llamó el dueño a la biblioteca.

Las respuestas llevan Cache-Control: no-store, porque un token que quedó en caché en algún punto del camino es un token que tiene otra persona.

Los fallos son todos 4xx con un code:

• 410 expired: el emparejamiento caducó. Inicia uno nuevo.
• 410 already_collected: el token ya se entregó, quizá a una consulta cuya respuesta no recibiste. Inicia uno nuevo.
• 403 unknown_pairing: el secreto de consulta no corresponde a ningún emparejamiento. Inicia uno nuevo.
• 401 missing_token: no había bearer.

Después de emparejar

La biblioteca ya existe y está vacía, y la página del dueño dice que está conectada. Queda lista cuando envías tu primer catálogo: véase Enviar un catálogo.

Un token de sincronización no caduca. Deja de funcionar cuando el dueño borra la biblioteca, y desde entonces todas las rutas responden 403, que es la señal descrita en Convenciones.

No compartas un token de sincronización entre dos programas. Cada sincronización reemplaza la dirección y el token de media que la biblioteca tiene registrados, así que el segundo le quitaría en silencio la biblioteca al primero.