Quickstart

Este guia apresenta o caminho mínimo para obter um resultado de classification do DVS. A validation funciona da mesma forma — basta substituir o endpoint no passo 3 e o evento de resultado no passo 5.

Pré-requisitos

É necessário já ter:

• Credenciais de sandbox (client_id e client_secret) emitidas pela OSIGU. Todos os exemplos deste guia apontam para sandbox — ao ir para produção, troque para os hosts de produção (https://dvs-ingestion-api.osigu.com para a API e https://api.osigu.com/v1/oauth/token para o OAuth) e use as credenciais de produção.
• Acesso de rede a partir dos servidores para https://dvs-ingestion-api.sandbox.osigu.com (DVS) e https://sandbox.osigu.com (OAuth).
• Um documento de teste (PDF ou imagem) para classificar.

1. Obtenha um access token

OAuth2 client credentials grant. Envie o client_id:client_secret como HTTP Basic auth e o grant_type como parâmetro de 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"] carrega metadados do tenant, ex.: {"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 carrega metadados do tenant, ex.: { 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" }
}

O access_token é uma string opaca (não é um JWT) válida por ~24 horas por padrão. O mapa extensions carrega metadados sobre o tenant (ex.: provider_slug) — útil para logging e debugging.

Faça cache do token em memória e reutilize-o até próximo à expiração. Não chame o endpoint do OAuth a cada request da API.

Veja Obtendo Access Tokens para a referência completa.

2. Prepare o documento

É possível enviar o documento de três formas:

Inline (base64)

Melhor para arquivos abaixo de 3 MB. Sem setup necessário.

BASE64=$(base64 -i document.pdf)

S3 URL

Quando o documento já está em um bucket S3 gerenciado pela OSIGU. A OSIGU informará o nome do bucket durante o onboarding.

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

External URL

O DVS irá buscar o documento no endpoint HTTPS informado. Precisa estar publicamente acessível.

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

3. Classifique o 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"])  # ex.: "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); // ex.: "SADT"

4. Leia a response

Em caso de sucesso, é retornado 200 OK (sync) ou 202 Accepted (async). A response síncrona tem este formato:

{
  "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
}

O type é um dos 17 tipos de documentos brasileiros — veja Tipos de Documentos para o catálogo completo.

5. (Somente async) Receba o webhook

Caso o modo escolhido seja mode=async, a response é 202 Accepted com o classification_request_id. O DVS envia um webhook assinado ao endpoint registrado quando o processamento é concluído.

A implementação do receiver leva menos de 30 linhas de código em qualquer linguagem. Acesse Implementar Receiver de Webhook para a receita completa com verificação HMAC.

Próximos passos

Validar um documento

Execute o pipeline completo de extração + validation com a mesma autenticação.

Configurar receiver de webhook

Receiver pronto para produção com verificação HMAC, idempotency e tratamento de retry.

Explorar a referência da API

Referência completa dos endpoints com schemas de request/response e painéis "Try it".

Entender erros

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