Schnellstart für Entwickler

Erstellen Sie Ihre erste Fotoanfrage per API in 5 Minuten.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie haben:

• Ein aktives Visiono-Konto mit API-Zugang
• Einen erstellten API-Schlüssel
• Einen Webhook-Endpunkt bereit (oder verwenden Sie webhook.site zum Testen)

Schritt 1: Fotoanfrage erstellen

Verwenden Sie die API, um eine einmalige Fotoanfrage zu erstellen:

curl -X POST "https://www.visiono.iohttps://www.visiono.io/de/docs/api/v1/photo-requests" \
  -H "X-API-Key: vsk_live_ihr_api_schluessel_hier" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Bitte fotografieren Sie das Paket von allen Seiten",
    "expires_in_hours": 24
  }'

Erwartete Antwort

{
  "data": {
    "id": "req_abc123",
    "unique_code": "ABC123",
    "status": "pending",
    "instructions": "Bitte fotografieren Sie das Paket von allen Seiten",
    "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": []
  }
}

Wichtige Felder in der Antwort:

Feld	Beschreibung
id	Eindeutige Anfrage-Kennung
request_url	Diesen Link mit Ihrem Kunden teilen
unique_code	Kurzcode für manuelle Eingabe bei code_entry_url
expires_at	Wann die Anfrage abläuft

Schritt 2: Link teilen

Senden Sie die request_url aus der Antwort an Ihren Kunden per SMS, E-Mail oder einem anderen Messaging-Kanal.

Wenn der Kunde den Link öffnet:

1. Er sieht Ihre Anweisungen
2. Kamera wird aktiviert (kein Galeriezugriff)
3. Er macht die erforderlichen Fotos
4. Fotos werden an Ihren Arbeitsbereich übermittelt

Nur Kamera

Kunden können nur ihre Gerätekamera verwenden — keine Galerie-Uploads. Dies stellt authentische Echtzeit-Fotos sicher.

Schritt 3: Webhook empfangen

Wenn Fotos eingereicht werden, sendet Visiono einen Webhook an Ihren konfigurierten Endpunkt.

Webhook-Handler einrichten

Erstellen Sie einen einfachen Express-Server, um Webhooks zu empfangen:

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. Signatur verifizieren
  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('Ungültige Webhook-Signatur');
    return res.status(401).send('Ungültige Signatur');
  }

  // 2. Sofort bestätigen
  res.status(200).send('OK');

  // 3. Ereignis verarbeiten
  const { event, data } = req.body;

  if (event === 'photo_request.submitted') {
    console.log('Anfrage-ID:', data.id);
    console.log('Fotos erhalten:');

    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('Webhook-Server läuft auf Port 3000');
});

Webhook-Payload-Beispiel

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Bitte fotografieren Sie das Paket von allen Seiten",
    "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"
  }
}

Webhooks testen

Verwenden Sie webhook.site, um einen temporären Endpunkt zum Testen zu erhalten. Sie können eingehende Payloads in Echtzeit sehen, ohne einen Server einzurichten.

Schritt 4: Fotos herunterladen

Foto-URLs im Webhook-Payload sind direkte Download-Links:

# Foto herunterladen
curl -O "https://storage.visiono.io/photos/xyz789.jpg"

Oder programmatisch in Ihrem Webhook-Handler:

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());
  });
}

// In Ihrem Webhook-Handler
data.photos.forEach((photo, index) => {
  downloadPhoto(photo.url, `foto_${index + 1}.jpg`);
});

Setup testen

Verwenden Sie diese Checkliste, um zu verifizieren, dass alles funktioniert:

Test	Wie verifizieren
API-Schlüssel funktioniert	GET https://www.visiono.io/de/docs/api/v1/ping gibt 200 OK zurück
Anfrage erstellt	Antwort enthält request_url und unique_code
Link zugänglich	request_url im Browser öffnen, Kamera aktiviert
Webhook konfiguriert	Webhook erstellen im Dashboard
Webhook empfängt	Test-Ereignis kommt an Ihrem Endpunkt an
Signatur gültig	Handler gibt 200 zurück, nicht 401

Schneller API-Test

# Ihren API-Schlüssel testen
curl -X GET "https://www.visiono.iohttps://www.visiono.io/de/docs/api/v1/ping" \
  -H "X-API-Key: vsk_live_ihr_api_schluessel_hier"

Erwartete Antwort:

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

Nächste Schritte

Jetzt, da Sie die Grundlagen haben:

• Webhooks — Alle verfügbaren Ereignisse konfigurieren
• Permanente Links — Wiederverwendbare Links für laufende Sammlung erstellen
• Foto-Slots — Spezifische Fotos mit Anweisungen anfordern
• API-Referenz — Vollständige Endpunkt-Dokumentation

Brauchen Sie Hilfe? Prüfen Sie die API-Referenz für detaillierte Endpunkt-Dokumentation, oder konfigurieren Sie Webhooks für alle verfügbaren Ereignisse.