Começando

Este guia ajudará você a integrar a API de transcrição médica da TranscriMed em sua aplicação de saúde em apenas alguns passos.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Uma aplicação ou sistema de saúde que requer transcrição médica
• Conhecimento básico de APIs REST e OAuth2
• Ambiente de desenvolvimento configurado para sua linguagem de programação preferida

Passo 1: Registrar Sua Aplicação

1. Criar Conta de Desenvolvedor: Visite o Portal do Desenvolvedor TranscriMed e crie uma conta
2. Registrar Sua Aplicação: Preencha o formulário de registro da aplicação
3. Obter Suas Credenciais: Você receberá:
   • Client ID: Identificador único da sua aplicação
   • Client Secret: Mantenha isso seguro e nunca exponha em código do lado do cliente
   • Redirect URI: Para onde os usuários serão redirecionados após autorização

dica

Armazene suas credenciais de cliente com segurança. Nunca as confirme no controle de versão ou as exponha em código do lado do cliente.

Passo 2: Configurar Autenticação

A TranscriMed usa OAuth2 para autenticação segura. Veja como implementar:

Solicitação de Autorização

Abra a autorização em uma janela popup para aplicações desktop:

function openAuthorizationPopup() {
  const authUrl = new URL('https://api.transcrimed.com.br/api/oauth/authorize');
  authUrl.searchParams.set('response_type', 'code');
  authUrl.searchParams.set('client_id', 'seu_client_id');
  authUrl.searchParams.set('redirect_uri', 'https://seuapp.com/callback');
  authUrl.searchParams.set('scope', 'medical_records:read medical_records:write jobs:read');
  authUrl.searchParams.set('state', 'string_estado_aleatorio');

  // Abrir janela popup para autorização
  const popup = window.open(
    authUrl.toString(),
    'oauth_popup',
    'width=500,height=600,scrollbars=yes,resizable=yes'
  );

  // Escutar código de autorização do popup
  window.addEventListener('message', function(event) {
    if (event.data.type === 'oauth2_callback') {
      const { code, state } = event.data;
      // Enviar código para seu backend para troca de token
      exchangeCodeForTokens(code);
      popup.close();
    }
  });
}

Troca de Token

Trocar o código de autorização por um token de acesso (faça isso no seu backend):

async function exchangeCodeForTokens(codigoAutorizacao) {
  const tokenResponse = await fetch('https://api.transcrimed.com.br/api/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: codigoAutorizacao,
      redirect_uri: 'https://seuapp.com/callback',
      client_id: 'seu_client_id',
      client_secret: 'seu_client_secret'
    })
  });

  const tokens = await tokenResponse.json();
  const accessToken = tokens.access_token;
  
  // Armazenar tokens com segurança e proceder com chamadas da API
  return accessToken;
}

Passo 3: Faça Sua Primeira Chamada da API

Agora vamos gerar seu primeiro registro médico:

Gerar a partir de Áudio

// Converter arquivo de áudio para base64
const audioFile = document.getElementById('audio-input').files[0];
const audioBase64 = await fileToBase64(audioFile);

const response = await fetch('https://api.transcrimed.com.br/api/v1/medical-records/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    audio: audioBase64,
    template_id: 'consulta-geral',
    language: 'pt',
    mode: 'sync',
    patient_id: 'paciente_123',
    metadata: {
      appointment_type: 'consulta',
      provider: 'Dr. Silva'
    }
  })
});

const result = await response.json();

if (result.success) {
  console.log('Registro médico gerado:');
  console.log('Título:', result.data.medical_record.title);
  console.log('Conteúdo:', result.data.medical_record.content);
  console.log('Tempo de processamento:', result.data.processing_info.duration_ms, 'ms');
} else {
  console.error('Erro:', result.error);
}

// Função auxiliar para converter arquivo para base64
function fileToBase64(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => resolve(reader.result.split(',')[1]);
    reader.onerror = error => reject(error);
  });
}

Gerar a partir de Texto

const response = await fetch('https://api.transcrimed.com.br/api/v1/medical-records/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Paciente apresenta dor no peito e falta de ar. Sinais vitais estáveis. Exame físico revela sons pulmonares limpos.',
    template_id: 'consulta-cardiologia',
    language: 'pt',
    mode: 'sync',
    patient_id: 'paciente_456'
  })
});

const result = await response.json();
console.log('Registro médico gerado:', result.data.medical_record);

Passo 4: Lidar com Processamento Assíncrono

Para arquivos de áudio mais longos ou quando você precisa processar múltiplas solicitações, use o modo assíncrono:

// Iniciar processamento assíncrono
const asyncResponse = await fetch('https://api.transcrimed.com.br/api/v1/medical-records/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    audio: audioLongoBase64,
    template_id: 'consulta-geral',
    language: 'pt',
    mode: 'async'
  })
});

const jobResult = await asyncResponse.json();
const jobId = jobResult.data.job_id;

