Misi.Link

Documentación de la API

Envíe archivos desde sus propias herramientas (scripts, programas, servidores): cree una transferencia, suba los archivos por partes y obtenga el enlace.

Clave disponible con los planes Pro y Empresa, en Mi cuenta › API. Precios

Autenticación

Cree una clave en Mi cuenta › API y envíela en la cabecera Authorization de cada petición. Manténgala en secreto: da acceso a sus transferencias. Una clave eliminada deja de funcionar al instante.

Authorization: Bearer mlk_…

Si su herramienta o su alojamiento no transmite la cabecera Authorization, envíe la misma clave en la cabecera X-API-Key:

X-API-Key: mlk_…

120 peticiones por minuto y por clave. Tamaño, número de archivos y duración: los de su plan.

Enviar archivos en tres pasos

1. Crear la transferencia

Indique la lista de archivos (nombre y tamaño en bytes). Con «recipients», cada destinatario recibe un correo; sin destinatarios, obtiene un enlace para compartir. Opcional: «message», «password», «expire_days», «delete_after_download».

curl -X POST https://misi.link/api/v1/transfers \
  -H "Authorization: Bearer $MISILINK_KEY" -H "Content-Type: application/json" \
  -d '{"files": [{"name": "film.mov", "size": 5368709120}],
       "recipients": ["client@example.com"], "message": "…", "expire_days": 14}'
{"ok": true, "id": "aB3dE5fG", "token": "…", "url": "https://misi.link/aB3dE5fG",
 "files": [{"id": 101, "name": "film.mov", "size": 5368709120}], "chunk_size": 8388608}

2. Subir los archivos

Envíe cada archivo por partes de «chunk_size» bytes como máximo, en orden: «offset» es el número de bytes ya recibidos de ese archivo. Tras un corte, «status» indica dónde continuar (respuesta 409: continúe en «received»). Si su alojamiento o su cortafuegos filtra las direcciones, envíe la posición en la cabecera X-Upload-Offset en lugar de en la dirección.

curl -X POST "https://misi.link/api/upload/chunk?id=aB3dE5fG&token=…&file=101&offset=0" \
  -H "Content-Type: application/octet-stream" --data-binary @morceau-1.bin
# {"ok": true, "received": 8388608, "done": false}

curl "https://misi.link/api/upload/status?id=aB3dE5fG&token=…"

3. Terminar

Cuando se hayan recibido todos los archivos, termine: la transferencia se publica y se envían los correos. El enlace es el de la primera respuesta («url»). Este paso es obligatorio. Después, el servidor guarda los archivos: mientras tanto, «status» vale «finalizing». Una transferencia recibida por completo pero nunca terminada se termina automáticamente tras 30 minutos sin actividad.

curl -X POST https://misi.link/api/upload/complete -H "Content-Type: application/json" \
  -d '{"id": "aB3dE5fG", "token": "…"}'

Envío directo al almacenamiento (recomendado para archivos grandes)

Con «direct»: true, su programa envía el archivo directamente al almacenamiento de misi.link, sin pasar por el servidor: velocidad máxima y en línea en pocos segundos al final. Un archivo por transferencia (varios: júntelos en un archivo comprimido). Sin esta opción, o si la respuesta contiene «direct»: null, suba las partes con «chunk» como arriba.

  1. Cree la transferencia con «direct»: true. La respuesta indica «direct.part_size» (tamaño de cada parte, la última es más corta), «direct.parts» (número de partes) y «direct.sign».
  2. Pida las direcciones firmadas a «sign» (identificador, token y números de parte, 100 como máximo por llamada; válidas 6 horas) y envíe cada parte con un simple PUT a su dirección, sin cabecera de autenticación. Las partes pueden enviarse en paralelo y reenviarse si fallan.
  3. Termine con «complete». Si falta una parte, la respuesta es «incomplete» con la lista «missing»: reenvíe esas partes y vuelva a llamar a «complete». Cifrado de extremo a extremo: cada parte es una serie de segmentos cifrados completos, en orden (vea el ejemplo).
curl -X POST https://misi.link/api/v1/transfers -H "Authorization: Bearer $MISILINK_KEY" -H "Content-Type: application/json" \
  -d '{"files": [{"name": "film.mov", "size": 5368709120}], "direct": true}'
# {…, "direct": {"part_size": 16777216, "parts": 320, "total": 5368709120, "sign": "https://misi.link/api/upload/sign"}}

curl -X POST https://misi.link/api/upload/sign -H "Content-Type: application/json" \
  -d '{"id": "aB3dE5fG", "token": "…", "parts": [1, 2, 3]}'
# {"ok": true, "urls": {"1": "https://…", "2": "https://…", "3": "https://…"}}

curl -X PUT -H "Content-Type: application/octet-stream" --data-binary @part-1.bin "https://…"

curl -X POST https://misi.link/api/upload/complete -H "Content-Type: application/json" -d '{"id": "aB3dE5fG", "token": "…"}'
# {"ok": false, "error": "incomplete", "missing": [2]}

Cifrado de extremo a extremo (opcional)

