API de Assinatura para Saúde e Telemedicina

Saúde e telemedicina movimentam um fluxo intenso de documentos que precisam de assinatura com validade jurídica: termo de consentimento livre e esclarecido (TCLE), prescrição e receita eletrônica, atestados, laudos e prontuário. Diferente de outros setores, a área médica tem uma regra dura: o Conselho Federal de Medicina exige certificado ICP-Brasil para que documentos médicos digitais tenham validade plena. Uma API de assinatura para saúde precisa, ao mesmo tempo, aplicar assinatura qualificada, garantir identidade forte do paciente e tratar dados sensíveis sob a LGPD.

Este guia mostra como uma API de assinatura digital resolve esse conjunto de requisitos de forma programática: do TCLE coletado dentro da plataforma de teleconsulta à prescrição assinada com ICP-Brasil que o paciente dispensa na farmácia. Vamos detalhar os documentos típicos, os perfis de assinatura corretos para cada um, a trilha de auditoria, a integração com prontuário e um fluxo completo de teleconsulta até a receita assinada.

O público aqui é técnico: desenvolvedores e líderes de engenharia de healthtechs, plataformas de telemedicina, clínicas e operadoras que precisam embutir assinatura em seus produtos sem reinventar a parte regulatória.

O que torna a saúde um caso especial de assinatura

Na maioria dos setores, é possível escolher livremente entre assinatura simples, avançada ou qualificada conforme o risco do documento. Na saúde, parte dessa liberdade desaparece por exigência regulatória.

O Conselho Federal de Medicina, ao regulamentar o documento médico digital, estabeleceu que prescrições, atestados, laudos e demais documentos médicos eletrônicos devem ser assinados com certificado digital no padrão ICP-Brasil para terem validade sem a necessidade de assinatura manuscrita posterior. Em termos da legislação brasileira, isso significa assinatura qualificada, amparada pela MP 2.200-2/2001, que institui a Infraestrutura de Chaves Públicas Brasileira.

Ao mesmo tempo, todo documento de saúde carrega dados pessoais sensíveis na definição da LGPD. Isso eleva o nível de cuidado com base legal, retenção, criptografia e atendimento aos direitos do titular. Não basta assinar: é preciso assinar tratando o dado corretamente.

Documentos de saúde e o perfil de assinatura correto

O primeiro passo de qualquer integração é mapear cada tipo de documento ao perfil de assinatura adequado. A tabela abaixo resume os casos mais comuns e a recomendação de perfil. Para entender em profundidade cada nível, veja o guia de níveis de assinatura: qualificada, avançada e simples.

Note que DIGITAL_CERTIFICATE é o valor de profile usado para acionar a assinatura com certificado ICP-Brasil, que cobre tanto o A1 (certificado em arquivo) quanto o A3 (token ou cartão em hardware). O passo correspondente que aparece na resposta da API é o DIGITAL_SIGN_A1, e a classe real do certificado utilizado fica registrada no resultado da assinatura, não no perfil.

Identidade forte: quem assina é quem diz ser

Em saúde, a identidade do signatário não é detalhe burocrático: é o que sustenta a responsabilidade clínica e a defesa em eventual litígio. A API trata identidade compondo métodos de autenticação por etapa, descritos em detalhe no guia de métodos de autenticação da API.

Para o médico

O certificado ICP-Brasil já carrega CPF e nome do profissional na titularidade, de modo que o passo DIGITAL_SIGN_A1 vincula a assinatura a uma identidade verificada por uma Autoridade Certificadora. Esse é o nível máximo de garantia de autoria e é justamente o que o CFM exige para documentos médicos.

Para o paciente

O paciente nem sempre possui certificado ICP-Brasil, então a identidade forte é montada combinando métodos:

• OTP_CHALLENGE — código de uso único por SMS ou e-mail, confirmando posse do canal de contato.
• BIOMETRIC_LIVENESS — prova de vida facial, garantindo que há uma pessoa real e presente.
• BIOMETRIC_MATCH — confronto facial contra um documento de identidade, quando se quer ligar o rosto a um CPF.
• CLICK_ACCEPT — aceite clickwrap, geralmente como camada complementar ao registro de ciência.

