Quickstart

Esta guía recorre el camino mínimo para obtener un resultado de classification desde DVS. Validation funciona igual — basta reemplazar el endpoint del paso 3 y el evento de resultado del paso 5.

Prerrequisitos

Es necesario contar previamente con:

• Credenciales de sandbox (client_id y client_secret) emitidas por OSIGU. Todos los ejemplos de esta guía apuntan a sandbox — al pasar a producción, cambiar a los hosts de producción (https://dvs-ingestion-api.osigu.com para la API y https://api.osigu.com/v1/oauth/token para OAuth) y usar las credenciales de producción.
• Acceso de red desde los servidores hacia https://dvs-ingestion-api.sandbox.osigu.com (DVS) y https://sandbox.osigu.com (OAuth).
• Un documento de prueba (PDF o imagen) para clasificar.

1. Obtener un access token

Grant_type OAuth2 client credentials. Enviar client_id:client_secret como HTTP Basic auth y grant_type como parámetro en el query string:

curl

curl --location --request POST \
  "https://sandbox.osigu.com/v1/oauth/token?grant_type=client_credentials" \
  --header "Authorization: Basic $(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)"

Python

import httpx, base64

basic = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()
token_response = httpx.post(
    "https://sandbox.osigu.com/v1/oauth/token",
    params={"grant_type": "client_credentials"},
    headers={"Authorization": f"Basic {basic}"},
)
data = token_response.json()
access_token = data["access_token"]
# data["extensions"] contiene metadatos del tenant, p. ej. {"provider_slug": "br-gamma"}

Node.js

const basic = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
const tokenResponse = await fetch(
  "https://sandbox.osigu.com/v1/oauth/token?grant_type=client_credentials",
  {
    method: "POST",
    headers: { Authorization: `Basic ${basic}` },
  },
);
const data = await tokenResponse.json();
const accessToken = data.access_token;
// data.extensions contiene metadatos del tenant, p. ej. { provider_slug: "br-gamma" }

Response:

{
  "access_token": "7dd4f350-676e-4257-9d7b-f3c5ac4dfi14",
  "token_type": "bearer",
  "expires_in": 86399,
  "scope": "read write",
  "extensions": { "provider_slug": "br-gamma" }
}

El access_token es una cadena opaca (no un JWT), válida por ~24 horas por defecto. El mapa extensions lleva metadatos del tenant (p. ej., provider_slug) — útiles para logging y debugging.

Cachear el token en memoria y reutilizarlo hasta acercarse a la expiración. No golpear el endpoint OAuth en cada llamada a la API.

Ver Obtención de Access Tokens para la referencia completa.

2. Preparar el documento

Es posible enviar el documento de una de tres formas:

Inline (base64)

Recomendado para archivos de menos de 3 MB. No requiere configuración previa.

BASE64=$(base64 -i document.pdf)

S3 URL

Si el documento ya vive en un bucket S3 gestionado por OSIGU. OSIGU indicará el nombre del bucket durante el onboarding.

s3://osigu-dvs-documents-prod/incoming/your-key.pdf

External URL

DVS descargará el documento desde el endpoint HTTPS provisto. Debe ser accesible públicamente.

https://your-storage.example.com/secure/doc.pdf

3. Clasificar el documento

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\": \"sync\",
    \"file\": {
      \"content_base64\": \"$BASE64\",
      \"mime_type\": \"application/pdf\"
    },
    \"country_code\": \"BR\",
    \"external_ref_id\": \"my-internal-id-12345\"
  }"

Python

import httpx, uuid

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": "sync",
        "file": {"content_base64": base64_str, "mime_type": "application/pdf"},
        "country_code": "BR",
        "external_ref_id": "my-internal-id-12345",
    },
    timeout=30,
)
result = response.json()
print(result["type"])  # p. ej., "SADT"

Node.js

import crypto from "node:crypto";

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: "sync",
      file: { content_base64: base64Str, mime_type: "application/pdf" },
      country_code: "BR",
      external_ref_id: "my-internal-id-12345",
    }),
  },
);
const result = await response.json();
console.log(result.type); // p. ej., "SADT"

4. Leer la response

En caso de éxito se obtiene un 200 OK (sync) o 202 Accepted (async). La response sync se ve así:

{
  "classification_request_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "SADT",
  "status": "COMPLETED",
  "classifier_slug": "br-default-v1",
  "mode": "sync",
  "auto_validate": false,
  "validation_request_id": null,
  "external_ref_id": "my-internal-id-12345",
  "timestamp": "2026-06-03T17:42:18.224Z",
  "duration_ms": 3187
}

El type es uno de los 17 tipos de documento brasileños — ver Tipos de Documento para el catálogo completo.

5. (Solo async) Recibir el webhook

Si se eligió mode=async, la response es 202 Accepted con el classification_request_id. DVS envía un webhook firmado al endpoint registrado cuando el procesamiento se completa.

Implementar el receptor toma menos de 30 líneas de código en cualquier lenguaje. Saltar a Implementar Receptor de Webhooks para la receta completa con verificación HMAC.

Qué sigue

Validar un documento

Ejecutar el pipeline completo de extracción + validación con la misma autenticación.

Configurar receptor de webhooks

Receptor listo para producción con verificación HMAC, idempotency y manejo de retry.

Explorar la API reference

Referencia completa de endpoints con schemas de request/response y paneles "Try it".

Entender los errores

Códigos de error, política de retry, idempotency.