Classificar um Documento

Este guia descreve uma request de classificação completa — do token ao resultado — com código pronto para produção.

Passo 1: Obter um access token

Caso não haja um token em cache, é necessário obter um. Consulte Obtenção de Access Tokens para as funções auxiliares.

Passo 2: Escolher a origem do arquivo

Inline (base64)

Mais simples para arquivos menores que 3 MB. Não requer configuração adicional.

S3 URL

Arquivos já presentes em um bucket gerenciado pela OSIGU. O nome do bucket é fornecido durante o onboarding.

URL externa

O DVS irá buscar o arquivo no endpoint HTTPS informado. Deve ser publicamente acessível e passar pelo guard SSRF do DVS (sem faixas de IP privado).

Passo 3: Chamar o 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();
}

Passo 4: Tratar a 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"
}

Aguarde o webhook classification.completed (ou faça polling via GET /v1/classification-requests/{id}).

Passo 5: (Opcional) Processar a validation encadeada

Caso seja enviado auto_validate: true e o tipo resultante não seja UNKNOWN, o DVS dispara automaticamente a validation. Será recebido um segundo webhook — validation.completed — compartilhando o mesmo correlation_id.

Padrões comuns

Quando usar sync vs async

Sync: UI interativa em que o usuário está aguardando (tela de upload, revisão de documento). Limita o arquivo a 3 MB. Recomendado quando a latência é crítica.

Async: processamento em batch, fluxos em background, arquivos >3 MB. Sem restrição de latência de UX.

Sempre definir external_ref_id

Utilize o ID interno (pedido, sinistro, file id). O DVS persiste e retorna esse valor em todos os eventos. Permite correlacionar sem expor IDs internos em URLs.

Sempre definir Idempotency-Key

Use um UUID gerado no client. Caso a mesma request seja reenviada por falha de rede, o DVS faz deduplicação e retorna o resultado original sem reprocessar.

Trate UNKNOWN com elegância

Quando type=UNKNOWN, o DVS não conseguiu classificar com confiança. Não trate como erro — encaminhe ao operador para revisão manual ou aplique heurísticas próprias como fallback.