drop / API v1
Sommaire

Démarrage

Documentation de l'API

L'API drop permet à une application partenaire, comme voxar, de confier ses pièces jointes et ses partages de fichiers à drop : jusqu'à 2 Go par envoi, avec lien de partage, date d'expiration et mot de passe facultatif.

Les fichiers ne transitent jamais par le serveur partenaire. Celui-ci crée un transfert avec son jeton d'API ; le navigateur de l'utilisateur envoie ensuite les fichiers directement à drop, en morceaux, avec un jeton d'envoi à usage unique.

Conventions

  • Requêtes et réponses en JSON, encodé en UTF-8. Envoyez toujours Accept: application/json.
  • Les dates suivent la norme ISO 8601 (2026-12-17T14:02:11+00:00).
  • Les tailles sont exprimées en octets ; les identifiants sont des UUID.
  • Les champs absents d'une requête prennent leur valeur par défaut ; un champ sans valeur vaut null.
URL de base
https://drop.voxar.chat/api/v1

Démarrage

Démarrage rapide

Une pièce jointe passe par trois étapes, réparties entre le serveur partenaire et le navigateur.

  1. Le serveur crée un transfert avec POST /transfers. Il reçoit le lien de partage et un bloc upload.
  2. Le navigateur envoie les fichiers grâce au bloc upload : il déclare chaque fichier, l'envoie en morceaux, puis finalise le transfert.
  3. Le serveur publie le lien dans le message, et peut récupérer à tout moment les noms, tailles et liens des fichiers.

Pour démarrer, demandez un jeton d'API à l'administrateur de drop (voir Mise en place), puis suivez le guide d'intégration.

# Le serveur partenaire crée le transfert avec son jeton d'API.
curl https://drop.voxar.chat/api/v1/transfers \
  -H "Authorization: Bearer $DROP_API_TOKEN" \
  -H "Accept: application/json" \
  -d title="Compte rendu"

# Il renvoie au navigateur le bloc « upload » de la réponse.

Démarrage

Authentification

L'API utilise deux jetons, chacun limité à son rôle.

JetonUtilisé parEn-tête
Jeton d'APIServeur partenaireAuthorization: Bearer …
Jeton d'envoiNavigateurX-Upload-Token: …

Jeton d'API

Il est rattaché à un compte drop : les transferts créés avec lui appartiennent à ce compte, qui est le seul à pouvoir les consulter et les supprimer. Il n'expire pas et reste valable jusqu'à sa révocation.

Jeton d'envoi

Il est renvoyé à la création d'un transfert, dans upload.token. Il donne accès aux seules routes d'envoi de ce transfert et il est détruit à la finalisation, ou au bout de 24 heures si l'envoi n'est jamais terminé.

Le jeton d'API ne quitte jamais le serveur

Ne l'envoyez pas au navigateur, ne l'enregistrez pas dans les journaux. Seul le bloc upload est destiné au navigateur.
Requête authentifiée
curl https://drop.voxar.chat/api/v1/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77 \
  -H "Authorization: Bearer 3|q8ZrT4vKx2…" \
  -H "Accept: application/json"

Démarrage

Erreurs

Les codes HTTP indiquent le résultat : 2xx pour un succès, 4xx pour une requête à corriger, 5xx pour un incident côté drop. Le corps contient toujours un message lisible et, pour une erreur de validation, le détail par champ dans errors.

CodeSignificationQue faire
401 Jeton d'API absent, invalide ou révoqué. Vérifier l'en-tête Authorization.
403 Transfert d'un autre compte, jeton d'envoi invalide ou transfert déjà finalisé. Ne pas réessayer.
404 Transfert ou fichier inexistant ou déjà supprimé. Considérer la pièce jointe comme supprimée.
409 Fichier déjà entièrement envoyé. Passer à l'étape suivante.
413 Morceau plus gros que part_size. Découper le fichier selon part_size.
422 Paramètre invalide, limite dépassée, morceaux manquants ou corrompus. Lire errors et corriger.
429 Trop de requêtes. Attendre la durée de Retry-After.
5xx Incident côté drop. Réessayer avec un délai croissant.
Réponse
{
  "message": "Le champ expires in days ne doit pas dépasser 90.",
  "errors": {
    "expires_in_days": [
      "Le champ expires in days ne doit pas dépasser 90."
    ]
  }
}

Démarrage

Limites

