Getting Started

This guide will help you integrate TranscriMed's medical transcription API into your healthcare application in just a few steps.

Prerequisites

Before you begin, ensure you have:

• A healthcare application or system requiring medical transcription
• Basic knowledge of REST APIs and OAuth2
• Development environment set up for your preferred programming language

Step 1: Register Your Application

1. Create Developer Account: Visit TranscriMed Developer Portal and create an account
2. Register Your Application: Fill out the application registration form
3. Get Your Credentials: You'll receive:
   • Client ID: Your application's unique identifier
   • Client Secret: Keep this secure and never expose it in client-side code
   • Redirect URI: Where users will be redirected after authorization

tip

Store your client credentials securely. Never commit them to version control or expose them in client-side code.

Step 2: Set Up Authentication

TranscriMed uses OAuth2 for secure authentication. Here's how to implement it:

Authorization Request

Open authorization in a popup window for desktop applications:

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', 'your_client_id');
  authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
  authUrl.searchParams.set('scope', 'medical_records:read medical_records:write jobs:read');
  authUrl.searchParams.set('state', 'random_state_string');

  // Open popup window for authorization
  const popup = window.open(
    authUrl.toString(),
    'oauth_popup',
    'width=500,height=600,scrollbars=yes,resizable=yes'
  );

  // Listen for authorization code from popup
  window.addEventListener('message', function(event) {
    if (event.data.type === 'oauth2_callback') {
      const { code, state } = event.data;
      // Send code to your backend for token exchange
      exchangeCodeForTokens(code);
      popup.close();
    }
  });
}

Token Exchange

Exchange the authorization code for an access token (do this in your backend):

async function exchangeCodeForTokens(authorizationCode) {
  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: authorizationCode,
      redirect_uri: 'https://yourapp.com/callback',
      client_id: 'your_client_id',
      client_secret: 'your_client_secret'
    })
  });

  const tokens = await tokenResponse.json();
  const accessToken = tokens.access_token;
  
  // Store tokens securely and proceed with API calls
  return accessToken;
}

Step 3: Make Your First API Call

Now let's generate your first medical record:

Generate from Audio

// Convert audio file to 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: 'general-consultation',
    language: 'en',
    mode: 'sync',
    patient_id: 'patient_123',
    metadata: {
      appointment_type: 'consultation',
      provider: 'Dr. Smith'
    }
  })
});

const result = await response.json();

if (result.success) {
  console.log('Medical record generated:');
  console.log('Title:', result.data.medical_record.title);
  console.log('Content:', result.data.medical_record.content);
  console.log('Processing time:', result.data.processing_info.duration_ms, 'ms');
} else {
  console.error('Error:', result.error);
}

// Helper function to convert file to 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);
  });
}

Generate from Text

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: 'Patient presents with chest pain and shortness of breath. Vital signs stable. Physical examination reveals clear lung sounds.',
    template_id: 'cardiology-consultation',
    language: 'en',
    mode: 'sync',
    patient_id: 'patient_456'
  })
});

const result = await response.json();
console.log('Generated medical record:', result.data.medical_record);

Step 4: Handle Async Processing

For longer audio files or when you need to process multiple requests, use async mode:

// Start async processing
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: longAudioBase64,
    template_id: 'general-consultation',
    language: 'en',
    mode: 'async'
  })
});

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

// Poll job status
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(`Job ${jobId} status: ${job.status} (${job.progress}%)`);
  
  if (job.status === 'completed') {
    // Get the result
    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('Medical record generated:', resultData.data);
    return resultData.data;
  } else if (job.status === 'failed') {
    console.error('Job failed:', job.error_data);
    return null;
  } else {
    // Continue polling
    setTimeout(() => pollJobStatus(jobId), 2000);
  }
};

pollJobStatus(jobId);

Step 5: Error Handling

Always implement proper error handling:

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(`API Error: ${result.error.message}`);
    }

    return result.data;
  } catch (error) {
    console.error('Failed to generate medical record:', error);
    
    // Handle specific error cases
    if (error.message.includes('INVALID_AUDIO')) {
      // Handle invalid audio format
      alert('Please provide a valid audio file');
    } else if (error.message.includes('INSUFFICIENT_PERMISSIONS')) {
      // Handle permission errors
      alert('You don\'t have permission to perform this action');
    } else if (error.message.includes('RATE_LIMIT_EXCEEDED')) {
      // Handle rate limiting
      alert('Rate limit exceeded. Please try again later.');
    } else {
      // Handle general errors
      alert('An error occurred while processing your request');
    }
    
    throw error;
  }
}

Step 6: Test Your Integration

Before going live, test your integration:

Use Test Credentials

// Use test credentials for safe testing
const API_URL = 'https://api.transcrimed.com.br';

// Configure with test client ID (get from Developer Portal)
const CLIENT_ID = 'your_test_client_id'; // Test credentials from developer portal
const CLIENT_SECRET = 'your_test_client_secret';

// Test authentication with test credentials (auto-consent mode)
// For manual testing, add test_mode=manual to authorization URL
const testAuth = async () => {
  const response = await fetch(`${API_URL}/api/v1/jobs`, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
  
  if (response.ok) {
    console.log('Authentication successful - Test mode active');
  } else {
    console.error('Authentication failed');
  }
};

Validate Audio Format

// Ensure audio is in supported format
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('Unsupported audio format');
  }
  
  // Check file size (max 100MB)
  if (file.size > 100 * 1024 * 1024) {
    throw new Error('Audio file too large');
  }
};

// Note: With test credentials, use our sample audio files
// Responses will always be simulated, not processing real audio

Next Steps

Now that you have basic integration working:

1. Explore API Reference - Learn about all available endpoints
2. Authentication Guide - Advanced authentication patterns
3. Tools - Use our development tools for easier integration
4. Examples - See real-world integration examples
5. Advanced Features - Contact us for advanced integration patterns

Common Issues & Solutions

Authentication Issues

Problem: 401 Unauthorized responses Solution: Ensure your access token is valid and not expired. Refresh tokens when needed.

Problem: Data rejected in test mode Solution: Use only valid test data (names like "Test Patient", "John Doe", templates test_*)

Audio Format Issues

Problem: 400 Bad Request with INVALID_AUDIO error Solution: Ensure audio is base64 encoded and in a supported format (WAV, MP3, M4A, etc.)

Rate Limiting

Problem: 429 Too Many Requests responses Solution: Implement exponential backoff and respect Retry-After when present.

Large File Processing

Problem: Timeouts with large audio files Solution: Use async mode (mode: 'async') for files longer than 5 minutes.

Support

Need help with your integration?

• API Reference - Complete API documentation
• Email Support - Submit support requests
• Community Forum - Connect with other developers
• Email - Direct technical support

---

Ready to build? Start with our API Reference or explore our development tools to accelerate your integration.