Sandbox Environment | Ottimate Developer Documentation

All development and testing MUST be performed in the Sandbox environment. Production credentials are only issued after successful validation in Sandbox. Never test integrations directly in Production as this will affect live accounting data and workflows.

Quick Reference

Use these URLs when developing your integration:

Environment	Dashboard	API Base	Auth Server
Sandbox	sandbox.ottimate.com	`https://sandbox-api.ottimate.com/v1`	`https://sandbox-auth.ottimate.com/oauth/token`
Production	dashboard.ottimate.com	`https://api.ottimate.com/v1`	`https://auth.ottimate.com/oauth/token`

Always start with Sandbox URLs during development. Replace with Production URLs only after receiving production credentials.

What is the Sandbox Environment?

The Sandbox environment is a complete, isolated replica of the Ottimate production system designed specifically for development, testing, and validation. It provides a safe space to build and test your integration without any risk to live accounting data or workflows.

Why Use Sandbox?

Risk-Free Testing: Test your integration without affecting real accounting data or business operations
Experiment Freely: Try different approaches, test edge cases, and debug issues without consequences
Realistic Environment: Access the same features, APIs, and workflows available in production
Error Testing: Safely test error handling and failure scenarios
Validation Required: Complete and validate your integration before accessing production

Sandbox vs Production

Data Isolation

The Sandbox environment is completely separate from Production:

Independent Data: Sandbox data and settings do not sync with or affect Production
Different Identifiers: The same entity will have different Ottimate-generated IDs in each environment
Separate Credentials: Sandbox and Production use different API keys, Client IDs, and Client Secrets
Isolated Users: User accounts and permissions are managed separately

Feature Parity

The Sandbox environment replicates all core production features:

All API endpoints and operations
Authentication flows
Invoice processing and extraction
Approval workflows
Vendor and dimension management
Catalog functionality

Getting Sandbox Access

Credential Provisioning

Ottimate provisions Sandbox and Production credentials in two separate stages to ensure proper testing and validation:

Stage 1: Sandbox Access During the Discovery and Development phases, your Ottimate Partner Manager will:

Create and configure a mock client account in the Sandbox environment with all necessary features enabled (this is required for the API to function)
Provide you with:
- Sandbox API Key (X-API-Key header)
- Sandbox Client ID and Client Secret (OAuth2 credentials)
- Access details for your configured Sandbox organization
- Invitation to dedicated Slack channel for support

The API will not work without a properly configured client account in Sandbox. Ensure your Partner Manager has completed the organization setup before attempting API calls.

Stage 2: Production Access After successful validation in Sandbox:

Production API Key
Production Client ID and Client Secret
Access to production organization(s)
Go-live support and monitoring

This staged approach mitigates the risk of impacting high-stakes accounting tasks and ensures your integration is production-ready.

Using the Sandbox Dashboard

You can log in to the Sandbox Dashboard to test your integration from an end-user perspective and verify how your API calls affect the system.

Testing Invoice Upload

The Sandbox supports multiple methods for creating and uploading invoices:

API Upload: Use POST /v1/invoices/upload to upload invoice files for extraction
API Creation: Use POST /v1/invoices to create invoices programmatically with structured data
Desktop Upload: Test InstantCapture desktop upload functionality
Manual Creation: Create invoices manually from the Invoice tab to understand the user workflow

Viewing API Results

After making API calls, log in to the Sandbox Dashboard to:

Verify invoices were created correctly
Check extraction results from uploaded files
Test approval workflows
Validate dimension assignments
Confirm vendor associations
Review export status

Recommended Testing Workflow

Follow this workflow to ensure comprehensive testing in Sandbox:

Step 0: Client Account Setup (Prerequisite)

IMPORTANT: Before you can use the API, a mock client account must be onboarded and configured in the Sandbox environment.

What’s required:

Your Ottimate Partner Manager will create and configure a test organization in Sandbox
All necessary features and modules will be enabled for your integration
User accounts and permissions will be set up
The organization structure (companies, locations) will be configured

Why this matters: The Ottimate API will not function without a properly configured client account. All API requests are scoped to a specific organization, so this setup is mandatory before any testing can begin.

Action needed: Contact your Ottimate Partner Manager to confirm your Sandbox organization has been created and configured with:

Organization name and settings
Enabled features (Instantcapture, Purchase Orders, Catalog Match, etc.)
Company and location structure
Initial user accounts

Once confirmed, you’ll receive:

