Docs/Sessions d'envoi

Sessions d'envoi

Une session d'envoi représente un événement unique de collecte de photos mobiles. Les sessions référencent des destinations préconfigurées où les images sont livrées. Vous pouvez envoyer simultanément vers plusieurs destinations.

Créer une session

Créez une session en spécifiant les destinations qui doivent recevoir les images envoyées. Si vous omettez destination_ids, les destinations par défaut de la clé API sont utilisées.

POST/api/v1/upload-sessions

Corps de la requête

Champ	Type	Requis	Description
destination_ids	string[]	Non	Tableau d'identifiants UUID de destinations préconfigurées. Utilise les destinations par défaut de la clé API si omis.
long_polling	boolean	Non	Active la livraison par interrogation en plus des destinations push.
tags	string[]	Non	Tableau de chaînes de caractères pour corréler les envois (ex. user:123, order:456).
expires_in_hours	integer	Non	Durée de vie de la session en heures (1–168). Mutuellement exclusif avec expires_at.
expires_at	string	Non	Expiration absolue au format ISO 8601. Mutuellement exclusif avec expires_in_hours.
max_images	integer	Non	Nombre maximal d'images autorisées dans cette session.
allowed_mime_types	string[]	Non	Restreint les formats acceptés. Sous-ensemble de image/jpeg, image/png, image/webp, image/heic.
max_image_dimension	integer	Non	Dimension maximale en pixels (largeur ou hauteur) pour les images envoyées.
password	string	Non	Exiger un mot de passe pour accéder à la page d'envoi (4–128 caractères).

curl -X POST https://api.apertur.ca/api/v1/upload-sessions \
  -H "Authorization: Bearer aptr_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_ids": [
      "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ],
    "tags": ["user:123", "order:456"],
    "expires_in_hours": 24,
    "max_images": 10
  }'

Destinations

Les destinations sont des cibles de livraison préconfigurées gérées dans votre tableau de bord sous Projet → Destinations. Apertur prend en charge 9 types de destinations répartis en quatre catégories.

Stockage infonuagique

Amazon S3 ou tout stockage compatible S3 (MinIO, Backblaze B2, DigitalOcean Spaces, etc.).

endpoint, region, bucket, accessKey, secretKey, pathTemplate, customHeaders

azure_blob

Conteneurs Azure Blob Storage.

connectionString, container, pathTemplate

Lecteurs infonuagiques

google_driveOAuth

Google Drive. Connecté via OAuth — les jetons sont automatiquement rafraîchis.

folderId, pathTemplate

dropboxOAuth

Dropbox. Dossier par défaut : /Apps/Apertur.

folderPath

onedriveOAuth

Microsoft OneDrive. Dossier par défaut : /Apertur.

driveId, folderPath

boxOAuth

Box.com. Dossier par défaut : racine.

folderId

Serveur

ftp

FTP, FTPS ou SFTP. Prend en charge l'authentification par mot de passe et par clé privée.

host, port, username, password, protocol, remotePath, privateKey

webdav

Serveurs compatibles WebDAV (Nextcloud, ownCloud, etc.).

url, username, password, remotePath

HTTP

webhook

POST HTTP vers votre point de terminaison. Prend en charge les formats multipart, JSON base64 et binaire. Signature HMAC incluse.

url, secret, format (multipart / json_base64 / binary)

Gestion des destinations

Gérez les destinations via l'API ou le tableau de bord sous Projet → Destinations.

Méthode	Point de terminaison	Description
POST	/api/v1/projects/:projectId/destinations	Créer une nouvelle destination
GET	/api/v1/projects/:projectId/destinations	Lister toutes les destinations
PATCH	/api/v1/projects/:projectId/destinations/:destId	Mettre à jour une destination
DELETE	/api/v1/projects/:projectId/destinations/:destId	Supprimer une destination

Les destinations basées sur OAuth (google_drive, dropbox, onedrive, box) sont créées via un flux d'autorisation OAuth initié depuis le tableau de bord.

Long polling

Le long polling est une option boolean sur la session, et non un type de destination. Lorsqu'il est activé, votre serveur peut interroger pour obtenir les images en parallèle des destinations push. Ceci est utile lorsque votre serveur ne peut pas accepter de requêtes entrantes. Consultez la documentation sur le Long Polling pour plus de détails.

{
  "destination_ids": ["d290f1ee-..."],
  "long_polling": true
}

Réponse

La réponse inclut un uuid pour identifier la session ainsi que la liste des destinations résolues.

{
  "uuid": "sess_01HX4ABCDEFGHIJKLMN",
  "destinations": [
    { "id": "d290f1ee-...", "type": "s3", "name": "Production S3" },
    { "id": "7c9e6679-...", "type": "webhook", "name": "My Webhook" }
  ],
  "long_polling": false,
  "expires_at": "2024-03-29T10:00:00Z",
  "password_protected": false
}

Champ	Type	Description
uuid	string	Identifiant unique de la session
destinations	object[]	Tableau des destinations résolues (id, type, name)
long_polling	boolean	Indique si la livraison par interrogation est activée
expires_at	string	Date et heure d'expiration au format ISO 8601
password_protected	boolean	Indique si la session requiert un mot de passe

Statut de livraison

Suivez la progression de la livraison par image et par destination pour toute session.

GET/api/v1/upload-sessions/:uuid/delivery-status

curl https://api.apertur.ca/api/v1/upload-sessions/sess_01HX4ABCDEFGHIJKLMN/delivery-status \
  -H "Authorization: Bearer aptr_xxxx"

{
  "session_id": "sess_01HX4ABCDEFGHIJKLMN",
  "images": [
    {
      "image_id": "img_01HX...",
      "image_index": 0,
      "deliveries": [
        {
          "destination_id": "d290f1ee-...",
          "destination_name": "Production S3",
          "destination_type": "s3",
          "status": "delivered",
          "delivered_at": "2024-03-28T10:01:23Z"
        },
        {
          "destination_id": "7c9e6679-...",
          "destination_name": "My Webhook",
          "destination_type": "webhook",
          "status": "pending",
          "attempts": 1,
          "next_retry_at": "2024-03-28T10:02:00Z"
        }
      ]
    }
  ]
}

Politique de nouvelle tentative

Les livraisons échouées sont retentées jusqu'à 5 fois avec des délais croissants : 5 s, 30 s, 2 min, 10 min, 1 h.

Options de session

Ces champs optionnels vous permettent de personnaliser le comportement de la session.

Option	Description	Par défaut
password	Exiger un mot de passe pour accéder à la page d'envoi (4–128 car.)	Aucun (pas de mot de passe)
max_images	Limiter le nombre d'images qu'un utilisateur peut envoyer	Valeur par défaut du plan
expires_in_hours	Durée de vie de la session en heures (1–168)	24 heures
expires_at	Expiration absolue au format ISO 8601	-
allowed_mime_types	Restreindre les formats d'image acceptés	Tous les types pris en charge
max_image_dimension	Dimension maximale en pixels (largeur ou hauteur)	Aucune limite
tags	Tableau de chaînes de caractères pour corréler les envois avec vos données	[]

Statut de la session

Statut	Description
pending	Session créée, en attente que l'utilisateur scanne et soumette ses photos
uploading	L'utilisateur est en train d'envoyer des images
completed	Toutes les images ont été traitées et livrées
expired	La session a expiré avant que l'utilisateur n'ait soumis ses photos
failed	La livraison a échoué après épuisement de toutes les tentatives

← Authentification Suivant : Webhooks →