Docs/Données de projet

Données de projet

Ces points de terminaison permettent aux propriétaires de clés API et aux membres de projet de lire des statistiques agrégées ainsi que des listes de sessions et d'envois pour tous les projets auxquels ils ont accès. Ils sont conçus pour le tableau de bord et l'outillage interne, pas pour les clients finaux.

Authentification

Tous les endpoints de données de projet acceptent deux modes d'authentification. Passe un JWT de tableau de bord comme Bearer token pour interroger tous les projets que tu possèdes ou dont tu es membre, ou passe une clé API (Bearer aptr_…) pour restreindre les résultats au projet de cette clé.

Sessions récentes

Retourne les sessions d'envoi les plus récemment créées dans tous les projets auxquels l'appelant a accès. Utile pour les fils d'activité du tableau de bord.

GET/api/v1/sessions/recent

Paramètres de requête

Champ	Type	Requis	Description
limit	integer	Non	Nombre d'enregistrements à retourner. Valeur par défaut : 10, maximum : 50.

Réponse

Retourne un tableau d'objets représentant des lignes de session (sans enveloppe de pagination).

Champ	Type	Description
id	string	UUID de la session.
createdAt	string	Date-heure ISO 8601 de création de la session.
expiresAt	string	Date-heure ISO 8601 d'expiration de la session.
status	string	Une valeur parmi pending, active, expired, completed, failed.
projectId	string	UUID du projet auquel cette session appartient.
projectName	string	Nom d'affichage du projet.
imagesCount	integer	Nombre total d'enregistrements d'envoi sur cette session.
imagesDelivered	integer	Nombre d'envois ayant au moins une livraison réussie.
imagesFailed	integer	Nombre d'envois où au moins une destination a échoué.
destinationsCount	integer	Nombre de destinations vers lesquelles la session diffuse.
tags	string[] \| null	Étiquettes de la session, ou null si aucune n'est définie.
longPollingEnabled	boolean	Indique si le long polling est activé pour cette session.

curl https://api.apertur.ca/api/v1/sessions/recent?limit=10 \
  -H "Authorization: Bearer <jwt-token>"

Lister les sessions

Liste paginée des sessions d'envoi dans tous les projets auxquels l'appelant a accès.

GET/api/v1/sessions

Paramètres de requête

Champ	Type	Requis	Description
page	integer	Non	Numéro de page à retourner. Valeur par défaut : 1.
pageSize	integer	Non	Nombre d'enregistrements par page. Valeur par défaut : 20, maximum : 100.

Réponse

Retourne une enveloppe paginée. Le tableau data contient des objets de ligne de session ayant la même structure que /sessions/recent.

{
  "data": [/* array of session row objects */],
  "total": 134,
  "page": 1,
  "pageSize": 20,
  "totalPages": 7
}

Champ	Type	Description
id	string	UUID de la session.
createdAt	string	Date-heure ISO 8601 de création de la session.
expiresAt	string	Date-heure ISO 8601 d'expiration de la session.
status	string	Une valeur parmi pending, active, expired, completed, failed.
projectId	string	UUID du projet auquel cette session appartient.
projectName	string	Nom d'affichage du projet.
imagesCount	integer	Nombre total d'enregistrements d'envoi sur cette session.
imagesDelivered	integer	Nombre d'envois ayant au moins une livraison réussie.
imagesFailed	integer	Nombre d'envois où au moins une destination a échoué.
destinationsCount	integer	Nombre de destinations vers lesquelles la session diffuse.
tags	string[] \| null	Étiquettes de la session, ou null si aucune n'est définie.
longPollingEnabled	boolean	Indique si le long polling est activé pour cette session.

curl "https://api.apertur.ca/api/v1/sessions?page=1&pageSize=20" \
  -H "Authorization: Bearer <jwt-token>"

Envois récents

Retourne les enregistrements d'envoi les plus récemment reçus dans tous les projets auxquels l'appelant a accès, avec les compteurs de livraison par destination.

GET/api/v1/uploads/recent

Paramètres de requête

Champ	Type	Requis	Description
limit	integer	Non	Nombre d'enregistrements à retourner. Valeur par défaut : 10, maximum : 50.

Réponse

Retourne un tableau d'objets représentant des lignes d'envoi (sans enveloppe de pagination).