Cada método executado entra na trilha de auditoria com carimbo temporal, IP e geolocalização. Esse registro é o que transforma um simples PDF assinado em prova robusta de consentimento — o racional completo dessa autenticação em consultas remotas está em autenticação forte para consentimento em telemedicina.

LGPD para dados sensíveis de saúde

Dados de saúde são categoria de dado sensível sob a LGPD, com base legal mais restrita do que dados comuns. O tratamento exige fundamento específico, como o consentimento destacado do titular ou a tutela da saúde exercida por profissional habilitado. Uma integração de assinatura precisa respeitar isso por desenho.

A recomendação arquitetural é clara: mantenha o conteúdo clínico no seu prontuário e deixe a API processar apenas o documento a ser assinado e suas evidências. A SignDocs é LGPD-first e documenta publicamente o tratamento: a Tabela de Retenção define prazos de guarda por categoria de dado (incluindo dados de saúde), a Central de Confiança reúne DPA e demais instrumentos, e o canal do DPO atende requisições de acesso, correção ou eliminação — o que dá respaldo documental para responder ao paciente dentro do prazo legal.

Boas práticas que se aplicam ao contexto de saúde:

• Minimização: envie à API só o necessário para assinar; evite trafegar histórico clínico completo dentro do PDF de coleta de assinatura quando não for indispensável.
• Criptografia: dados em trânsito (TLS) e em repouso; para clientes regulados, há suporte a mTLS na camada enterprise.
• Base legal registrada: documente, no fluxo, qual base ampara cada tratamento (consentimento do TCLE, tutela da saúde, execução de contrato).
• Retenção controlada: defina por quanto tempo cada artefato é mantido; o prontuário tem prazos legais próprios de guarda.

Fluxo completo: da teleconsulta à prescrição assinada

Vamos percorrer o caminho mais comum em telemedicina, conectando os conceitos acima a chamadas reais. O ciclo de vida transacional completo está detalhado no guia de fluxo transacional da API; aqui aplicamos ao contexto clínico.

1. Início da teleconsulta: paciente e médico entram na sala de vídeo da sua plataforma. Antes de iniciar, o sistema precisa coletar o TCLE.
2. Coleta do TCLE com identidade forte: a plataforma cria uma sessão de Assinatura Expressa para o paciente, embutida em iframe na própria tela da teleconsulta.
3. Atendimento clínico: a consulta acontece. O médico decide a conduta e gera a prescrição no prontuário.
4. Assinatura da prescrição com ICP-Brasil: o prontuário envia o PDF da receita à API com perfil DIGITAL_CERTIFICATE; o médico assina com seu certificado ICP-Brasil.
5. Entrega ao paciente: a receita assinada (PAdES, com carimbo de hora do servidor e trilha de auditoria) é entregue ao paciente, que pode dispensá-la na farmácia.
6. Arquivamento e auditoria: um webhook notifica a conclusão; a plataforma baixa o documento assinado e o evidence pack e os arquiva junto ao registro do paciente.

Passo 2 — TCLE via Assinatura Expressa embutida

Uma única chamada cria a sessão de assinatura do paciente. O retorno traz a URL que você abre em iframe:

A resposta inclui a url da sessão e o clientSecret. Lembre-se de que a URL sozinha não é o link final: ela precisa ser combinada com o clientSecret como parâmetro de consulta para montar o endereço que abre o widget de assinatura. O perfil BIOMETRIC_PLUS_OTP compõe prova de vida facial com código de uso único, formando a identidade forte do paciente para o consentimento.

Passo 4 — Prescrição assinada com certificado ICP-Brasil

Para a receita, o perfil muda para DIGITAL_CERTIFICATE, pois o documento é médico e o CFM exige ICP-Brasil. O signatário é o próprio médico:

Passo 6 — Webhook de conclusão e arquivamento

Quando o documento é assinado, a API dispara um webhook. Seu prontuário escuta o evento, baixa o PDF assinado e o evidence pack, e os arquiva. O mecanismo de eventos, com verificação HMAC e idempotência, está detalhado no guia de webhooks e eventos da API.

Trilha de auditoria e prova jurídica

