Référence du SDK

Cette page décrit les paramètres, les captures, les réponses d'envoi et les conditions de réessai. Les signatures propres à votre plateforme se trouvent dans les guides React Native, Capacitor et natif.

Configuration

Paramètre	Type	Capacitor	React Native	Description
apiKey	string	requis	requis	Clé API SDK fournie pour votre entreprise.
baseUrl	string	requis	optionnel	URL terminée par /certificall/. Par défaut en React Native : production.
appVersion	string	requis	optionnel	Version de votre application. Par défaut en React Native : 1.0.0.

Avec Capacitor, appelez initialize(options). Avec React Native, appelez configure(options). Attendez la résolution de la promesse avant toute capture ou tout envoi. Indiquez explicitement baseUrl pour maîtriser l'environnement utilisé.

takePhoto()

const photo = await CertificallTrust.takePhoto({
  reportToken: 'CHANTIER-2026-001',
  metadata: { site: 'Paris', zone: 'A1' },
});

L'objet de paramètres est optionnel. La méthode vérifie l'appareil, ouvre sa caméra et retourne une capture locale CapturedPhoto. Aucun dossier n'est créé avant l'envoi.

Paramètre	Type	Requis	Description
reportToken	string	non	Votre référence métier, restituée à l'envoi et dans reportId des webhooks. Limitez-la à 255 caractères.
metadata	Record<string, string>	non	Paires clé-valeur attachées au dossier créé à l'envoi.

Pour metadata, utilisez au maximum 20 clés, de 40 caractères au plus, avec des valeurs texte de 500 caractères au plus. Les clés ne peuvent pas contenir [ ou ]. Un nombre ou un booléen doit être converti en texte ("42", "true").

Des métadonnées invalides sont écartées à l'envoi et signalées par METADATA_DROPPED ; elles n'empêchent pas à elles seules la certification. Voir aussi Métadonnées de dossier.

CapturedPhoto

Champ	Type	Description
captureId	string	UUID de la prise, utilisé pour reconnaître ses réessais.
capturedAt	string	Date de la prise, ISO 8601 UTC.
sessionId	string	Identifiant de session généré par le SDK. Conservez-le sans le reconstruire.
image	CapturedImage	Image JPEG en base64, format et dimensions.
exif	object ou null	Données EXIF disponibles.
signals	CaptureSignals	Données de confiance figées à la prise.
debugBuild	boolean	Indique une capture issue d'un build de développement.
reportToken	string ou null	Référence métier fournie à la prise.
metadata	object ou null	Métadonnées fournies à la prise.
target	null	Champ réservé ; conservez la valeur retournée par le SDK.
proof	null	Champ réservé ; conservez la valeur retournée par le SDK.

Image

Champ	Type	Description
image.base64	string	Contenu JPEG en base64, indispensable pour l'envoi.
image.format	string	jpeg.
image.width	number	Largeur en pixels.
image.height	number	Hauteur en pixels.

Données de confiance

Le SDK collecte automatiquement ces données à partir de sa configuration, puis les joint à la capture. Vous n'avez pas à les collecter ni à les ajouter vous-même.

Champ	Contenu
signals.historyPositions	Positions : timestamp, lat, long, accuracy, altitude, speed, heading.
signals.historyMotions	Mouvements : timestamp, acceleration (x, y, z) et rotation (alpha, beta, gamma).
signals.device	manufacturer, model, name, platform, os, osVersion, appVersion, isVirtual, batteryLevel, isCharging.
signals.network	connectionType, wifiIp, carrierIp. Les adresses peuvent être null.

Les timestamps des historiques sont en millisecondes. Les coordonnées sont en degrés, la précision et l'altitude en mètres, la vitesse en mètres par seconde et le cap en degrés. L'accélération est en m/s², gravité comprise ; la rotation est en degrés par seconde. La batterie est une fraction entre 0 et 1 (0.8 pour 80 %), ou null si elle est inconnue.

Les données restent celles de la prise, même lors d'un envoi différé. Les tableaux peuvent être vides lorsqu'aucun signal n'a pu être collecté ; consultez les avertissements de la réponse d'envoi.

sendPhoto()

Passez la capture complète retournée par takePhoto(), ou restaurée depuis votre stockage :

