Brzi početak za programere

Kreirajte svoj prvi zahtjev za fotografije putem API-ja u 5 minuta.

Preduvjeti

Prije nego počnete, osigurajte da imate:

• Aktivni Visiono račun s pristupom API-ju
• Kreirani API ključ
• Webhook krajnju točku spremnu (ili koristite webhook.site za testiranje)

Korak 1: Kreirajte zahtjev za fotografije

Koristite API za kreiranje jednokratnog zahtjeva za fotografije:

curl -X POST "https://www.visiono.iohttps://www.visiono.io/hr/docs/api/v1/photo-requests" \
  -H "X-API-Key: vsk_live_vas_api_kljuc_ovdje" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Molimo fotografirajte paket sa svih strana",
    "expires_in_hours": 24
  }'

Očekivani odgovor

{
  "data": {
    "id": "req_abc123",
    "unique_code": "ABC123",
    "status": "pending",
    "instructions": "Molimo fotografirajte paket sa svih strana",
    "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": []
  }
}

Ključna polja u odgovoru:

Polje	Opis
id	Jedinstveni identifikator zahtjeva
request_url	Podijelite ovaj link s korisnikom
unique_code	Kratki kod za ručni unos na code_entry_url
expires_at	Kada zahtjev istječe

Korak 2: Podijelite link

Pošaljite request_url iz odgovora vašem korisniku putem SMS-a, e-pošte ili bilo kojeg kanala za poruke.

Kada korisnik otvori link:

1. Vidi vaše upute
2. Kamera se aktivira (bez pristupa galeriji)
3. Snimi potrebne fotografije
4. Fotografije se šalju u vaš radni prostor

Samo kamera

Korisnici mogu koristiti samo kameru svog uređaja — bez učitavanja iz galerije. Ovo osigurava autentične fotografije u stvarnom vremenu.

Korak 3: Primite webhook

Kada se fotografije pošalju, Visiono šalje webhook na vašu konfiguriranu krajnju točku.

Postavite webhook handler

Kreirajte jednostavan Express poslužitelj za primanje webhookova:

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. Verificirajte potpis
  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('Nevažeći webhook potpis');
    return res.status(401).send('Nevažeći potpis');
  }

  // 2. Potvrdite odmah
  res.status(200).send('OK');

  // 3. Obradite događaj
  const { event, data } = req.body;

  if (event === 'photo_request.submitted') {
    console.log('ID zahtjeva:', data.id);
    console.log('Primljene fotografije:');

    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 poslužitelj radi na portu 3000');
});

Primjer webhook payloada

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Molimo fotografirajte paket sa svih strana",
    "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"
  }
}

Testiranje webhookova

Koristite webhook.site da dobijete privremenu krajnju točku za testiranje. Možete vidjeti dolazne payloade u stvarnom vremenu bez postavljanja poslužitelja.

Korak 4: Preuzmite fotografije

URL-ovi fotografija u webhook payloadu su direktni linkovi za preuzimanje:

# Preuzmite fotografiju
curl -O "https://storage.visiono.io/photos/xyz789.jpg"

Ili programski u vašem webhook handleru:

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

// U vašem webhook handleru
data.photos.forEach((photo, index) => {
  downloadPhoto(photo.url, `fotografija_${index + 1}.jpg`);
});

Testirajte svoje postavke

Koristite ovu kontrolnu listu za provjeru da sve radi:

Test	Kako provjeriti
API ključ radi	GET https://www.visiono.io/hr/docs/api/v1/ping vraća 200 OK
Zahtjev kreiran	Odgovor sadrži request_url i unique_code
Link dostupan	Otvorite request_url u pregledniku, kamera se aktivira
Webhook konfiguriran	Kreirajte webhook na nadzornoj ploči
Webhook prima	Testni događaj stiže na vašu krajnju točku
Potpis valjan	Handler vraća 200, ne 401

Brzi API test

# Testirajte vaš API ključ
curl -X GET "https://www.visiono.iohttps://www.visiono.io/hr/docs/api/v1/ping" \
  -H "X-API-Key: vsk_live_vas_api_kljuc_ovdje"

Očekivani odgovor:

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

Sljedeći koraci

Sada kada imate osnove koje rade:

• Webhooks — Konfigurirajte sve dostupne događaje
• Trajni linkovi — Kreirajte višekratne linkove za kontinuirano prikupljanje
• Foto slotovi — Zatražite specifične fotografije s uputama
• API referenca — Potpuna dokumentacija krajnjih točaka

Trebate pomoć? Provjerite API referencu za detaljnu dokumentaciju krajnjih točaka, ili konfigurirajte Webhooks za sve dostupne događaje.