API Testing Guide

Test TranscriMed APIs directly from your browser using our interactive testing tools.

Company account with an integration key?

The test mode below is for OAuth2 partner apps. Integration keys have no test mode: test against the sandbox (https://api.sandbox.transcrimed.com.br), a separate installation with its own account and keys, using only fictitious data. Follow the Integration Key guide and run the Integration key (B2B) folder of the Postman collection with the Sandbox environment.

Test Mode

TranscriMed provides an integrated test environment with two testing modes for comprehensive integration testing:

• Test Credentials: Use test client credentials to automatically activate test mode
• Auto-Consent Mode: Test clients automatically approve OAuth2 authorization (default)
• Manual Test Mode: Add test_mode=manual to test the complete user authorization flow
• Mock Responses: Receive realistic mock data without real AI processing
• No Costs: Test for free without consuming production credits
• Data Validation: Only accepts specific test data for security

OAuth2 Testing Modes

TranscriMed offers two distinct OAuth2 testing modes to suit different testing needs:

Auto-Consent Mode (Default)

Perfect for: API integration testing, automated testing, CI/CD pipelines

• How it works: Test clients automatically approve authorization requests
• No user interaction: Authorization URL immediately returns authorization code
• Usage: Simply use test credentials - auto-consent is enabled by default

# Auto-consent example (default behavior)
GET /oauth/authorize?client_id=test_tc_abc123&redirect_uri=https://your-app.com/callback&response_type=code&scope=medical_records:read
# → Immediately redirects with authorization code

Manual Test Mode

Perfect for: Testing complete user experience, UI/UX validation, partner authentication flows

• How it works: Full OAuth2 flow with partner login and consent screen
• Complete UX testing: Partner logs in → sees consent screen → approves → gets code
• Usage: Add test_mode=manual parameter to authorization URL

# Manual test mode example
GET /oauth/authorize?client_id=test_tc_abc123&redirect_uri=https://your-app.com/callback&response_type=code&scope=medical_records:read&test_mode=manual
# → Shows partner login → consent screen → redirects with authorization code

Choosing the Right Mode

Scenario	Recommended Mode	Why
API Integration Testing	Auto-Consent	Fast, no manual steps
Automated Tests	Auto-Consent	No user interaction needed
CI/CD Pipelines	Auto-Consent	Fully automated
UX Testing	Manual Test Mode	Test complete user flow
Partner Training	Manual Test Mode	Experience real OAuth2 flow
Demo Purposes	Manual Test Mode	Show actual consent process

Prerequisites

Before testing the APIs, you'll need:

1. API Credentials: Get your test credentials from the Developer Portal
2. Test Mode: Use test credentials for safe experimentation
3. Test Data: Use our sample data or prepare your own
4. OAuth2 Flow: Choose between auto-consent or manual test mode

Interactive API Documentation

Explore our OpenAPI specifications with interactive tools:

• Authentication API - OAuth2 flows and token management
• Medical Records API - Medical record generation and management
• Worklist API - Bidirectional RIS/PACS integration
• Jobs API - Asynchronous job tracking

Quick Test Examples

Test Authentication

Check that your token works by listing your account templates:

Generate Medical Record

Test medical record generation with sample text:

List Jobs

Check your processing jobs:

Testing Best Practices

1. Start with Test Credentials

Always test with test credentials first:

• Test Client ID: Provided in your developer portal (separate from production credentials)
• Auto-Consent Mode: Test clients automatically approve authorization requests (default)
• Manual Test Mode: Add test_mode=manual parameter to test complete OAuth2 flow
• Mock Responses: Returns simulated data without processing LLMs
• No real costs: Safe for experimentation
• Test Data: Only accepts test patient data

2. Use Required Test Data

With test credentials, you must use specific test data:

Test Patient Names

- "Test Patient" / "Paciente Teste"
- "John Doe" / "Jane Doe"
- "Sample Patient"
- "Demo Patient"

Sample Clinical Text (Example)

Test Patient John Doe, 52 anos, hipertenso e diabético, em uso regular de 
losartana 50mg e metformina 850mg. Apresenta queixa de cefaleia 
occipital há 2 semanas, de forte intensidade, associada a náuseas.
PA: 160x100 mmHg, FC: 88 bpm, glicemia capilar: 180 mg/dL.

Sample Audio (Base64)

UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAABCxAgAEABAAZGF0YQAAAAA=

Test Templates

- test_template_general
- test_template_cardiology
- test_template_dermatology

3. Handle Errors Gracefully

Common error scenarios to test:

• 401 Unauthorized: Invalid or missing API key
• 429 Too Many Requests: Rate limit exceeded
• 400 Bad Request: Invalid request parameters
• 500 Internal Server Error: Server issues

4. Monitor Rate Limits

When rate limits are exceeded, the API returns 429 Too Many Requests. A Retry-After header may be present to indicate when it is safe to retry. Implement exponential backoff.

Testing Tools

Postman Collection

1. Download the collection and an environment: Sandbox for company accounts with an integration key, or Test for OAuth2 partner apps with test credentials.
2. Import both into Postman and select the environment.
3. Set the credential as the environment's current value: integration_key (Sandbox) or client_id / client_secret (Test).
4. Company accounts: run the Integration key (B2B) folder with the Collection Runner. See Tools.

cURL Examples

Test with cURL using test credentials:

# Check the token: list your templates
curl -X GET https://api.transcrimed.com.br/api/v1/templates \
  -H "Authorization: Bearer YOUR_TEST_API_KEY"

# Generate medical record (test mode - required data)
curl -X POST https://api.transcrimed.com.br/api/v1/medical-records/generate \
  -H "Authorization: Bearer YOUR_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Test Patient com dor torácica",
    "mode": "sync",
    "template_id": "test_template_general"
  }'

Python Example

import requests

# Configure with test credentials
API_KEY = "your_test_api_key"  # Obtained with test client credentials
BASE_URL = "https://api.transcrimed.com.br"

# Make request (automatic test mode)
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/api/v1/medical-records/generate",
    headers=headers,
    json={
        "text": "Test Patient com sintomas gripais",  # Required test name
        "mode": "sync",
        "template_id": "test_template_general"  # Test template
    }
)

# Response will always be simulated in test mode
print(response.json())

Debugging Tips

1. Check Request Format

Ensure your requests follow the correct format:

• Headers are properly set
• JSON body is valid
• Required fields are included

2. Inspect Response Headers

Response headers contain useful debugging information:

• X-Request-Id: Unique request identifier for support
• X-Processing-Time: Server processing time
• Rate limit headers

3. Use Request IDs

When contacting support, always provide:

• Request ID from response headers
• Timestamp of the request
• Error message received

Next Steps

Ready to integrate TranscriMed into your application?

1. Read the Getting Started Guide - Step-by-step integration
2. Explore Authentication - Implement OAuth2 flow
3. Check out Examples - Real-world integration examples
4. Browse Tools - Use our development tools and resources

Support

Need help with testing?

• Developer Support
• Community Forum
• Report Issues