Su programa cifra el archivo antes de enviarlo: misi.link solo recibe y guarda datos ilegibles. La clave nunca se envía al servidor: está en el enlace, después de «#». El destinatario descarga y descifra en su navegador, en la página habitual.

  1. Genere al azar una clave de 16 bytes y cree la transferencia con «e2e»: true y un solo archivo (su tamaño sin cifrar, en bytes). Para varios archivos, júntelos antes en un archivo comprimido.
  2. Clave de cifrado: HKDF-SHA-256 de la clave (sal «misilink-e2e-v1», info = identificador de la transferencia, 16 bytes), para AES-GCM.
  3. Divida el archivo en segmentos de 4 MiB (4 194 304 bytes). Segmento n.º i: nonce = 4 bytes nulos y luego i en 8 bytes (big-endian); datos asociados = i en 8 bytes y luego 1 byte (1 para el último segmento, si no 0). Cada segmento cifrado tiene 16 bytes más: suba estos bytes con «chunk», en orden («e2e.encrypted_size» en total), y termine con «complete».
  4. Recomendado: «e2e_verify» = HKDF-SHA-256 de la clave (misma sal, info «misilink-verify», 32 bytes) en base64url. misi.link rechaza entonces una descarga con una clave errónea, sin conocer nunca la correcta.
  5. Enlace para compartir: «url» + «#» + la clave en base64url (22 caracteres). Con destinatarios («recipients»), añada «e2e_key» (la clave): misi.link la guarda sellada para incluirla en los enlaces de los correos.
curl -X POST https://misi.link/api/v1/transfers \
  -H "Authorization: Bearer $MISILINK_KEY" -H "Content-Type: application/json" \
  -d '{"files": [{"name": "film.mov", "size": 5368709120}], "e2e": true, "e2e_verify": "…"}'
# {"ok": true, "id": "aB3dE5fG", …, "e2e": {"segment": 4194304, "tag": 16, "encrypted_size": 5368729600, "version": 1}}

Ejemplo completo en Python (biblioteca cryptography):

#!/usr/bin/env python3
# misi.link: end-to-end encrypted upload through the API (Python 3.8+, pip install cryptography)
# The file goes straight to the storage (signed URLs); if direct upload is unavailable, through "chunk".
# Usage: MISILINK_KEY=mlk_... python3 misilink_e2e.py file.mov [https://misi.link]
import base64, json, os, sys, urllib.request
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from cryptography.hazmat.primitives.hashes import SHA256
from cryptography.hazmat.primitives.kdf.hkdf import HKDF

SEG, SALT = 4 * 1024 * 1024, b'misilink-e2e-v1'
b64 = lambda b: base64.urlsafe_b64encode(b).rstrip(b'=').decode()
hkdf = lambda ikm, info, n: HKDF(SHA256(), n, SALT, info).derive(ikm)


def call(url, body=None, raw=None, headers=None, method=None, auth=True):
    h = dict(headers or {})
    if auth:
        h['Authorization'] = 'Bearer ' + os.environ['MISILINK_KEY']
    data = raw if raw is not None else (json.dumps(body).encode() if body is not None else None)
    if data is not None:
        h.setdefault('Content-Type', 'application/octet-stream' if raw is not None else 'application/json')
    req = urllib.request.Request(url, data=data, headers=h, method=method or ('POST' if data is not None else 'GET'))
    with urllib.request.urlopen(req, timeout=600) as r:
        body = r.read()
        return json.loads(body) if body[:1] == b'{' else {}


def segments(path, key, size):
    n = max(1, -(-size // SEG))
    with open(path, 'rb') as f:
        for i in range(n):
            last = i == n - 1
            nonce = bytes(4) + i.to_bytes(8, 'big')
            aad = i.to_bytes(8, 'big') + (b'\x01' if last else b'\x00')
            yield key.encrypt(nonce, f.read(SEG), aad)        # SEG bytes in, SEG + 16 bytes out


def send(path, base='https://misi.link'):
    size = os.path.getsize(path)
    secret = os.urandom(16)                                   # the key: never sent to the server
    verify = b64(hkdf(secret, b'misilink-verify', 32))       # lets the server recognise the right key
    t = call(base + '/api/v1/transfers', {'files': [{'name': os.path.basename(path), 'size': size}],
                                         'e2e': True, 'e2e_verify': verify, 'direct': True})
    key = AESGCM(hkdf(secret, t['id'].encode(), 16))
    auth = {'id': t['id'], 'token': t['token']}
    d = t.get('direct')
    if d:                                                     # straight to the storage: parts of d['part_size'] bytes
        part, n, urls = b'', 0, {}
        def put(n, data):
            if str(n) not in urls:
                urls.update(call(d['sign'], {**auth, 'parts': list(range(n, min(n + 100, d['parts'] + 1)))})['urls'])
            call(urls[str(n)], raw=data, method='PUT', auth=False)
        for seg in segments(path, key, size):
            part += seg
            if len(part) == d['part_size']:
                n += 1; put(n, part); part = b''
        if part:
            n += 1; put(n, part)
    else:                                                     # through the server
        sent = 0
        for seg in segments(path, key, size):
            r = call(t['upload']['chunk'] + '?id=' + t['id'] + '&token=' + t['token'] + '&file=' + str(t['files'][0]['id']),
                     raw=seg, headers={'X-Upload-Offset': str(sent)})
            sent = r['received']
    call(t['upload']['complete'], auth)
    return t['url'] + '#' + b64(secret)                      # the key travels after "#", only in the link


if __name__ == '__main__':
    print(send(sys.argv[1], *(sys.argv[2:3] or [])))

Otras peticiones

GET /api/v1/transfers
Sus transferencias, 50 por página (?page=2…).
GET /api/v1/transfers/{id}
Una transferencia: estado, enlace, archivos, número de descargas, fecha de caducidad.
DELETE /api/v1/transfers/{id}
Eliminar una transferencia (el enlace deja de funcionar).
GET /api/v1/me
Su cuenta, su plan y sus límites, tamaño de las partes.

Fechas en formato ISO 8601 (UTC), tamaños en bytes.

Respuestas y errores

Todas las respuestas son JSON, con «ok». En caso de error: «error» (código corto) y «message». Códigos HTTP: 401 clave ausente o no válida, 403 plan sin API, 404 no encontrado, 409 parte en el lugar equivocado, 422 petición rechazada, 429 demasiadas peticiones (espere un minuto).