Ces limites protègent le service. Au-delà d'un quota de requêtes, l'API répond 429 avec l'en-tête Retry-After (en secondes).

Taille d'un transfert 2 Go
Fichiers par transfert 500
Taille d'un morceau 16 Mo
Durée de validité 1 à 90 jours (défaut : 7)
Délai pour finaliser un envoi 24 heures
Validité d'une URL de morceau 60 minutes
Requêtes avec le jeton d'API 120 par minute et par compte
Requêtes d'envoi 600 par minute et par adresse IP
Quota dépassé
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 37

Transferts

L'objet Transfert

Un transfert regroupe un ou plusieurs fichiers derrière un lien de partage. Il naît en brouillon, devient partageable une fois les fichiers envoyés et finalisés, puis il est supprimé automatiquement à sa date d'expiration.

Attributs

  • id string

    Identifiant unique du transfert (UUID).

  • status enum

    draft : envoi en cours, lien inactif. ready : finalisé et partageable. removed : retiré par la modération.

  • url string

    Page de téléchargement à publier dans le message. Elle gère le mot de passe, l'expiration et la limite de téléchargements.

  • archive_url string

    Téléchargement de tous les fichiers en une archive zip.

  • title string | null

    Titre affiché au destinataire.

  • message string | null

    Message affiché au destinataire.

  • is_protected boolean

    true si un mot de passe est demandé avant le téléchargement.

  • max_downloads integer | null

    Nombre maximal de visiteurs autorisés à télécharger. null : illimité.

  • download_count integer

    Nombre de visiteurs ayant déjà téléchargé. Un visiteur est compté une fois par session de navigateur.

  • expires_at string

    Date d'expiration (ISO 8601). Le transfert et ses fichiers sont supprimés dans l'heure qui suit.

  • created_at string

    Date de création (ISO 8601).

  • files_count integer

    Nombre de fichiers.

  • total_size integer

    Taille totale des fichiers, en octets.

  • files array

    Fichiers du transfert, triés par nom.

    Afficher les attributs enfants
    • id string

      Identifiant unique du fichier (UUID).

    • name string

      Nom du fichier, avec son dossier éventuel : photos/plan.png.

    • size integer

      Taille en octets.

    • mime string | null

      Type MIME déclaré à l'envoi.

    • status enum

      uploading ou ready.

    • download_url string

      Téléchargement direct de ce fichier.

    • preview_url string | null

      URL temporaire qui affiche le fichier dans le navigateur, à placer dans <img>, <video>, <audio> ou <iframe>. Valable 60 minutes : récupérez le transfert à nouveau pour en obtenir une neuve. Un aperçu ne compte pas comme un téléchargement et ne demande pas le mot de passe : ne l'affichez qu'aux personnes autorisées à voir la pièce jointe. null si le type n'est pas affichable (seuls les images JPEG, PNG, GIF, WebP et AVIF, les PDF, la vidéo, l'audio et le texte brut le sont), si le fichier est encore en cours d'envoi ou si le transfert n'est pas partageable.

L'objet Transfert
{
  "id": "019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77",
  "status": "ready",
  "url": "https://drop.voxar.chat/t/k3x9q2m7pa",
  "archive_url": "https://drop.voxar.chat/t/k3x9q2m7pa/zip",
  "title": "Compte rendu",
  "message": null,
  "is_protected": false,
  "max_downloads": null,
  "download_count": 4,
  "expires_at": "2026-12-17T14:02:11+00:00",
  "created_at": "2026-11-17T14:02:11+00:00",
  "files_count": 2,
  "total_size": 48263904,
  "files": [
    {
      "id": "019a8c2f-0d4e-7a11-8b6c-5e3f9a2d7c10",
      "name": "photos/plan.png",
      "size": 50495,
      "mime": "image/png",
      "status": "ready",
      "download_url": "https://drop.voxar.chat/t/k3x9q2m7pa/files/019a8c2f-0d4e-7a11-8b6c-5e3f9a2d7c10",
      "preview_url": "https://drop.voxar.chat/api/previews/019a8c2f-2c4b-7d31-a1e5-9f0c3b7d4e21?expires=1763391731&name=plan.png&signature=4f1c…"
    },
    {
      "id": "019a8c2f-1b7a-7f02-9c3d-8e4b1a6f2d99",
      "name": "rapport.pdf",
      "size": 48213409,
      "mime": "application/pdf",
      "status": "ready",
      "download_url": "https://drop.voxar.chat/t/k3x9q2m7pa/files/019a8c2f-1b7a-7f02-9c3d-8e4b1a6f2d99",
      "preview_url": "https://drop.voxar.chat/api/previews/019a8c2f-3e8d-7a04-b2f6-0c1d4e8f5a32?expires=1763391731&name=rapport.pdf&signature=9b2e…"
    }
  ]
}