Para a clínica, o que protege juridicamente não é só o PDF assinado, mas o conjunto de evidências que comprova quem assinou, como, quando e de onde. Cada documento gera um evidence pack no formato .p7m, um contêiner PKCS#7/CMS que reúne assinatura, certificados, o hash SHA-256 do documento, o carimbo de hora do servidor e a trilha completa de autenticação. Os padrões e formatos estão descritos no guia de PKCS#7/CMS, PAdES e CAdES, e a estrutura do pacote probatório no guia de evidence pack e prova jurídica.

Pontos relevantes para o setor de saúde:

• PAdES para PDFs: prescrições e atestados em PDF recebem assinatura embarcada no padrão PAdES (nível baseline B), com a cadeia de certificados ICP-Brasil para arquivamento por anos.
• Carimbo de hora do servidor e trilha de auditoria: a data e a hora da assinatura são registradas pelos servidores da SignDocs (ISO-8601) e fixadas na trilha de auditoria append-only junto ao hash SHA-256 do documento, importante para atestados e prazos clínicos.
• Verificação pública: qualquer farmácia, convênio ou perito pode validar a receita no verificador público, sem login, confirmando integridade e autoria.

Integração com prontuário e plataformas de telemedicina

A API é REST e agnóstica de linguagem, com SDKs oficiais em TypeScript/Node, Python, Go, Java, PHP e C#/.NET, o que cobre a esmagadora maioria dos prontuários eletrônicos e sistemas hospitalares do mercado brasileiro. Para linguagens sem SDK dedicado, o REST direto resolve.

Padrão de integração recomendado

1. Geração no prontuário: seu sistema renderiza o PDF do documento (TCLE, receita, atestado) a partir dos dados clínicos.
2. Envio para assinatura: o PDF segue para a API com o perfil adequado e metadados (CRM, ID da consulta, tipo de documento).
3. Coleta: conforme o caso, embutida em iframe na teleconsulta (Assinatura Expressa) ou via envelope multi-signatário (Transaction API).
4. Retorno via webhook: o documento assinado e o evidence pack voltam por evento; nenhum dado clínico além do documento precisa transitar.
5. Arquivamento: os artefatos são guardados junto ao registro do paciente, respeitando os prazos legais de retenção do prontuário.

Duas superfícies de API, dois cenários

A SignDocs oferece duas formas de integração que se complementam bem no contexto de saúde:

• Assinatura Expressa (Signing Sessions): POST /v1/signing-sessions resolve em uma chamada o caso de um documento e um signatário — ideal para o TCLE embutido na teleconsulta e para a prescrição assinada pelo médico.
• API de envelopes: para fluxos com múltiplos signatários no mesmo documento (por exemplo, paciente, responsável legal e médico em um termo de procedimento), com até 100 signatários, ciclo de vida completo e ordem de assinatura controlada — veja o guia de ordem de assinatura.

Esse mesmo modelo de integração se aplica a outros setores regulados. Vale comparar com as abordagens descritas para fintechs, para RH e admissão digital e para imobiliárias — os padrões de identidade, webhook e evidence pack se repetem, mudando apenas o perfil de assinatura e a base legal aplicável.

Ambiente de homologação e boas práticas de implantação

Antes de produção, valide o fluxo no ambiente de homologação, cujo host base é api-hml.signdocs.com.br (note a forma com hífen). Nesse ambiente, as entidades têm TTL de 7 dias, o que é perfeito para testes de integração sem acúmulo de dados de teste.

• Autenticação: obtenha o token via OAuth2 client-credentials; o JWT é assinado com ECDSA (ES256), expira em 15 minutos e as chaves residem em KMS.
• Teste cada perfil: valide separadamente o TCLE com identidade forte e a prescrição com DIGITAL_CERTIFICATE, conferindo o evidence pack de cada um.
• Verifique no verificador público: confirme que a receita gerada em HML valida corretamente antes de liberar para a farmácia em produção.
• Webhooks seguros: implemente verificação HMAC-SHA256 e idempotência no receptor antes de ir ao ar.

Sobre planos e custos

O acesso à API é contratado como plano sob medida, dimensionado pelo time comercial conforme o volume de documentos e os perfis de assinatura usados (assinatura com ICP-Brasil e biometria têm requisitos próprios) — o ambiente de homologação é gratuito para validar a integração antes de qualquer contrato. Os planos da página de planos cobrem o aplicativo web/mobile e não incluem acesso à API. Entenda os modelos do mercado em quanto custa uma API de assinatura.

Perguntas Frequentes