Clasificar un Documento

Esta guía recorre una solicitud completa de classification — desde el token hasta el resultado — con código listo para producción.

Paso 1: Obtener un access_token

Si no se cuenta con un token en caché, es necesario obtener uno. Ver Obtención de Access Tokens para las funciones auxiliares.

Paso 2: Elegir una fuente de archivo

Inline (base64)

Lo más sencillo para archivos menores a 3 MB. Sin configuración adicional.

S3 URL

Archivos que ya se encuentran en un bucket administrado por OSIGU. El nombre del bucket se proporciona durante el onboarding.

URL externa

DVS descargará el archivo desde el endpoint HTTPS. Debe ser accesible públicamente y pasar la protección SSRF de DVS (sin rangos de IP privadas).

Paso 3: Llamar al endpoint

curl

curl -X POST https://dvs-ingestion-api.sandbox.osigu.com/v1/classification-requests \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-$(uuidgen)" \
  -d "{
    \"mode\": \"async\",
    \"file\": {
      \"content_base64\": \"$BASE64\",
      \"mime_type\": \"application/pdf\"
    },
    \"country_code\": \"BR\",
    \"external_ref_id\": \"ORDER-12345\",
    \"auto_validate\": true
  }"

Python

import httpx, uuid

def classify_document(access_token: str, base64_content: str, external_ref_id: str):
    response = httpx.post(
        "https://dvs-ingestion-api.sandbox.osigu.com/v1/classification-requests",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Idempotency-Key": f"req-{uuid.uuid4()}",
        },
        json={
            "mode": "async",
            "file": {"content_base64": base64_content, "mime_type": "application/pdf"},
            "country_code": "BR",
            "external_ref_id": external_ref_id,
            "auto_validate": True,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Node.js

import crypto from "node:crypto";

async function classifyDocument(accessToken, base64Content, externalRefId) {
  const response = await fetch(
    "https://dvs-ingestion-api.sandbox.osigu.com/v1/classification-requests",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `req-${crypto.randomUUID()}`,
      },
      body: JSON.stringify({
        mode: "async",
        file: { content_base64: base64Content, mime_type: "application/pdf" },
        country_code: "BR",
        external_ref_id: externalRefId,
        auto_validate: true,
      }),
    },
  );
  if (!response.ok) {
    throw new Error(`Classification failed: ${response.status}`);
  }
  return await response.json();
}

Paso 4: Procesar la response

Modo sync (200 OK)

{
  "classification_request_id": "550e8400-...",
  "type": "SADT",
  "status": "COMPLETED",
  "duration_ms": 3187,
  "validation_request_id": null
}

Modo async (202 Accepted)

{
  "classification_request_id": "550e8400-...",
  "status": "RECEIVED",
  "mode": "async"
}

Es necesario esperar el webhook classification.completed (o hacer polling vía GET /v1/classification-requests/{id}).

Paso 5: (Opcional) Procesar la validation encadenada

Si se envió auto_validate: true y el tipo de resultado no es UNKNOWN, DVS dispara automáticamente la validation. Se recibirá un segundo webhook — validation.completed — compartiendo el mismo correlation_id.

Patrones comunes

Cuándo usar sync vs async

Sync: interfaces interactivas donde el usuario está esperando (pantalla de carga de archivo, revisión de documento). Limita el archivo a 3 MB. Usar cuando la latencia importa.

Async: procesamiento por lotes, workflows en segundo plano, archivos mayores a 3 MB. Sin restricción de latencia para UX.

Siempre definir external_ref_id

Usar el ID interno (orden, claim, id de archivo). DVS lo persiste y lo retorna en cada evento. Permite correlacionar sin exponer los IDs internos en las URLs.

Siempre definir Idempotency-Key

Usar un UUID generado del lado del cliente. Si el mismo request se reintenta por una falla de red, DVS lo deduplica y retorna el resultado original sin reprocesar.

Manejar UNKNOWN con elegancia

Cuando type=UNKNOWN, DVS no pudo clasificar con confianza. No debe tratarse como un error — se debe exponer al operador para revisión manual o aplicar heurísticas propias.