Revenir dans votre application après la capture
Quand la personne a pris ses photos, tryVidimus peut la ramener dans votre application et prévenir votre serveur que la capture est terminée.
Ce que voit la personne
Après la dernière photo, la page de capture affiche son texte de fin, puis un message du type « Vous allez être ramené sur app.example.com dans 4 s », avec deux boutons : y aller maintenant, ou rester sur la page. Au bout de 4 secondes, la personne est envoyée à votre adresse, avec les identifiants de la preuve ajoutés. Sans adresse de retour, la personne reste sur la page de fin.
1. Déclarer votre site
Un lien de capture ne doit jamais pouvoir envoyer une personne vers un site que vous n'avez pas choisi. Vous déclarez donc d'abord les sites que vous acceptez, sous forme d'origines (https://app.example.com, sans chemin), 20 au plus. Il y a une liste pour le test et une pour la production (la clé utilisée décide laquelle), et la modifier demande le droit manage_settings sur votre clé. Tant que vous n'avez rien déclaré, aucune adresse de retour n'est acceptée. Dans votre compte (page Sites), vous modifiez vous-même la liste de test ; la liste de production y est affichée en lecture seule pour l'instant : réglez-la avec l'API et une clé live, ou demandez-nous.
$ curl -X PATCH https://api.tryvidimus.com/v1/settings \ -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"allowed_return_origins":["https://app.example.com"]}' { "allowed_return_origins": ["https://app.example.com"] }
2. Transmettre l'adresse de retour
Ajoutez return_url à la création de la session de capture. Son site doit figurer dans votre liste, sinon l'appel échoue avec 422 return_url_not_allowed et aucune session n'est créée. Seul https est accepté ; http://localhost l'est pour les clés de bac à sable uniquement, pour le développement.
$ curl -X POST https://api.tryvidimus.com/v1/capture-sessions \ -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"external_reference":"booking_4471","party":"provider","return_url":"https://app.example.com/bookings/4471/capture-done"}'
3. Ce que reçoit votre page
Deux paramètres sont ajoutés à votre adresse : proof_id, la preuve en cours de création, et session_id. Rien d'autre : jamais votre propre référence, jamais le jeton de capture. Prenez-les comme des indices et non comme une preuve, car n'importe qui peut saisir une adresse. Pour être sûr que la capture a eu lieu, lisez la preuve avec l'API grâce à proof_id, ou appuyez-vous sur le webhook ci-dessous.
https://app.example.com/bookings/4471/capture-done
?proof_id=prf_01m4akapdbe8e8qq3er9r5qwyj
&session_id=cps_01m4akapdbe8e8qq3er9r5qwyj
4. Le signal fiable : le webhook
La redirection est un confort : la personne peut fermer la page avant qu'elle ait lieu. Le signal fiable est l'événement capture_session.completed, envoyé à votre serveur quelques secondes après l'enregistrement des fichiers et avant le scellement de la preuve. Abonnez-y votre endpoint : un endpoint créé avant cet événement ne le reçoit pas tant que vous ne l'ajoutez pas à ses événements. La preuve n'est pas encore scellée : attendez proof.sealed avant de vous appuyer dessus. L'événement garde le même identifiant à chaque nouvel essai, vous pouvez donc ignorer les doublons.
{
"event": "capture_session.completed",
"session_id": "cps_01m4akapdbe8e8qq3er9r5qwyj",
"proof_id": "prf_01m4akapdbe8e8qq3er9r5qwyj",
"external_reference": "booking_4471",
"party": "provider",
"stage": "pickup",
"completed_at": "2026-10-08T10:00:00.123Z"
}
En ligne de commande
La CLI fait la même chose sans écrire de requête : déclarez vos sites, puis passez --return-url à l'ouverture d'une session. Modifier la liste demande --yes, car elle remplace la précédente.
$ tryvidimus settings set-return-origins --origins https://app.example.com --yes $ tryvidimus sessions create --reference booking_4471 --party provider \ --return-url https://app.example.com/bookings/4471/capture-done
Ne vous fiez jamais à la seule redirection : attendez toujours le webhook, ou lisez la preuve avec l'API.