Introdução

DVS (Document Validation Service) é a API da OSIGU para automatizar o ciclo de vida de documentos médico-administrativos: classificando-os por tipo, extraindo dados estruturados e validando-os contra regras de negócio configuráveis por agreement de operadora.

Esta documentação destina-se a engenheiros que integram seu sistema hospitalar, clínica ou sistema de faturamento diretamente ao DVS.

O que é possível fazer com o DVS

Classificar um documento

Envie um PDF ou imagem e receba de volta o tipo do documento — SADT, Pedido Médico, Anatomia Patológica, OPME e outros.

Validar um documento

Execute o pipeline completo de extração + validation. Obtenha um veredito APPROVED / REJECTED com erros detalhados por regra.

Receber resultados via webhook

Processamento assíncrono com callbacks assinados por HMAC. Verifique a signature em qualquer linguagem com nossos snippets prontos para usar.

Autenticar com OAuth2

OAuth2 client credentials grant padrão. Um token, múltiplos endpoints.

Conceitos centrais

Dois endpoints complementares

Use classification quando não se sabe qual o tipo de documento. Use validation quando o tipo já é conhecido (o HIS já marcou) e deseja-se verificar se atende às regras da operadora. Também é possível encadear ambos em uma única chamada passando auto_validate=true para o classificador.

Sempre assíncrono na validation, síncrono disponível na classification

A validation inclui OCR + extração estruturada e avaliação de regras — leva de 15 a 60 segundos. Sempre retorna 202 Accepted imediatamente e entrega o resultado via webhook assinado. A classification suporta tanto modos sync (UX interativa) quanto async.

Controle de acesso por tenant, tipo de documento e agreement

A OSIGU concede a cada provider acesso explícito a combinações específicas de (document_type, country_code, agreement_code). Default-deny: não é possível validar nada até que a OSIGU configure o acesso durante o onboarding.

Webhooks assinados com HMAC

O DVS assina cada webhook com HMAC-SHA256 usando um secret compartilhado no onboarding. Verifique a signature no receiver antes de processar. O mesmo mecanismo serve para eventos de classification e validation.

A API é versionada com /v1/

Todos os endpoints públicos ficam sob /v1/. Mudanças aditivas não alteram a versão; mudanças que quebram compatibilidade vão para /v2/ com uma janela de coexistência de 6 meses.

Para quem é

O DVS foi construído para providers que precisam de qualquer um dos seguintes:

• Hospitais e clínicas que querem validar documentos médicos (guias TISS, pedidos médicos, laudos de anatomia patológica, solicitações de OPME, etc.) antes de submeter a uma operadora.
• Sistemas de faturamento que querem sinalizar documentos com campos ausentes ou inválidos antes de disparar o reembolso.
• Integrações com HIS que já classificam documentos internamente mas querem o motor de extração + validation da OSIGU sem precisar reconstruí-lo.

Se o consumo do DVS for feito através do RCM ou outro produto OSIGU, esta documentação não é o ponto de entrada — ela é destinada à integração direta com a API.

Ambientes

O DVS fornece dois ambientes independentes. Construa e valide primeiro contra o sandbox — todo exemplo de código nesta documentação aponta por padrão para o sandbox.

Sandbox

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

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

Testes de integração. Não tarifado. Use durante a construção.

Produção

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

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

Tráfego real. Validations reais, billing real. Migre após o sandbox estar aprovado.

Cada ambiente tem seu próprio host DVS e seu próprio endpoint de OAuth token. As credenciais também são escopadas por ambiente — o client_id de sandbox não funcionará contra o endpoint OAuth de produção, e vice-versa.

Começando

1. 1Assine um contrato de integração com a OSIGU

   O time comercial da OSIGU provisionará o client_id, client_secret, webhook secret e configurará o acesso a tipos específicos de documentos.

2. 2Implemente a obtenção do OAuth2 token

   Use o client credentials grant para obter um access token. Faça cache por ~50 minutos (o TTL padrão do token é de 1 hora).

3. 3Envie sua primeira request

   Siga o quickstart para classificar ou validar o primeiro documento em menos de 5 minutos.

4. 4Implemente um receiver de webhook

   Para fluxos assíncronos, exponha um endpoint HTTPS e verifique signatures HMAC. Teste localmente com ngrok.

Suporte

Para onboarding, rotação de secrets ou incidentes em produção: support@osigu.com.