Démarrage rapide pour les développeurs

Créez votre première demande de photos via l'API en 5 minutes.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Un compte Visiono actif avec accès API
• Une clé API créée
• Un point de terminaison webhook prêt (ou utilisez webhook.site pour les tests)

Étape 1 : Créer une demande de photos

Utilisez l'API pour créer une demande de photos ponctuelle :

curl -X POST "https://www.visiono.iohttps://www.visiono.io/fr/docs/api/v1/photo-requests" \
  -H "X-API-Key: vsk_live_votre_cle_api_ici" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Veuillez photographier le colis sous tous les angles",
    "expires_in_hours": 24
  }'

Réponse attendue

{
  "data": {
    "id": "req_abc123",
    "unique_code": "ABC123",
    "status": "pending",
    "instructions": "Veuillez photographier le colis sous tous les angles",
    "request_url": "https://visio.now/p/abc123",
    "code_entry_url": "https://visio.now/code",
    "expires_at": "2024-01-16T10:00:00Z",
    "created_at": "2024-01-15T10:00:00Z",
    "items": []
  }
}

Champs clés dans la réponse :

Champ	Description
id	Identifiant unique de la demande
request_url	Partagez ce lien avec votre client
unique_code	Code court pour saisie manuelle sur code_entry_url
expires_at	Quand la demande expire

Étape 2 : Partager le lien

Envoyez le request_url de la réponse à votre client par SMS, e-mail ou n'importe quel canal de messagerie.

Quand le client ouvre le lien :

1. Il voit vos instructions
2. L'appareil photo s'active (pas d'accès à la galerie)
3. Il prend les photos requises
4. Les photos sont soumises à votre espace de travail

Appareil photo uniquement

Les clients peuvent uniquement utiliser l'appareil photo de leur appareil — pas d'uploads depuis la galerie. Cela garantit des photos authentiques en temps réel.

Étape 3 : Recevoir le webhook

Quand les photos sont soumises, Visiono envoie un webhook à votre point de terminaison configuré.

Configurer votre gestionnaire de webhook

Créez un simple serveur Express pour recevoir les webhooks :

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
  // 1. Vérifier la signature
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    console.error('Signature webhook invalide');
    return res.status(401).send('Signature invalide');
  }

  // 2. Acquitter immédiatement
  res.status(200).send('OK');

  // 3. Traiter l'événement
  const { event, data } = req.body;

  if (event === 'photo_request.submitted') {
    console.log('ID de demande :', data.id);
    console.log('Photos reçues :');

    data.photos.forEach((photo, index) => {
      console.log(`  ${index + 1}. ${photo.url}`);
      if (photo.metadata?.gps_lat) {
        console.log(`     GPS : ${photo.metadata.gps_lat}, ${photo.metadata.gps_lng}`);
      }
    });
  }
});

app.listen(3000, () => {
  console.log('Serveur webhook en cours sur le port 3000');
});

Exemple de payload webhook

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Veuillez photographier le colis sous tous les angles",
    "photos": [
      {
        "id": "photo_xyz789",
        "url": "https://storage.visiono.io/photos/xyz789.jpg",
        "metadata": {
          "gps_lat": 45.4642,
          "gps_lng": 9.1900,
          "captured_at": "2024-01-15T10:28:00Z"
        }
      }
    ],
    "submitted_at": "2024-01-15T10:30:00Z"
  }
}

Tester les webhooks

Utilisez webhook.site pour obtenir un point de terminaison temporaire pour les tests. Vous pouvez voir les payloads entrants en temps réel sans configurer de serveur.

Étape 4 : Télécharger les photos

Les URLs de photos dans le payload webhook sont des liens de téléchargement direct :

# Télécharger une photo
curl -O "https://storage.visiono.io/photos/xyz789.jpg"

Ou programmatiquement dans votre gestionnaire de webhook :

const https = require('https');
const fs = require('fs');

function downloadPhoto(url, filename) {
  const file = fs.createWriteStream(filename);
  https.get(url, (response) => {
    response.pipe(file);
    file.on('finish', () => file.close());
  });
}

// Dans votre gestionnaire de webhook
data.photos.forEach((photo, index) => {
  downloadPhoto(photo.url, `photo_${index + 1}.jpg`);
});

Tester votre configuration

Utilisez cette checklist pour vérifier que tout fonctionne :

Test	Comment vérifier
La clé API fonctionne	GET https://www.visiono.io/fr/docs/api/v1/ping retourne 200 OK
Demande créée	La réponse contient request_url et unique_code
Lien accessible	Ouvrez request_url dans le navigateur, l'appareil photo s'active
Webhook configuré	Créez un webhook dans le tableau de bord
Webhook reçoit	L'événement de test arrive à votre point de terminaison
Signature valide	Le gestionnaire retourne 200, pas 401

Test rapide de l'API

# Tester votre clé API
curl -X GET "https://www.visiono.iohttps://www.visiono.io/fr/docs/api/v1/ping" \
  -H "X-API-Key: vsk_live_votre_cle_api_ici"

Réponse attendue :

{
  "message": "pong",
  "timestamp": "2024-01-15T10:00:00Z"
}

Prochaines étapes

Maintenant que vous avez les bases fonctionnelles :

• Webhooks — Configurez tous les événements disponibles
• Liens permanents — Créez des liens réutilisables pour la collecte continue
• Emplacements photo — Demandez des photos spécifiques avec instructions
• Référence API — Documentation complète des points de terminaison

Besoin d'aide ? Consultez la Référence API pour une documentation détaillée des points de terminaison, ou configurez les Webhooks pour tous les événements disponibles.