// React Native
const sent = await CertificallTrust.sendPhoto(photo);

// Capacitor
const sent = await CertificallTrust.sendPhoto({ photo });

Certificall crée le dossier, y dépose la photo, le clôture et produit le certificat PDF. La réponse SentPhoto est rendue après ce parcours. Les données de confiance manquantes sont indiquées dans warnings.

Appelez sendPhoto() dès la prise, dès que le réseau le permet. Une photo transmise plus de 10 minutes après sa prise porte sur son certificat le bandeau « absence de connexion internet ».

SentPhoto

Champ	Type	Description
captureId	string	Identifiant de la capture envoyée.
itemId	string	Identifiant de la photo Certificall.
caseId	string	Identifiant du dossier créé.
reportToken	string (optionnel)	Référence métier retournée en écho.
imageUrl	string	URL de l'image.
pdfUrl	string	URL du certificat PDF.
geoloc	{ lat: number, lng: number } (optionnel)	Coordonnées retenues pour la photo. En cas de NO_POSITION, ne les utilisez pas comme une localisation réelle.
createdAt	string	Date de création côté serveur, ISO 8601.
warnings	{ code: string, message: string }[]	Données manquantes, écartées ou remplacées ; tableau vide si aucun avertissement.

Les champs supplémentaires renvoyés par Certificall sont transmis par le SDK. Prévoyez de tolérer des champs et des codes d'avertissement supplémentaires.

Certificat et analyse

La réponse ne contient pas de score. Le webhook de dossier transmet le dossier à sa clôture ; le webhook de résultat d'analyse transmet ensuite le résultat de confiance. Vous pouvez les rattacher à votre système avec reportToken, restitué dans reportId.

Conservation et réessais

Le SDK ne maintient pas de file persistante et ne programme pas de réessais automatiques. Votre application prend en charge le stockage et l'ordonnancement des envois.

1. Enregistrez l'objet complet retourné par takePhoto(), avec JSON.stringify(photo) pour les bridges JavaScript. Incluez image.base64.
2. Relisez-le avec JSON.parse(serializedPhoto) lorsque l'envoi devient possible.
3. Appelez sendPhoto() avec la capture restaurée, sans modifier ses identifiants ni ses signaux.
4. Retirez la capture de votre file après une réponse réussie, en conservant les identifiants et les liens dont votre application a besoin.

En cas de coupure réseau ou de fermeture de l'application avant réception de la réponse, renvoyez la même capture. Si elle a déjà été certifiée, vous recevez les mêmes identifiants de dossier et de photo, et le même lien de certificat. Une nouvelle prise avec takePhoto() porte un autre captureId et crée un autre dossier.

Situation	Action
NETWORK_UNAVAILABLE	Gardez la capture et réessayez lorsque Certificall est joignable.
SERVER_REJECTED, raison CAPTURE_IN_PROGRESS, HTTP 409	La même capture est en cours de certification. Réessayez après quelques minutes.
SERVER_REJECTED, raison CAPTURE_NOT_CERTIFIED, HTTP 503	La photo a été reçue mais la certification a échoué. Conservez-la et réessayez plus tard.
HTTP 429	Espacez vos envois et réessayez après la fenêtre de limitation.
Autre erreur serveur 5xx	Conservez la capture et réessayez avec un délai.
Clé invalide ou entreprise bloquée	Corrigez la situation avant de reprendre les envois.

Si une première tentative reste inachevée pendant plus de 10 minutes, un réessai peut repartir dans un nouveau dossier. La restitution du même dossier concerne une capture déjà certifiée ; un dossier resté inachevé n'est pas réutilisé au-delà de ce délai.

Préserver la capture

Conservez le JSON produit par le SDK tel quel. Ne remplacez pas les signaux par ceux du moment de l'envoi et ne retirez pas captureId : il permet à Certificall de reconnaître un réessai.

Avertissements

Un avertissement n'est pas un échec d'envoi : une réponse réussie avec warnings correspond à une photo enregistrée et certifiée. Les données manquantes peuvent dégrader le score de confiance. Votre application peut prévenir l'utilisateur ou lui proposer une nouvelle prise selon votre besoin métier.

