POST/v1/uploads/{upload_id}/complete

Terminer un téléversement

complete_upload

Lorsque toutes les parties sont reçues, Sursa assemble le fichier, compare le SHA-256 du fichier entier avec sha256 du corps et effectue les mêmes vérifications que pour un téléversement en une seule requête : le format d’après la signature du contenu et l’analyse antivirus. Le résultat est ready, ou rejected avec reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Chaque refus par la vérification du format ou par l’antivirus est inscrit au journal d’audit sous file.rejected.

Une réponse 200 signifie que le résultat est prêt ; 202 signifie que le fichier est encore en cours de vérification (processing), et le résultat s’obtient avec GET /v1/uploads/{upload_id}. Si l’état revient à pending (un redémarrage d’une instance de l’API a interrompu la vérification), envoyez de nouveau complete. Répéter complete après le résultat renvoie le même résultat. Des parties manquantes renvoient 409 uploads.incomplete (details.missing). Un sha256 différent de celui déclaré à la création, ou un parts[].etag différent d’une partie reçue, renvoie 422 uploads.checksum_mismatch. Un téléversement prêt mais non utilisé reste valable 24 heures. Ajouté dans la version 1.62.0.

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de chemin

upload_idstringobligatoire
ID du téléversement (upl_ suivi de 32 caractères hexadécimaux).
length ≤ 64

Paramètres d’en-tête

Idempotency-Keystring
Clé permettant de réessayer une écriture sans risque : de 1 à 255 caractères ASCII imprimables ; un UUID v4 par opération logique est recommandé. Une nouvelle tentative avec la même clé dans les 24 heures n’exécute pas l’opération une seconde fois : elle renvoie la réponse enregistrée (statut, en-têtes et corps) avec l’en-tête Idempotency-Replayed: true. La même clé avec une méthode, un chemin, un Content-Type ou un corps différents renvoie 409 api.idempotency_mismatch ; tant que la première requête est en cours, 409 api.idempotency_in_progress avec Retry-After: 1. Après une réponse 5xx ou 429, la clé est libérée, et une nouvelle tentative exécute de nouveau l’opération. La clé est propre à l’organisation et à l’appelant (clé API, utilisateur ou clé de source personnalisée).
length ≥ 1, length ≤ 255

Corps de la requête

application/json

Objet : UploadComplete

sha256stringobligatoire
SHA-256 du fichier entier.
partsarray of UploadPartRef
Vérification facultative des parties : l’ETag de chaque partie tel que renvoyé par PUT …/parts/{n}.
items ≤ 1000

Réponses

200Le résultat est prêt : `ready` ou `rejected`.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.
Idempotency-Replayed
true signifie que la réponse a été rejouée à partir de celle enregistrée pour cette Idempotency-Key : l’opération ne s’est pas exécutée une seconde fois.

application/json

Objet : Upload

idstringobligatoire
ID du téléversement (upl_ suivi de 32 caractères hexadécimaux).
purposeUploadPurposeobligatoire
filenamestringobligatoire
Nom du fichier (sans les dossiers).
content_typestringobligatoire
Type de contenu déclaré ; vide s’il n’a pas été déclaré.
sizeinteger (int64)obligatoire
Taille du fichier en octets.
sha256string | nullobligatoire
SHA-256 du fichier, déclaré à la création ou lors de complete ; null s’il n’est pas encore connu.
statusUploadStatusobligatoire
part_sizeinteger (int64)obligatoire
Taille de chaque partie sauf la dernière (de 5 à 100 Mio).
part_countintegerobligatoire
Nombre de parties.
≥ 1, ≤ 1000
parts_receivedintegerobligatoire
Nombre de parties reçues.
≥ 0
partsarray of UploadPartobligatoire
Parties reçues, par numéro (vide dans la réponse de POST /v1/uploads).
reject_reasonstring | nullobligatoire
Motif du rejet (rejected) : checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. L’énumération peut s’étendre ; null en l’absence de rejet.
reject_detailsobject | nullobligatoire
Détails du rejet (l’extension, le format déclaré et le format détecté, les sommes de contrôle) ; null en l’absence de rejet.
created_atstring (date-time)obligatoire
Date de création du téléversement.
expires_atstring (date-time)obligatoire
Date limite pour finaliser le téléversement et, une fois celui-ci prêt, pour l’utiliser.
completed_atstring (date-time) | nullobligatoire
Date de fin de la vérification (ready ou rejected).
consumed_atstring (date-time) | nullobligatoire
Date d’utilisation du téléversement (par une fiche, une archive ou une importation).

202Le fichier est encore en cours de vérification (`processing`).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.
Idempotency-Replayed
true signifie que la réponse a été rejouée à partir de celle enregistrée pour cette Idempotency-Key : l’opération ne s’est pas exécutée une seconde fois.

application/json

Objet : Upload

idstringobligatoire
ID du téléversement (upl_ suivi de 32 caractères hexadécimaux).
purposeUploadPurposeobligatoire
filenamestringobligatoire
Nom du fichier (sans les dossiers).
content_typestringobligatoire
Type de contenu déclaré ; vide s’il n’a pas été déclaré.
sizeinteger (int64)obligatoire
Taille du fichier en octets.
sha256string | nullobligatoire
SHA-256 du fichier, déclaré à la création ou lors de complete ; null s’il n’est pas encore connu.
statusUploadStatusobligatoire
part_sizeinteger (int64)obligatoire
Taille de chaque partie sauf la dernière (de 5 à 100 Mio).
part_countintegerobligatoire
Nombre de parties.
≥ 1, ≤ 1000
parts_receivedintegerobligatoire
Nombre de parties reçues.
≥ 0
partsarray of UploadPartobligatoire
Parties reçues, par numéro (vide dans la réponse de POST /v1/uploads).
reject_reasonstring | nullobligatoire
Motif du rejet (rejected) : checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. L’énumération peut s’étendre ; null en l’absence de rejet.
reject_detailsobject | nullobligatoire
Détails du rejet (l’extension, le format déclaré et le format détecté, les sommes de contrôle) ; null en l’absence de rejet.
created_atstring (date-time)obligatoire
Date de création du téléversement.
expires_atstring (date-time)obligatoire
Date limite pour finaliser le téléversement et, une fois celui-ci prêt, pour l’utiliser.
completed_atstring (date-time) | nullobligatoire
Date de fin de la vérification (ready ou rejected).
consumed_atstring (date-time) | nullobligatoire
Date d’utilisation du téléversement (par une fiche, une archive ou une importation).

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

409L’état de l’objet ne permet pas l’action, par exemple un doublon, une indexation en cours ou un job déjà traité.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

410L’objet a existé mais n’est plus disponible : le lien a déjà été utilisé ou a expiré, ou le fichier a été supprimé à la fin de sa durée de conservation.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

Retry-After
Nombre de secondes à attendre avant de réessayer la requête.
RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec chaque POST et PATCH. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter à nouveau la requête.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← uploads · Référence de l’API

curl -X POST 'https://api.sursa.com/v1/uploads/UPLOAD_ID/complete' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdefABCD"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Essayer

Clé API

La clé reste dans la mémoire de cet onglet et n’est envoyée qu’à https://api.sursa.com.

Les requêtes agissent sur les données réelles de votre organisation.

Idempotency-Key header

upload_id path *

Idempotency-Key

Si ce champ est vide, une nouvelle clé est générée pour chaque requête.

Corps de la requête (JSON)