Transferts

Créer un transfert

POST /v1/transfers

Crée un transfert en brouillon, appartenant au compte du jeton d'API. La réponse contient le transfert dans data et, dans upload, tout ce dont le navigateur a besoin pour envoyer les fichiers.

Paramètres

  • title string facultatif

    Titre affiché au destinataire. 120 caractères au plus.

  • message string facultatif

    Message affiché au destinataire. 2 000 caractères au plus.

  • password string facultatif

    Mot de passe demandé avant le téléchargement, de 4 à 128 caractères. Il n'est jamais renvoyé par l'API.

  • expires_in_days integer facultatif

    Durée de validité, de 1 à 90 jours, comptée à partir de la création.

    Défaut : 7

  • max_downloads integer facultatif

    Nombre maximal de visiteurs autorisés à télécharger, de 1 à 10 000. Sans valeur : illimité.

Retour

  • data Transfert

    Le transfert créé, au statut draft. Son url ne sera active qu'après la finalisation.

  • upload object

    À transmettre tel quel au navigateur. Ne contient pas le jeton d'API.

    Afficher les attributs enfants
    • token string

      Jeton d'envoi, à placer dans l'en-tête indiqué par header.

    • header string

      Nom de l'en-tête : X-Upload-Token.

    • expires_at string

      Limite pour finaliser l'envoi. Passé ce délai, le brouillon est supprimé.

    • endpoints object

      URL de files, parts, complete, destroy et finalize. __FILE__ y est à remplacer par l'identifiant du fichier.

Requête
curl https://drop.voxar.chat/api/v1/transfers \
  -H "Authorization: Bearer $DROP_API_TOKEN" \
  -H "Accept: application/json" \
  -d title="Compte rendu" \
  -d expires_in_days=30
Réponse
{
  "data": {
    "id": "019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77",
    "status": "draft",
    "url": "https://drop.voxar.chat/t/k3x9q2m7pa",
    "archive_url": "https://drop.voxar.chat/t/k3x9q2m7pa/zip",
    "title": "Compte rendu",
    "message": null,
    "is_protected": false,
    "max_downloads": null,
    "download_count": 0,
    "expires_at": "2026-12-17T14:02:11+00:00",
    "created_at": "2026-11-17T14:02:11+00:00",
    "files_count": 0,
    "total_size": 0,
    "files": []
  },
  "upload": {
    "token": "Vb4tqLw0Zr8n…",
    "header": "X-Upload-Token",
    "expires_at": "2026-11-18T14:02:11+00:00",
    "endpoints": {
      "files": "https://drop.voxar.chat/api/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77/files",
      "parts": "https://drop.voxar.chat/api/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77/files/__FILE__/parts",
      "complete": "https://drop.voxar.chat/api/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77/files/__FILE__/complete",
      "destroy": "https://drop.voxar.chat/api/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77/files/__FILE__",
      "finalize": "https://drop.voxar.chat/api/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77/finalize"
    }
  }
}

Transferts

Récupérer un transfert

GET /v1/transfers/{id}

Renvoie un transfert du compte avec la liste de ses fichiers. Utile pour afficher une pièce jointe (noms, tailles, liens) ou vérifier qu'un envoi est terminé.

Un transfert expiré reste lisible jusqu'à sa suppression, qui a lieu dans l'heure. Il répond ensuite 404.

Paramètres

  • id string requis

    Identifiant du transfert, dans l'URL.

Retour

Requête
curl https://drop.voxar.chat/api/v1/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77 \
  -H "Authorization: Bearer $DROP_API_TOKEN" \
  -H "Accept: application/json"
