Introducción

DVS (Document Validation Service) es la API de OSIGU para automatizar el ciclo de vida de documentos médico-administrativos: clasificarlos por tipo, extraer datos estructurados y validarlos contra reglas de negocio configurables por agreement de aseguradora.

Esta documentación está dirigida a personas de ingeniería que integran su sistema hospitalario, de clínica o de facturación directamente con DVS.

Lo que se puede hacer con DVS

Clasificar un documento

Enviar un PDF o imagen y obtener el tipo de documento — SADT, Pedido Médico, Anatomia Patológica, OPME, entre otros.

Validar un documento

Ejecutar el pipeline completo de extracción + validación. Obtener un veredicto APPROVED / REJECTED con errores detallados por regla.

Recibir resultados vía webhook

Procesamiento asíncrono con callbacks firmados por HMAC. Es posible verificar la signature en cualquier lenguaje con los snippets listos para copiar y pegar.

Autenticar con OAuth2

Grant_type estándar OAuth2 client credentials. Un solo token, múltiples endpoints.

Ideas centrales

Dos endpoints complementarios

Usar classification cuando no se conoce qué tipo de documento se tiene. Usar validation cuando el tipo ya se conoce (el HIS lo etiquetó) y se desea verificar que cumple con las reglas de la aseguradora. También es posible encadenar ambos en una sola llamada pasando auto_validate=true al clasificador.

Validation siempre asíncrono, classification con modo sync disponible

Validation incluye OCR + extracción estructurada y evaluación de reglas — toma entre 15 y 60 segundos. Siempre devuelve 202 Accepted de inmediato y entrega el resultado vía webhook firmado. Classification soporta ambos modos: sync (UX interactiva) y async.

Control de acceso por tenant por tipo de documento y agreement

OSIGU otorga a cada proveedor acceso explícito a combinaciones específicas de (document_type, country_code, agreement_code). Default-deny: no es posible validar nada hasta que OSIGU configure el acceso durante el onboarding.

Webhooks firmados con HMAC

DVS firma cada webhook con HMAC-SHA256 usando un secret compartido durante el onboarding. La signature debe verificarse en el receptor antes de procesar. El mismo mecanismo aplica para eventos de classification y validation.

La API está versionada con /v1/

Todos los endpoints públicos viven bajo /v1/. Los cambios aditivos no incrementan la versión; los cambios incompatibles pasan a /v2/ con una ventana de coexistencia de 6 meses.

A quién está dirigida

DVS está diseñada para proveedores que necesitan alguna de las siguientes capacidades:

• Hospitales y clínicas que desean validar documentos médicos (guías TISS, pedidos médicos, informes de Anatomia Patológica, solicitudes de OPME, etc.) antes de enviarlos a una aseguradora.
• Sistemas de facturación que desean detectar documentos con campos faltantes o inválidos antes de disparar el reembolso.
• Integraciones HIS que ya clasifican documentos internamente, pero quieren aprovechar el motor de extracción + validación de OSIGU sin reconstruirlo.

Si se consume DVS a través de RCM u otro producto de OSIGU, esta documentación no es el punto de entrada — está dirigida a la integración directa por API.

Entornos

DVS ofrece dos entornos independientes. Construir y validar primero contra sandbox — todos los ejemplos de código de esta documentación apuntan a sandbox por defecto.

Sandbox

DVS API: https://dvs-ingestion-api.sandbox.osigu.com

OAuth token: https://sandbox.osigu.com/v1/oauth/token

Pruebas de integración. No facturable. Para usar durante la construcción.

Producción

DVS API: https://dvs-ingestion-api.osigu.com

OAuth token: https://api.osigu.com/v1/oauth/token

Tráfico real. Validaciones reales, facturación real. Migrar después de que sandbox esté en verde.

Cada entorno tiene su propio host de DVS y su propio endpoint OAuth de token. Las credenciales también están limitadas por entorno — el client_id de sandbox no funcionará contra el endpoint OAuth de producción, y viceversa.

Cómo empezar

1. 1Firmar un acuerdo de integración con OSIGU

   El equipo comercial de OSIGU aprovisionará el client_id, client_secret, secret de webhook y configurará el acceso a tipos de documento específicos.

2. 2Implementar la obtención del token OAuth2

   Usar el client credentials grant para obtener un access token. Cachearlo durante ~50 minutos (el TTL del token por defecto es de 1 hora).

3. 3Enviar la primera request

   Seguir el quickstart para clasificar o validar el primer documento en menos de 5 minutos.

4. 4Implementar un receptor de webhooks

   Para flujos asíncronos, exponer un endpoint HTTPS y verificar signatures HMAC. Para probar localmente, usar ngrok.

Soporte

Para onboarding, rotación de secrets o incidentes en producción: support@osigu.com.