Champ	Type	Description
id	string	UUID de l'enregistrement d'envoi.
filename	string	Nom de fichier original du fichier envoyé.
sizeBytes	integer	Taille du fichier en octets.
mimeType	string	Type MIME détecté de l'envoi.
source	string	Une valeur parmi camera, gallery, url, google_drive, google_photos, dropbox, onedrive, box, instagram.
isEncrypted	boolean	Indique si le fichier est stocké chiffré côté client.
createdAt	string	Date-heure ISO 8601 de réception de l'envoi.
sessionId	string	UUID de la session d'envoi parente.
projectId	string	UUID du projet auquel cet envoi appartient.
projectName	string	Nom d'affichage du projet.
destinationsTotal	integer	Nombre total de destinations vers lesquelles cet envoi est livré.
destinationsDelivered	integer	Nombre de destinations qui ont reçu l'envoi avec succès.
destinationsFailed	integer	Nombre de destinations en échec définitif.
destinationsBreakdown	object[]	Tableau d'objets { type, count } regroupant les résultats de livraison par type de destination.
status	string	Statut dérivé : delivered, failed, partial, pending ou stored_only. Voir la note ci-dessous.

Calcul du statut d'envoi

delivered = toutes les destinations ont reçu avec succès. failed = au moins une destination a terminé et toutes ont échoué. partial = mélange de livré et d'échoué. pending = certaines destinations n'ont pas encore rapporté. stored_only = aucune destination n'a été dépêchée (l'image est seulement stockée sur le serveur).

curl https://api.apertur.ca/api/v1/uploads/recent?limit=10 \
  -H "Authorization: Bearer <jwt-token>"

Lister les envois

Liste paginée des enregistrements d'envoi dans tous les projets auxquels l'appelant a accès.

GET/api/v1/uploads

Paramètres de requête

Champ	Type	Requis	Description
page	integer	Non	Numéro de page à retourner. Valeur par défaut : 1.
pageSize	integer	Non	Nombre d'enregistrements par page. Valeur par défaut : 20, maximum : 100.

Réponse

Retourne une enveloppe paginée. Le tableau data contient des objets de ligne d'envoi ayant la même structure que /uploads/recent.

{
  "data": [/* array of upload row objects */],
  "total": 482,
  "page": 1,
  "pageSize": 20,
  "totalPages": 25
}

Champ	Type	Description
id	string	UUID de l'enregistrement d'envoi.
filename	string	Nom de fichier original du fichier envoyé.
sizeBytes	integer	Taille du fichier en octets.
mimeType	string	Type MIME détecté de l'envoi.
source	string	Une valeur parmi camera, gallery, url, google_drive, google_photos, dropbox, onedrive, box, instagram.
isEncrypted	boolean	Indique si le fichier est stocké chiffré côté client.
createdAt	string	Date-heure ISO 8601 de réception de l'envoi.
sessionId	string	UUID de la session d'envoi parente.
projectId	string	UUID du projet auquel cet envoi appartient.
projectName	string	Nom d'affichage du projet.
destinationsTotal	integer	Nombre total de destinations vers lesquelles cet envoi est livré.
destinationsDelivered	integer	Nombre de destinations qui ont reçu l'envoi avec succès.
destinationsFailed	integer	Nombre de destinations en échec définitif.
destinationsBreakdown	object[]	Tableau d'objets { type, count } regroupant les résultats de livraison par type de destination.
status	string	Statut dérivé : delivered, failed, partial, pending ou stored_only. Voir la note ci-dessous.

curl "https://api.apertur.ca/api/v1/uploads?page=1&pageSize=20" \
  -H "Authorization: Bearer <jwt-token>"

Statistiques agrégées

Retourne des métriques agrégées pour tous les projets auxquels l'appelant a accès, incluant les compteurs du mois en cours et les principaux projets par activité.

GET/api/v1/stats

Réponse

Champ	Type	Description
sessionsThisMonth	integer	Nombre de sessions créées durant le mois calendrier en cours.
sessionsTotal	integer	Nombre total de sessions depuis le début.
imagesUploaded	integer	Nombre total d'enregistrements téléversés depuis le début.
imagesDelivered	integer	Nombre d'enregistrements ayant au moins une livraison réussie.
deliverySuccessRate	integer	Pourcentage de 0 à 100, calculé à partir de envoyé / (envoyé + échoué) par destination.
totalProjects	integer	Nombre total de projets auxquels l'appelant a accès.
activeKeys	integer	Nombre de clés API actuellement actives dans ces projets.
topProjects	object[]	Tableau d'au plus 10 objets { id, name, sessions } classés par nombre de sessions ce mois-ci.

curl https://api.apertur.ca/api/v1/stats \
  -H "Authorization: Bearer <jwt-token>"

← Sessions d'envoi Suivant : Destinations →