Validar un Documento

Usar este endpoint cuando ya se sabe qué tipo de documento se tiene (el HIS lo etiquetó, el operador lo seleccionó manualmente, etc.) y se busca que DVS:

1. Extraiga datos estructurados del archivo.
2. Aplique el conjunto de reglas de validation configurado para (document_type, country_code, agreement_code).
3. Opcionalmente llame validators externos (consulta de CRM, validation de CID, elegibilidad).
4. Retorne APPROVED / REJECTED con errores detallados.

Siempre async. El resultado se entrega vía webhook firmado.

Paso 1: Descubrir qué se puede validar

Llamar a GET /v1/document-types para listar las combinaciones para las cuales el tenant está autorizado:

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
}

Un agreement_code en null significa wildcard — es posible validar ese tipo con cualquier agreement de ese país.

Paso 2: Enviar la 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()

Paso 3: Manejar la resolución de agreement_code

Si el tenant tiene...	Y se...	Resultado
Un acceso para el tipo de documento	Omite agreement_code	DVS auto-resuelve a ese único agreement. agreement_resolution: "auto_unique" en la response.
Múltiples accesos para el tipo de documento	Omite agreement_code	422 con available_agreements en additional_information. Reenviar con valor explícito.
Acceso wildcard (null)	Omite agreement_code	DVS usa el conjunto de reglas wildcard. agreement_resolution: "wildcard" en la response.
Sin acceso para el tipo de documento	Cualquier caso	403 071-403-document-type-not-allowed.

Paso 4: Esperar el 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": [...]
  }
}

Ver validation.completed para el esquema completo del payload y cómo interpretar final_status.

Patrones comunes

No clasificar dos veces

Si ya se tiene un validation_request_id proveniente del encadenamiento con auto_validate=true, no se debe llamar también a este endpoint con el mismo documento. Se pagaría dos veces la extracción + validation.

Definir available_fields_for_ai_analysis solo si es necesario

Por defecto DVS ejecuta todas las reglas. El parámetro available_fields_for_ai_analysis es un filtro opt-in para restringir qué campos se extraen y validan. Usar con moderación — si se excluyen campos críticos, la validation puede pasar por alto problemas reales.

REJECTED no es un error

final_status=REJECTED es una operación exitosa que entrega un veredicto negativo. Tratarlo como información accionable, no como una falla.