Validar um Documento

Use este endpoint quando o tipo do documento já for conhecido (o HIS marcou, o operador selecionou manualmente, etc.) e o objetivo seja que o DVS:

1. Extraia dados estruturados do arquivo.
2. Aplique o rule set de validation configurado para (document_type, country_code, agreement_code).
3. Opcionalmente, chame validadores externos (consulta CRM, validação de CID, elegibilidade).
4. Retorne APPROVED / REJECTED com erros detalhados.

Sempre async. O resultado é entregue via webhook assinado.

Passo 1: Descobrir o que é possível validar

Chame GET /v1/document-types para listar as combinações autorizadas para o tenant:

curl https://dvs-ingestion-api.sandbox.osigu.com/v1/document-types \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response:

{
  "items": [
    { "document_type_slug": "PM", "display_name": "Pedido Médico", "country_code": "BR", "agreement_code": "BRADESCO_xxx" },
    { "document_type_slug": "SADT", "display_name": "Guia SP/SADT", "country_code": "BR", "agreement_code": null }
  ],
  "total": 2
}

Um agreement_code null significa wildcard — é possível validar esse tipo com qualquer agreement daquele país.

Passo 2: Enviar a validation request

curl

curl -X POST https://dvs-ingestion-api.sandbox.osigu.com/v1/provider-validation-requests \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: val-$(uuidgen)" \
  -d "{
    \"file\": {
      \"content_base64\": \"$BASE64\",
      \"mime_type\": \"application/pdf\"
    },
    \"document_type\": \"PM\",
    \"country_code\": \"BR\",
    \"agreement_code\": \"BRADESCO_xxx\",
    \"external_ref_id\": \"ORDER-12345\"
  }"

Python

import httpx, uuid

def validate_document(access_token, base64_content, doc_type, agreement_code, external_ref_id):
    response = httpx.post(
        "https://dvs-ingestion-api.sandbox.osigu.com/v1/provider-validation-requests",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Idempotency-Key": f"val-{uuid.uuid4()}",
        },
        json={
            "file": {"content_base64": base64_content, "mime_type": "application/pdf"},
            "document_type": doc_type,
            "country_code": "BR",
            "agreement_code": agreement_code,
            "external_ref_id": external_ref_id,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Passo 3: Resolução de agreement_code

Se o tenant tem...	E você...	Resultado
Um único acesso para o tipo de documento	Omite agreement_code	O DVS resolve automaticamente para esse único agreement. agreement_resolution: "auto_unique" na response.
Múltiplos acessos para o tipo de documento	Omite agreement_code	422 com available_agreements em additional_information. Reenvie com valor explícito.
Acesso wildcard (null)	Omite agreement_code	O DVS usa o rule set wildcard. agreement_resolution: "wildcard" na response.
Sem acesso para o tipo de documento	Qualquer	403 071-403-document-type-not-allowed.

Passo 4: Aguardar o webhook

{
  "event_type": "validation.completed",
  "data": {
    "validation_request_id": "660e8400-...",
    "final_status": "APPROVED",
    "summary": {
      "total_validations": 13,
      "validations_passed": 12,
      "validations_failed": 0,
      "validations_skipped": 1
    },
    "errors": [],
    "external_validations": [...]
  }
}

Consulte validation.completed para o schema completo do payload e como interpretar final_status.

Padrões comuns

Não faça classification duplicada

Se já há um validation_request_id proveniente do encadeamento com auto_validate=true, não chame este endpoint com o mesmo documento. Seriam cobradas extração + validation duas vezes.

Defina available_fields_for_ai_analysis apenas se necessário

Por padrão, o DVS executa todas as regras. O parâmetro available_fields_for_ai_analysis é um filtro opcional para restringir quais campos são extraídos e validados. Use com parcimônia — excluir campos críticos pode fazer com que a validation deixe passar problemas reais.

REJECTED ≠ erro

final_status=REJECTED é uma operação bem-sucedida que retorna um veredito negativo. Trate como informação acionável, não como falha.