Your Sandbox organization ID or account identifier
Confirmation that your API credentials are linked to this organization

Step 1: Authenticate

After your Sandbox organization is configured, obtain your first access token using the Sandbox Auth URL and your credentials:

$ curl -X POST https://sandbox-auth.ottimate.com/oauth/token \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   -H "X-API-Key: your-sandbox-api-key" \
>   -d "grant_type=client_credentials" \
>   -d "client_id=YOUR_SANDBOX_CLIENT_ID" \
>   -d "client_secret=YOUR_SANDBOX_CLIENT_SECRET"

Step 2: Test With Authentic Data

Use accounting entities from your ERP for testing in Sandbox:

Create accounting vendors using POST /v1/vendors
Set up accounting dimensions using POST /v1/dimensions
Configure catalog entries if needed
Verify data in Sandbox Dashboard

Step 3: Test Core Workflows

Test all integration scenarios based on your AP workflow:

Invoice creation and upload
Data synchronization (vendors, dimensions)
Invoice updates and modifications
Approval workflows
Error handling and edge cases

Step 4: Validate Results

Verify outcomes in the Sandbox Dashboard:

Check that invoices appear correctly
Validate approval chains
Confirm dimension assignments
Review export status

Step 5: Test Error Scenarios

Intentionally test failure cases:

Invalid authentication
Malformed requests
Missing required fields
Duplicate data handling
Rate limiting behavior

Step 6: Schedule Validation

Once testing is complete, work with your Ottimate Partner Manager to:

Review test results
Complete validation checklist
Address any issues or concerns
Receive approval for production access

Best Practices

During Development

Use Sandbox URLs Consistently: Always point to sandbox-api.ottimate.com and sandbox-auth.ottimate.com during development
Test Thoroughly: Don’t rush to production—test all features and edge cases in Sandbox first
Use Realistic Test Data: Create test data that mirrors real-world scenarios you’ll encounter in production
Document Test Cases: Keep track of what you’ve tested and the results
Test Error Handling: Intentionally trigger errors to ensure your integration handles them gracefully

Data Management

Never Use Real Data: Do not use actual company information, real vendor data, or sensitive information in Sandbox
Create Meaningful Test Data: Use descriptive names for test entities (e.g., “Test Vendor - Electronics”, “Test Invoice - High Value”)
Clean Up Regularly: Keep your Sandbox organized by archiving or removing old test data
Coordinate with Team: If multiple developers share the Sandbox, coordinate data creation to avoid conflicts

Security

Keep Credentials Secure: Treat Sandbox credentials with the same security as production
Use Environment Variables: Never hardcode credentials in your source code
Rotate Credentials: Request new credentials if they may have been compromised
Don’t Share Credentials: Each developer should have their own set of credentials when possible

Transitioning to Production

Validation Requirements

Before receiving production credentials, Ottimate will validate:

Authentication: Proper OAuth2 flow implementation and token management
Core Functionality: All planned API operations working correctly
Error Handling: Appropriate handling of API errors and edge cases
Data Integrity: Correct data formatting and validation
Integration Stability: Consistent performance and reliability

Production Access Process

Complete Sandbox Testing: Finish all development and testing in Sandbox
Request Validation: Contact your Ottimate Partner Manager to schedule validation
Validation Session: Demonstrate your integration and review test results
Receive Production Credentials: Upon approval, receive production API key and OAuth credentials
Update Configuration: Update your integration to use production URLs
Monitor Go-Live: Ottimate team monitors initial production usage for any issues

Production Differences

When moving to production, be aware:

Different Credentials: Use production API key, Client ID, and Client Secret
Different URLs: Update all endpoints to use api.ottimate.com and auth.ottimate.com
Different IDs: Entity IDs from Sandbox won’t exist in production—data must be recreated or synchronized
Real Impact: All operations affect live accounting data and workflows
Production Support: Access to production support and monitoring

Need Help?

Sandbox Access & Organization Setup

To receive Sandbox credentials and ensure your mock client account is properly configured, reach out to your Ottimate Partner Manager or contact peter.niu@ottimate.com.

Before you start testing, confirm:

Your Sandbox organization has been created and configured
All required features are enabled for your integration
Your API credentials are linked to the organization

Technical Support

During development, use your dedicated Slack channel for real-time support from the Ottimate technical team.

Next Steps

Authentication Guide

Learn how to authenticate with Sandbox

API Reference

Explore available endpoints