Code	Signification
NO_POSITION	Aucune position exploitable ; la photo n'est pas localisée.
NO_MOTION	Aucun mouvement collecté.
NO_DEVICE	Modèle d'appareil absent ou illisible.
NO_BATTERY	Niveau de batterie inconnu.
NO_IP	Aucune adresse IP fournie.
CAPTURE_UNREADABLE	Description de capture absente ou illisible ; les signaux ne peuvent pas être utilisés.
CAPTURE_ID_GENERATED	Identifiant de prise absent ou invalide, remplacé côté serveur. Un réessai de cet envoi ne bénéficie pas de la reconnaissance par l'identifiant initial.
CAPTURED_AT_MISSING	Heure de prise absente ou invalide ; l'heure de réception est utilisée.
SIGNALS_DROPPED	Certaines positions ou certains mouvements illisibles ont été écartés.
SIGNALS_TRUNCATED	Plus de 200 positions ou mouvements transmis ; les 200 plus récents de chaque historique sont conservés.
METADATA_DROPPED	Métadonnées invalides ; le dossier est créé sans ces métadonnées.

Les message sont des explications en anglais. Utilisez les codes pour piloter votre logique et vos traductions.

Erreurs

Codes de capture et d'envoi

Code	Opération	Action
NOT_INITIALIZED	Capture ou envoi	Configurez le SDK et attendez la fin de l'initialisation.
DEVICE_NOT_TRUSTED	Capture	Lisez reasons et expliquez le refus d'appareil à l'utilisateur.
CAPTURE_CANCELLED	Capture	L'utilisateur a quitté la caméra. Aucun envoi n'a lieu.
NO_CAMERA	Capture	Aucune caméra disponible ; la galerie n'est pas proposée à la place.
CAPTURE_FAILED	Capture	La caméra n'a pas rendu une photo exploitable ; reprenez la capture.
INVALID_PHOTO	Envoi via un bridge ou restauration iOS	Passez l'objet complet retourné par takePhoto().
NETWORK_UNAVAILABLE	Envoi	Conservez la capture pour un réessai.
SERVER_REJECTED	Envoi	Lisez le statut HTTP et la raison serveur, puis appliquez la stratégie correspondante.

Les erreurs de configuration ou de permissions peuvent aussi relever des API de votre plateforme. Vérifiez les autorisations et la présence des paramètres de configuration.

Lire les informations complémentaires

Plateforme	Code	Raisons d'un refus d'appareil	Statut et raison serveur
Capacitor	error.code	error.data.reasons	error.data.status, error.data.reason
React Native	error.code	error.userInfo.reasons	error.userInfo.status, error.userInfo.reason
Swift	CertificallSDKError.code(of: error)	CertificallSDKError.reasons	httpStatus, serverCode sur l'erreur typée
Kotlin	CertificallError.codeOf(error)	DeviceNotTrustedException.reasons	SendPhotoException.httpStatus, SendPhotoException.serverCode

Refus serveur

Les refus HTTP remontent sous SERVER_REJECTED. La raison peut être absente ; ne vous appuyez pas uniquement sur le texte du message.

Statut HTTP	Raison lorsqu'elle est fournie	Action
400	INVALID_CAPTURE si l'image manque	Vérifiez que la capture et son image sont complètes.
401	Clé absente, invalide, inactive ou expirée	Vérifiez la clé de l'environnement et son renouvellement.
403	DEBUG_BUILD_REJECTED	Reprenez la photo avec un build de distribution pour la production.
409	CAPTURE_IN_PROGRESS	Réessayez la même capture plus tard.
409	CAPTURE_ID_TAKEN	L'identifiant est déjà utilisé par une autre capture ; reprenez une photo.
423	Entreprise bloquée	Faites rétablir l'accès de l'entreprise avant de reprendre les envois.
429	Limite d'appels atteinte	Espacez les envois.
503	CAPTURE_NOT_CERTIFIED	Conservez la capture et réessayez plus tard.

Une réponse HTTP 2xx qui ne contient pas de résultat de dossier peut également remonter comme SERVER_REJECTED. Vérifiez baseUrl, notamment son suffixe /certificall/, et conservez la capture jusqu'à un envoi réussi.