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.
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.
- Le serveur crée un transfert avec
POST /transfers. Il reçoit le lien de partage et un blocupload. - Le navigateur envoie les fichiers grâce au bloc
upload: il déclare chaque fichier, l'envoie en morceaux, puis finalise le transfert. - 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.
// Le navigateur récupère le bloc « upload » auprès du serveur partenaire…
const { upload } = await fetch('/attachments/uploads', { method: 'POST' })
.then((response) => response.json());
// …envoie les fichiers à drop (voir le guide d'intégration)…
const { url } = await uploadToDrop(upload, [...input.files]);
// …puis publie le lien de partage dans le message.
await postMessage({ body: url });
Démarrage
Authentification
L'API utilise deux jetons, chacun limité à son rôle.
| Jeton | Utilisé par | En-tête |
|---|---|---|
| Jeton d'API | Serveur partenaire | Authorization: Bearer … |
| Jeton d'envoi | Navigateur | X-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
upload est destiné au navigateur.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.
| Code | Signification | Que 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. |
{
"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."
]
}
}
{
"message": "Unauthenticated."
}
{
"message": "Jeton d'envoi invalide."
}
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 |
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
-
idstringIdentifiant unique du transfert (UUID).
-
statusenumdraft: envoi en cours, lien inactif.ready: finalisé et partageable.removed: retiré par la modération. -
urlstringPage 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_urlstringTéléchargement de tous les fichiers en une archive zip.
-
titlestring | nullTitre affiché au destinataire.
-
messagestring | nullMessage affiché au destinataire.
-
is_protectedbooleantruesi un mot de passe est demandé avant le téléchargement. -
max_downloadsinteger | nullNombre maximal de visiteurs autorisés à télécharger.
null: illimité. -
download_countintegerNombre de visiteurs ayant déjà téléchargé. Un visiteur est compté une fois par session de navigateur.
-
expires_atstringDate d'expiration (ISO 8601). Le transfert et ses fichiers sont supprimés dans l'heure qui suit.
-
created_atstringDate de création (ISO 8601).
-
files_countintegerNombre de fichiers.
-
total_sizeintegerTaille totale des fichiers, en octets.
-
filesarrayFichiers du transfert, triés par nom.
Afficher les attributs enfants Masquer les attributs enfants
-
idstringIdentifiant unique du fichier (UUID).
-
namestringNom du fichier, avec son dossier éventuel :
photos/plan.png. -
sizeintegerTaille en octets.
-
mimestring | nullType MIME déclaré à l'envoi.
-
statusenumuploadingouready. -
download_urlstringTéléchargement direct de ce fichier.
-
preview_urlstring | nullURL 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.nullsi 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.
-
{
"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
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
-
titlestring facultatifTitre affiché au destinataire. 120 caractères au plus.
-
messagestring facultatifMessage affiché au destinataire. 2 000 caractères au plus.
-
passwordstring facultatifMot de passe demandé avant le téléchargement, de 4 à 128 caractères. Il n'est jamais renvoyé par l'API.
-
expires_in_daysinteger facultatifDurée de validité, de 1 à 90 jours, comptée à partir de la création.
Défaut :
7 -
max_downloadsinteger facultatifNombre maximal de visiteurs autorisés à télécharger, de 1 à 10 000. Sans valeur : illimité.
Retour
-
dataTransfertLe transfert créé, au statut
draft. Sonurlne sera active qu'après la finalisation. -
uploadobjectÀ transmettre tel quel au navigateur. Ne contient pas le jeton d'API.
Afficher les attributs enfants Masquer les attributs enfants
-
tokenstringJeton d'envoi, à placer dans l'en-tête indiqué par
header. -
headerstringNom de l'en-tête :
X-Upload-Token. -
expires_atstringLimite pour finaliser l'envoi. Passé ce délai, le brouillon est supprimé.
-
endpointsobjectURL de
files,parts,complete,destroyetfinalize.__FILE__y est à remplacer par l'identifiant du fichier.
-
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
use Illuminate\Support\Facades\Http;
$response = Http::withToken(config('services.drop.token'))
->acceptJson()
->post('https://drop.voxar.chat/api/v1/transfers', [
'title' => 'Compte rendu',
'expires_in_days' => 30,
])
->throw();
$transfer = $response->json('data');
$upload = $response->json('upload'); // à transmettre au navigateur
const response = await fetch('https://drop.voxar.chat/api/v1/transfers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DROP_API_TOKEN}`,
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({ title: 'Compte rendu', expires_in_days: 30 }),
});
const { data: transfer, upload } = await response.json();
{
"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
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
-
idstring requisIdentifiant du transfert, dans l'URL.
Retour
-
dataTransfertUn objet Transfert, fichiers compris.
curl https://drop.voxar.chat/api/v1/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77 \
-H "Authorization: Bearer $DROP_API_TOKEN" \
-H "Accept: application/json"
$transfer = Http::withToken(config('services.drop.token'))
->acceptJson()
->get('https://drop.voxar.chat/api/v1/transfers/'.$transferId)
->throw()
->json('data');
const response = await fetch(`https://drop.voxar.chat/api/v1/transfers/${transferId}`, {
headers: {
Authorization: `Bearer ${process.env.DROP_API_TOKEN}`,
Accept: 'application/json',
},
});
const { data: transfer } = await response.json();
{
"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
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
-
idstring requisIdentifiant du transfert, dans l'URL.
Retour
-
204No ContentRéponse vide en cas de succès.
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"
Http::withToken(config('services.drop.token'))
->acceptJson()
->delete('https://drop.voxar.chat/api/v1/transfers/'.$transferId)
->throw();
await fetch(`https://drop.voxar.chat/api/v1/transfers/${transferId}`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.DROP_API_TOKEN}`,
Accept: 'application/json',
},
});
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
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
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
-
namestring requisNom 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. -
sizeinteger requisTaille exacte en octets. Elle est vérifiée à la validation du fichier.
-
mimestring facultatifType MIME, transmis au destinataire lors du téléchargement.
Retour
-
idstringIdentifiant du fichier, à placer à la place de
__FILE__dans les URL suivantes. -
part_sizeintegerTaille d'un morceau, en octets. Seul le dernier morceau peut être plus petit.
-
part_countintegerNombre de morceaux à envoyer (au moins 1, même pour un fichier vide).
-
statusenumuploading. Si la valeur estready, le contenu est déjà connu : passez directement au fichier suivant.
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());
curl https://drop.voxar.chat/api/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77/files \
-H "X-Upload-Token: $UPLOAD_TOKEN" \
-H "Accept: application/json" \
-d name="rapport.pdf" \
-d size=48213409 \
-d mime="application/pdf"
{
"id": "019a8c2f-1b7a-7f02-9c3d-8e4b1a6f2d99",
"part_size": 16777216,
"part_count": 3,
"status": "uploading"
}
Envoi des fichiers
Obtenir les URL des morceaux
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
-
startinteger facultatifNuméro du premier morceau demandé.
Défaut :
1 -
countinteger facultatifNombre d'URL demandées, 100 au plus.
Défaut :
20
Retour
-
partsarrayUne entrée par morceau, avec son
numberet sonurld'envoi, valable 60 minutes.
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());
curl "https://drop.voxar.chat/api/transfers/019a8c2e-…/files/019a8c2f-…/parts?start=1&count=100" \
-H "X-Upload-Token: $UPLOAD_TOKEN" \
-H "Accept: application/json"
{
"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
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
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.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');
curl -X PUT "$PART_URL" \
--data-binary @rapport.part1 \
--include
HTTP/1.1 200 OK
ETag: "9b2c0f4e8d1a7b3c5e6f8a9b0c1d2e3f"
Envoi des fichiers
Valider un fichier
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
-
partsarray requisTous les morceaux du fichier, de 1 à
part_count, dans n'importe quel ordre.Afficher les attributs enfants Masquer les attributs enfants
-
numberinteger requisNuméro du morceau.
-
etagstring requisValeur de l'en-tête
ETagreçue à l'envoi du morceau, guillemets compris.
-
Retour
-
idstringIdentifiant du fichier.
-
statusenumready: le fichier est complet.
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"' },
],
}),
});
curl https://drop.voxar.chat/api/transfers/019a8c2e-…/files/019a8c2f-…/complete \
-H "X-Upload-Token: $UPLOAD_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"parts": [{"number": 1, "etag": "\"9b2c…\""}, {"number": 2, "etag": "\"41fe…\""}, {"number": 3, "etag": "\"d07b…\""}]}'
{
"id": "019a8c2f-1b7a-7f02-9c3d-8e4b1a6f2d99",
"status": "ready"
}
Envoi des fichiers
Retirer un fichier
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.
await fetch(upload.endpoints.destroy.replace('__FILE__', remote.id), {
method: 'DELETE',
headers: { [upload.header]: upload.token, Accept: 'application/json' },
});
curl -X DELETE https://drop.voxar.chat/api/transfers/019a8c2e-…/files/019a8c2f-… \
-H "X-Upload-Token: $UPLOAD_TOKEN" \
-H "Accept: application/json"
Envoi des fichiers
Finaliser le transfert
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.
const { url, expires_at } = await fetch(upload.endpoints.finalize, {
method: 'POST',
headers: { [upload.header]: upload.token, Accept: 'application/json' },
}).then((response) => response.json());
curl -X POST https://drop.voxar.chat/api/transfers/019a8c2e-6b1f-7c3d-9e4a-2f5b8d1c0a77/finalize \
-H "X-Upload-Token: $UPLOAD_TOKEN" \
-H "Accept: application/json"
{
"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
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'));
}
<?php
namespace App\Http\Controllers;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
class AttachmentUploadController extends Controller
{
/**
* Crée un transfert drop et renvoie au navigateur de quoi y envoyer les fichiers.
*/
public function store(Request $request): JsonResponse
{
$response = Http::withToken(config('services.drop.token'))
->acceptJson()
->post(config('services.drop.url').'/api/v1/transfers', [
'title' => $request->string('title')->limit(120, '')->toString() ?: null,
'expires_in_days' => 90,
])
->throw();
return response()->json([
'transfer_id' => $response->json('data.id'),
'upload' => $response->json('upload'),
]);
}
}
// config/services.php
'drop' => [
'url' => env('DROP_URL'),
'token' => env('DROP_API_TOKEN'),
],
// .env
// DROP_URL=https://drop.voxar.chat
// DROP_API_TOKEN=3|q8ZrT4vKx2…
import { uploadToDrop } from './drop';
const { transfer_id, upload } = await fetch('/attachments/uploads', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken },
body: JSON.stringify({ title: 'Pièces jointes' }),
}).then((response) => response.json());
const { url } = await uploadToDrop(upload, [...input.files], (ratio) => {
progressBar.style.width = `${Math.round(ratio * 100)}%`;
});
// Enregistrez transfer_id avec le message, publiez url.
Administration
Mise en place
Ces étapes se font une fois, sur le serveur drop, pour chaque application partenaire.
- Appliquer les migrations, qui créent la table des jetons d'API.
- Créer un compte drop pour le partenaire, depuis la page d'inscription. Ce compte possédera tous ses transferts.
- Créer le jeton avec
php artisan api:tokenet le transmettre au partenaire par un canal sûr. Il ne s'affiche qu'une fois. - Autoriser le domaine du partenaire dans
CORS_ALLOWED_ORIGINS. - En stockage S3, ajouter ce domaine à la règle CORS du bucket, avec l'en-tête
ETagexposé (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
[
{
"AllowedOrigins": ["https://voxar.exemple.fr", "https://drop.voxar.chat"],
"AllowedMethods": ["PUT", "GET"],
"AllowedHeaders": ["*"],
"ExposeHeaders": ["ETag"],
"MaxAgeSeconds": 3600
}
]
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_ORIGINSlisteDomaines autorisés à appeler
/apidepuis un navigateur, séparés par des virgules.*les autorise tous.Défaut :
* -
TRANSFERS_API_MAX_EXPIRY_DAYSentierDurée de validité maximale d'un transfert créé par l'API, en jours.
Défaut :
90 -
TRANSFERS_MAX_BYTESentierTaille maximale d'un transfert, en octets.
Défaut :
2147483648 (2 Go) -
TRANSFERS_MAX_FILESentierNombre maximal de fichiers par transfert.
Défaut :
500 -
TRANSFERS_PART_SIZEentierTaille d'un morceau, en octets. 5 Mo au minimum en stockage S3.
Défaut :
16777216 (16 Mo) -
TRANSFERS_STORAGE_DRIVERenumlocal: 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.
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.
| Version | Date | Changements |
|---|---|---|
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_timesuffisant. - En stockage S3, une taille reçue différente de la taille déclarée répond
500au lieu de422.