Réponse
{
  "data": {
    "id": "019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77",
    "status": "ready",
    "url": "https://drop.voxar.chat/t/k3x9q2m7pa",
    "archive_url": "https://drop.voxar.chat/t/k3x9q2m7pa/zip",
    "title": "Compte rendu",
    "message": null,
    "is_protected": false,
    "max_downloads": null,
    "download_count": 4,
    "expires_at": "2026-12-17T14:02:11+00:00",
    "created_at": "2026-11-17T14:02:11+00:00",
    "files_count": 2,
    "total_size": 48263904,
    "files": [
      {
        "id": "019a8c2f-0d4e-7a11-8b6c-5e3f9a2d7c10",
        "name": "photos/plan.png",
        "size": 50495,
        "mime": "image/png",
        "status": "ready",
        "download_url": "https://drop.voxar.chat/t/k3x9q2m7pa/files/019a8c2f-0d4e-7a11-8b6c-5e3f9a2d7c10",
        "preview_url": "https://drop.voxar.chat/api/previews/019a8c2f-2c4b-7d31-a1e5-9f0c3b7d4e21?expires=1763391731&name=plan.png&signature=4f1c…"
      },
      {
        "id": "019a8c2f-1b7a-7f02-9c3d-8e4b1a6f2d99",
        "name": "rapport.pdf",
        "size": 48213409,
        "mime": "application/pdf",
        "status": "ready",
        "download_url": "https://drop.voxar.chat/t/k3x9q2m7pa/files/019a8c2f-1b7a-7f02-9c3d-8e4b1a6f2d99",
        "preview_url": "https://drop.voxar.chat/api/previews/019a8c2f-3e8d-7a04-b2f6-0c1d4e8f5a32?expires=1763391731&name=rapport.pdf&signature=9b2e…"
      }
    ]
  }
}

Transferts

Supprimer un transfert

DELETE /v1/transfers/{id}

Supprime définitivement le transfert, ses fichiers et leur contenu. Les liens de partage cessent aussitôt de fonctionner. À appeler quand le message qui portait la pièce jointe est supprimé.

Paramètres

  • id string requis

    Identifiant du transfert, dans l'URL.

Retour

  • 204 No Content

    Réponse vide en cas de succès.

Requête
curl -X DELETE https://drop.voxar.chat/api/v1/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77 \
  -H "Authorization: Bearer $DROP_API_TOKEN" \
  -H "Accept: application/json"
Réponse
HTTP/1.1 204 No Content

Envoi des fichiers

Envoi des fichiers

Le navigateur envoie les fichiers directement à drop, découpés en morceaux de 16 Mo. Un gros fichier part ainsi en parallèle, et un morceau en échec se renvoie seul, sans tout recommencer.

Pour chaque fichier, le navigateur le déclare, obtient les URL de ses morceaux, envoie chacun d'eux puis valide le fichier. Une fois tous les fichiers validés, il finalise le transfert.

Toutes ces routes s'appellent avec l'en-tête X-Upload-Token, sauf l'envoi des morceaux, dont l'URL signée suffit. Elles acceptent les appels venant d'un autre domaine (CORS), dans la limite des origines autorisées par l'administrateur.

Le guide d'intégration fait tout cela pour vous

La fonction uploadToDrop() enchaîne ces étapes, envoie plusieurs morceaux en parallèle et réessaie en cas d'erreur réseau.
Déroulé
Serveur partenaire                 drop
  │  POST /v1/transfers ─────────────▶│
  │◀──────────── data + upload ───────│
  │
Navigateur
  │  POST  endpoints.files ──────────▶│  pour chaque fichier
  │  GET   endpoints.parts ──────────▶│
  │  PUT   url de chaque morceau ────▶│  en parallèle
  │  POST  endpoints.complete ───────▶│
  │
  │  POST  endpoints.finalize ───────▶│  une fois tous les fichiers validés
  │◀──────────────── url ─────────────│

Envoi des fichiers

Déclarer un fichier

POST upload.endpoints.files

Enregistre un fichier dans le transfert et indique comment le découper. Un transfert accepte au plus 500 fichiers et 2 Go au total : au-delà, la requête répond 422.

Paramètres

  • name string requis

    Nom du fichier. Un chemin relatif est accepté pour conserver un dossier (photos/plan.png) ; les segments dangereux comme .. sont retirés. 255 caractères au plus après nettoyage.

  • size integer requis

    Taille exacte en octets. Elle est vérifiée à la validation du fichier.

  • mime string facultatif

    Type MIME, transmis au destinataire lors du téléchargement.

