Inicio Rápido para Desarrolladores

Crea tu primera solicitud de fotos vía API en 5 minutos.

Prerrequisitos

Antes de comenzar, asegúrate de tener:

• Una cuenta de Visiono activa con acceso a API
• Una clave de API creada
• Un endpoint de webhook listo (o usa webhook.site para pruebas)

Paso 1: Crear una Solicitud de Fotos

Usa la API para crear una solicitud de fotos única:

curl -X POST "https://www.visiono.iohttps://www.visiono.io/es/docs/api/v1/photo-requests" \
  -H "X-API-Key: vsk_live_tu_clave_api_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Por favor fotografía el paquete desde todos los lados",
    "expires_in_hours": 24
  }'

Respuesta Esperada

{
  "data": {
    "id": "req_abc123",
    "unique_code": "ABC123",
    "status": "pending",
    "instructions": "Por favor fotografía el paquete desde todos los lados",
    "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": []
  }
}

Campos clave en la respuesta:

Campo	Descripción
id	Identificador único de la solicitud
request_url	Comparte este enlace con tu cliente
unique_code	Código corto para entrada manual en code_entry_url
expires_at	Cuándo expira la solicitud

Paso 2: Compartir el Enlace

Envía el request_url de la respuesta a tu cliente por SMS, email o cualquier canal de mensajería.

Cuando el cliente abre el enlace:

1. Ve tus instrucciones
2. La cámara se activa (sin acceso a galería)
3. Toma las fotos requeridas
4. Las fotos se envían a tu espacio de trabajo

Solo Cámara

Los clientes solo pueden usar la cámara de su dispositivo — sin subidas desde galería. Esto asegura fotos auténticas en tiempo real.

Paso 3: Recibir el Webhook

Cuando se envían fotos, Visiono envía un webhook a tu endpoint configurado.

Configura Tu Manejador de Webhook

Crea un servidor Express simple para recibir 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. Verificar firma
  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('Firma de webhook inválida');
    return res.status(401).send('Firma inválida');
  }

  // 2. Confirmar inmediatamente
  res.status(200).send('OK');

  // 3. Procesar el evento
  const { event, data } = req.body;

  if (event === 'photo_request.submitted') {
    console.log('ID de Solicitud:', data.id);
    console.log('Fotos recibidas:');

    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('Servidor de webhook corriendo en puerto 3000');
});

Ejemplo de Payload de Webhook

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Por favor fotografía el paquete desde todos los lados",
    "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"
  }
}

Probar Webhooks

Usa webhook.site para obtener un endpoint temporal para pruebas. Puedes ver los payloads entrantes en tiempo real sin configurar un servidor.

Paso 4: Descargar Fotos

Las URLs de fotos en el payload del webhook son enlaces de descarga directa:

# Descargar una foto
curl -O "https://storage.visiono.io/photos/xyz789.jpg"

O programáticamente en tu manejador 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());
  });
}

// En tu manejador de webhook
data.photos.forEach((photo, index) => {
  downloadPhoto(photo.url, `foto_${index + 1}.jpg`);
});

Prueba Tu Configuración

Usa esta lista de verificación para verificar que todo funciona:

Prueba	Cómo Verificar
Clave API funciona	GET https://www.visiono.io/es/docs/api/v1/ping devuelve 200 OK
Solicitud creada	Respuesta contiene request_url y unique_code
Enlace accesible	Abre request_url en navegador, cámara se activa
Webhook configurado	Crea webhook en el panel
Webhook recibe	Evento de prueba llega a tu endpoint
Firma válida	Manejador devuelve 200, no 401

Prueba Rápida de API

# Probar tu clave API
curl -X GET "https://www.visiono.iohttps://www.visiono.io/es/docs/api/v1/ping" \
  -H "X-API-Key: vsk_live_tu_clave_api_aqui"

Respuesta esperada:

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

Próximos Pasos

Ahora que tienes lo básico funcionando:

• Webhooks — Configura todos los eventos disponibles
• Enlaces Permanentes — Crea enlaces reutilizables para recolección continua
• Espacios de Fotos — Solicita fotos específicas con instrucciones
• Referencia de API — Documentación completa de endpoints

¿Necesitas ayuda? Consulta la Referencia de API para documentación detallada de endpoints, o configura Webhooks para todos los eventos disponibles.