// Pesquisar status da tarefa
const pollJobStatus = async (jobId) => {
  const statusResponse = await fetch(
    `https://api.transcrimed.com.br/api/v1/jobs/${jobId}`,
    {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    }
  );
  
  const statusData = await statusResponse.json();
  const job = statusData.data.job;
  
  console.log(`Tarefa ${jobId} status: ${job.status} (${job.progress}%)`);
  
  if (job.status === 'completed') {
    // Obter o resultado
    const resultResponse = await fetch(
      `https://api.transcrimed.com.br/api/v1/jobs/${jobId}/result`,
      {
        headers: { 'Authorization': `Bearer ${accessToken}` }
      }
    );
    
    const resultData = await resultResponse.json();
    console.log('Registro médico gerado:', resultData.data);
    return resultData.data;
  } else if (job.status === 'failed') {
    console.error('Tarefa falhou:', job.error_data);
    return null;
  } else {
    // Continuar pesquisando
    setTimeout(() => pollJobStatus(jobId), 2000);
  }
};

pollJobStatus(jobId);

Passo 5: Tratamento de Erros

Sempre implemente tratamento de erros adequado:

async function generateMedicalRecord(audioData, options) {
  try {
    const response = await fetch('https://api.transcrimed.com.br/api/v1/medical-records/generate', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        audio: audioData,
        ...options
      })
    });

    const result = await response.json();

    if (!response.ok) {
      throw new Error(`Erro da API: ${result.error.message}`);
    }

    return result.data;
  } catch (error) {
    console.error('Falha ao gerar registro médico:', error);
    
    // Lidar com casos de erro específicos
    if (error.message.includes('INVALID_AUDIO')) {
      // Lidar com formato de áudio inválido
      alert('Por favor, forneça um arquivo de áudio válido');
    } else if (error.message.includes('INSUFFICIENT_PERMISSIONS')) {
      // Lidar com erros de permissão
      alert('Você não tem permissão para realizar esta ação');
    } else if (error.message.includes('RATE_LIMIT_EXCEEDED')) {
      // Lidar com limitação de taxa
      alert('Limite de taxa excedido. Tente novamente mais tarde.');
    } else {
      // Lidar com erros gerais
      alert('Ocorreu um erro ao processar sua solicitação');
    }
    
    throw error;
  }
}

Passo 6: Testar Sua Integração

Antes de entrar em produção, teste sua integração:

Usar Credenciais de Teste

// Usar credenciais de teste para testes seguros
const API_URL = 'https://api.transcrimed.com.br';

// Configurar com client ID de teste (obter no Portal do Desenvolvedor)
const CLIENT_ID = 'seu_client_id_de_teste'; // Credenciais de teste do portal
const CLIENT_SECRET = 'seu_client_secret_de_teste';

// Testar autenticação com credenciais de teste (modo auto-consentimento)
// Para teste manual, adicione test_mode=manual na URL de autorização
const testAuth = async () => {
  const response = await fetch(`${API_URL}/api/v1/jobs`, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
  
  if (response.ok) {
    console.log('Autenticação bem-sucedida - Modo de teste ativo');
  } else {
    console.error('Falha na autenticação');
  }
};

Validar Formato de Áudio

// Garantir que o áudio está em formato suportado
const validateAudio = (file) => {
  const supportedTypes = [
    'audio/wav',
    'audio/mp3',
    'audio/mpeg',
    'audio/m4a',
    'audio/flac',
    'audio/ogg'
  ];
  
  if (!supportedTypes.includes(file.type)) {
    throw new Error('Formato de áudio não suportado');
  }
  
  // Verificar tamanho do arquivo (máx 100MB)
  if (file.size > 100 * 1024 * 1024) {
    throw new Error('Arquivo de áudio muito grande');
  }
};

// Nota: Com credenciais de teste, use nossos arquivos de áudio de exemplo
// Respostas serão sempre simuladas, não processando áudio real

Próximos Passos

Agora que você tem a integração básica funcionando:

1. Explorar Referência da API - Aprenda sobre todos os endpoints disponíveis
2. Guia de Autenticação - Padrões avançados de autenticação
3. Ferramentas - Use nossas ferramentas de desenvolvimento para integração mais fácil
4. Exemplos - Veja exemplos de integração do mundo real
5. Recursos Avançados - Entre em contato para padrões de integração avançados

Problemas Comuns e Soluções

Problemas de Autenticação

Problema: Respostas 401 Unauthorized Solução: Certifique-se de que seu token de acesso é válido e não expirou. Atualize tokens quando necessário.

Problema: Dados rejeitados em modo de teste Solução: Use apenas dados de teste válidos (nomes como "Test Patient", "John Doe", templates test_*)

Problemas de Formato de Áudio

Problema: 400 Bad Request com erro INVALID_AUDIO Solução: Certifique-se de que o áudio está codificado em base64 e em um formato suportado (WAV, MP3, M4A, etc.)

Limitação de Taxa

Problema: Respostas 429 Too Many Requests Solução: Implemente backoff exponencial e respeite os limites de taxa. Considere fazer upgrade do seu plano para limites mais altos.

Processamento de Arquivos Grandes

Problema: Timeouts com arquivos de áudio grandes Solução: Use modo assíncrono (mode: 'async') para arquivos com mais de 5 minutos.

Suporte

Precisa de ajuda com sua integração?

• Referência da API - Documentação completa da API
• Suporte por Email - Envie solicitações de suporte
• Fórum da Comunidade - Conecte-se com outros desenvolvedores
• Email - Suporte técnico direto

---

Pronto para construir? Comece com nossa Referência da API ou explore nossas ferramentas de desenvolvimento para acelerar sua integração.