Retour

  • id string

    Identifiant du fichier, à placer à la place de __FILE__ dans les URL suivantes.

  • part_size integer

    Taille d'un morceau, en octets. Seul le dernier morceau peut être plus petit.

  • part_count integer

    Nombre de morceaux à envoyer (au moins 1, même pour un fichier vide).

  • status enum

    uploading. Si la valeur est ready, le contenu est déjà connu : passez directement au fichier suivant.

Requête
const file = input.files[0];

const remote = await fetch(upload.endpoints.files, {
  method: 'POST',
  headers: {
    [upload.header]: upload.token,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: file.name, size: file.size, mime: file.type || null }),
}).then((response) => response.json());
Réponse
{
  "id": "019a8c2f-1b7a-7f02-9c3d-8e4b1a6f2d99",
  "part_size": 16777216,
  "part_count": 3,
  "status": "uploading"
}

Envoi des fichiers

Obtenir les URL des morceaux

GET upload.endpoints.parts

Renvoie une URL d'envoi signée par morceau. Demandez-les par lots, et redemandez celles d'un morceau dont l'URL a expiré (réponse 403 à l'envoi).

Selon le stockage configuré, ces URL pointent vers drop ou directement vers le stockage objet (S3 ou compatible). Traitez-les comme opaques.

Paramètres

  • start integer facultatif

    Numéro du premier morceau demandé.

    Défaut : 1

  • count integer facultatif

    Nombre d'URL demandées, 100 au plus.

    Défaut : 20

Retour

  • parts array

    Une entrée par morceau, avec son number et son url d'envoi, valable 60 minutes.

Requête
const partsUrl = upload.endpoints.parts.replace('__FILE__', remote.id);

const { parts } = await fetch(`${partsUrl}?start=1&count=100`, {
  headers: { [upload.header]: upload.token, Accept: 'application/json' },
}).then((response) => response.json());
Réponse
{
  "parts": [
    { "number": 1, "url": "https://drop.voxar.chat/api/uploads/019a8c30-…/parts/1?expires=1795010531&signature=8f3c…" },
    { "number": 2, "url": "https://drop.voxar.chat/api/uploads/019a8c30-…/parts/2?expires=1795010531&signature=c41a…" },
    { "number": 3, "url": "https://drop.voxar.chat/api/uploads/019a8c30-…/parts/3?expires=1795010531&signature=07be…" }
  ]
}

Envoi des fichiers

Envoyer un morceau

PUT parts[].url

Le corps de la requête est le contenu brut du morceau n : les octets de (n − 1) × part_size à n × part_size du fichier. Aucun en-tête d'authentification n'est nécessaire.

Conservez la valeur de l'en-tête ETag de la réponse : elle sert à valider le fichier. Les morceaux peuvent être envoyés dans n'importe quel ordre et en parallèle ; quatre à six envois simultanés donnent un bon débit.

Réessayer, mais pas à l'infini

Une erreur réseau ou 5xx justifie un nouvel essai avec un délai croissant. Un 403 signale une URL expirée : redemandez-la. Un 413 signale un morceau trop gros.
Requête
const chunk = file.slice(
  (part.number - 1) * remote.part_size,
  part.number * remote.part_size,
);

const response = await fetch(part.url, { method: 'PUT', body: chunk });
const etag = response.headers.get('ETag');
Réponse
HTTP/1.1 200 OK
ETag: "9b2c0f4e8d1a7b3c5e6f8a9b0c1d2e3f"

Envoi des fichiers

Valider un fichier

POST upload.endpoints.complete

Assemble les morceaux après avoir vérifié qu'il n'en manque aucun, qu'aucun n'est corrompu et que la taille totale correspond à celle déclarée. En cas d'écart, la requête répond 422 et le fichier reste à compléter.

Paramètres

  • parts array requis

    Tous les morceaux du fichier, de 1 à part_count, dans n'importe quel ordre.

    Afficher les attributs enfants
    • number integer requis

      Numéro du morceau.

    • etag string requis

      Valeur de l'en-tête ETag reçue à l'envoi du morceau, guillemets compris.

Retour

  • id string

    Identifiant du fichier.

  • status enum

    ready : le fichier est complet.

Requête
await fetch(upload.endpoints.complete.replace('__FILE__', remote.id), {
  method: 'POST',
  headers: {
    [upload.header]: upload.token,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    parts: [
      { number: 1, etag: '"9b2c0f4e8d1a7b3c5e6f8a9b0c1d2e3f"' },
      { number: 2, etag: '"41fe7a0c9d3b2e18f6a4c5d7e8b9a0f1"' },
      { number: 3, etag: '"d07be3a1c2f4e5b6a7d8c9e0f1a2b3c4"' },
    ],
  }),
});
Réponse
{
  "id": "019a8c2f-1b7a-7f02-9c3d-8e4b1a6f2d99",
  "status": "ready"
}

Envoi des fichiers

Retirer un fichier

DELETE upload.endpoints.destroy

Retire un fichier du transfert avant la finalisation, par exemple quand l'utilisateur l'enlève de son message. Les morceaux déjà envoyés sont supprimés. Réponse 204 sans contenu.

Requête
await fetch(upload.endpoints.destroy.replace('__FILE__', remote.id), {
  method: 'DELETE',
  headers: { [upload.header]: upload.token, Accept: 'application/json' },
});

Envoi des fichiers

Finaliser le transfert

POST upload.endpoints.finalize

Termine l'envoi : le lien de partage devient actif et le jeton d'envoi est détruit. Tous les fichiers doivent être validés, sinon la requête répond 422.

La réponse contient le lien à publier. Le serveur partenaire peut aussi le retrouver, avec le détail des fichiers, via Récupérer un transfert.

Requête
const { url, expires_at } = await fetch(upload.endpoints.finalize, {
  method: 'POST',
  headers: { [upload.header]: upload.token, Accept: 'application/json' },
}).then((response) => response.json());
Réponse
{
  "url": "https://drop.voxar.chat/t/k3x9q2m7pa",
  "expires_at": "2026-12-17T14:02:11+00:00"
}

Guides

Intégrer les pièces jointes

Ce guide met en place les pièces jointes d'une application partenaire en trois morceaux de code : une route serveur qui crée le transfert, une fonction navigateur qui envoie les fichiers, et l'appel depuis l'interface.

1. Configurer l'accès

Ajoutez l'URL de drop et le jeton d'API à la configuration du serveur partenaire (onglet Configuration). Le jeton reste côté serveur.

2. Créer le transfert côté serveur

Une route de l'application partenaire, protégée par sa propre authentification, crée le transfert et ne renvoie au navigateur que transfer_id et le bloc upload (onglet Serveur). Enregistrez transfer_id avec le message : il sert à afficher puis à supprimer la pièce jointe.

3. Envoyer les fichiers depuis le navigateur

La fonction uploadToDrop() (onglet Navigateur) déclare chaque fichier, envoie ses morceaux quatre par quatre, réessaie les erreurs réseau, valide le fichier puis finalise le transfert. Elle signale la progression entre 0 et 1.

4. Publier le lien

La finalisation renvoie l'url de partage, à publier dans le message (onglet Utilisation). Quand le message est supprimé, appelez Supprimer un transfert avec le transfer_id enregistré.

Envois de plus d'une heure

Les URL de morceaux sont valables 60 minutes. Pour un envoi très long (connexion lente, fichier proche de 2 Go), demandez les URL par petits lots au fil de l'envoi plutôt que toutes au début.
const PARALLEL_PARTS = 4;
const MAX_ATTEMPTS = 3;

/**
 * Envoie des fichiers à drop et finalise le transfert.
 * Renvoie { url, expires_at }.
 */
export async function uploadToDrop(upload, files, onProgress = () => {}) {
  const headers = { [upload.header]: upload.token, Accept: 'application/json' };
  const endpoint = (name, fileId = '') => upload.endpoints[name].replace('__FILE__', fileId);

  async function call(method, url, body) {
    const response = await fetch(url, {
      method,
      headers: body ? { ...headers, 'Content-Type': 'application/json' } : headers,
      body: body ? JSON.stringify(body) : undefined,
    });
    if (!response.ok) {
      throw new Error(`drop a répondu ${response.status}`);
    }
    return response.status === 204 ? null : response.json();
  }

  async function putPart(url, chunk) {
    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
      const response = await fetch(url, { method: 'PUT', body: chunk }).catch(() => null);
      if (response?.ok) {
        return response.headers.get('ETag');
      }
      if (response && response.status < 500) {
        throw new Error(`Morceau refusé (${response.status})`);
      }
      await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
    }
    throw new Error('Morceau non envoyé après plusieurs tentatives');
  }

  const total = files.reduce((sum, file) => sum + file.size, 0);
  let sent = 0;

  for (const file of files) {
    const remote = await call('POST', endpoint('files'), {
      name: file.name,
      size: file.size,
      mime: file.type || null,
    });

    if (remote.status === 'ready') {
      continue;
    }

    const queue = [];
    for (let start = 1; start <= remote.part_count; start += 100) {
      const { parts } = await call('GET', `${endpoint('parts', remote.id)}?start=${start}&count=100`);
      queue.push(...parts);
    }

    const uploaded = [];
    const worker = async () => {
      for (let part = queue.shift(); part; part = queue.shift()) {
        const chunk = file.slice((part.number - 1) * remote.part_size, part.number * remote.part_size);
        uploaded.push({ number: part.number, etag: await putPart(part.url, chunk) });
        onProgress((sent += chunk.size) / total);
      }
    };
    await Promise.all(Array.from({ length: PARALLEL_PARTS }, worker));

    await call('POST', endpoint('complete', remote.id), { parts: uploaded });
  }

  return call('POST', endpoint('finalize'));
}

Administration

Mise en place

Ces étapes se font une fois, sur le serveur drop, pour chaque application partenaire.

  1. Appliquer les migrations, qui créent la table des jetons d'API.
  2. Créer un compte drop pour le partenaire, depuis la page d'inscription. Ce compte possédera tous ses transferts.
  3. Créer le jeton avec php artisan api:token et le transmettre au partenaire par un canal sûr. Il ne s'affiche qu'une fois.
  4. Autoriser le domaine du partenaire dans CORS_ALLOWED_ORIGINS.
  5. En stockage S3, ajouter ce domaine à la règle CORS du bucket, avec l'en-tête ETag exposé (onglet CORS S3).
# 1. Créer la table des jetons
php artisan migrate

# 2. Créer le jeton d'API du partenaire (affiché une seule fois)
php artisan api:token partenaire@exemple.fr --name=voxar

# 3. Autoriser son domaine à appeler l'API depuis le navigateur (.env)
CORS_ALLOWED_ORIGINS=https://voxar.exemple.fr

Administration

Configuration

Ces variables du fichier .env règlent l'API. Les limites affichées dans cette documentation en sont tirées automatiquement.

Variables d'environnement

  • CORS_ALLOWED_ORIGINS liste

    Domaines autorisés à appeler /api depuis un navigateur, séparés par des virgules. * les autorise tous.

    Défaut : *

  • TRANSFERS_API_MAX_EXPIRY_DAYS entier

    Durée de validité maximale d'un transfert créé par l'API, en jours.

    Défaut : 90

  • TRANSFERS_MAX_BYTES entier

    Taille maximale d'un transfert, en octets.

    Défaut : 2147483648 (2 Go)

  • TRANSFERS_MAX_FILES entier

    Nombre maximal de fichiers par transfert.

    Défaut : 500

  • TRANSFERS_PART_SIZE entier

    Taille d'un morceau, en octets. 5 Mo au minimum en stockage S3.

    Défaut : 16777216 (16 Mo)

  • TRANSFERS_STORAGE_DRIVER enum

    local : les morceaux passent par le serveur. s3 : ils partent directement vers le stockage objet.

    Défaut : local

Administration

Révoquer un jeton

Les jetons d'API n'expirent pas. En cas de fuite ou de fin de partenariat, supprimez-le : les requêtes suivantes répondent aussitôt 401. Les transferts déjà créés restent en ligne jusqu'à leur expiration.

Terminal
php artisan tinker --execute '
    App\Models\User::firstWhere("email", "partenaire@exemple.fr")
        ->tokens()
        ->where("name", "voxar")
        ->delete();
'

Administration

Versions

La version figure dans l'URL (/api/v1). Une évolution incompatible donnera lieu à une nouvelle version ; les ajouts compatibles (nouveaux champs, nouvelles routes) peuvent arriver dans la version actuelle. Ignorez les champs que vous ne connaissez pas.

VersionDateChangements
v1 17 novembre 2026 Première version : création, consultation et suppression des transferts, envoi des fichiers en morceaux depuis le navigateur.

Limites connues

  • Pas de webhook : la fin d'un envoi se constate par la réponse de la finalisation ou par Récupérer un transfert.
  • En stockage local, un très gros fichier est assemblé pendant la requête de validation : prévoir un max_execution_time suffisant.
  • En stockage S3, une taille reçue différente de la taille déclarée répond 500 au lieu de 422.