🌍Environments & Base URLs

Docs-Dispatcher operates across multiple environments with different base URLs for each service.

Production Environment

Dispatcher API

Base URL: https://api.docs-dispatcher.io

Endpoints:

Authentication:

• POST /auth - Login and get JWT

• GET /auth/refresh - Refresh JWT token

Configuration & Templates:

• GET /api/v1/my/config - Get user/company configurations

• GET /api/v1/templates - List templates

• GET /api/v1/templates/:id - Get template details

Service Dispatch:

• POST /api/invoicing - Invoice/quote dispatch

• POST /api/esign - eSign workflows

• POST /api/postal - Postal mail dispatch

• POST /api/sms - SMS messaging

• POST /api/email - Email dispatch

• POST /api/file - Document generation only

• POST /api/upload - File upload

• POST /api/:service/validate - Validation (all services)

Health:

• GET /healthz - Health check

Sandbox Environment (Coming Soon)

Sandbox environment for testing without affecting production data.

Dispatcher API: https://templater-api.sandbox.docs-dispatcher.io
Dispatcher API: https://api.sandbox.docs-dispatcher.io

Differences from production:

• Isolated database (no production data)

• Provider sandbox APIs used where available

• No real emails/SMS/postal mail sent

• No actual invoices created in accounting systems

• Rate limits may differ

Provider Sandboxes: Some providers offer sandbox modes (e.g., Qonto). Use the useSandbox flag in provider configs to test with real provider APIs without creating actual invoices.

Common Headers

Required for All Dispatcher Requests

Authorization: Basic <BASE64_ENCODED_CREDENTIALS>
Content-Type: application/json

Example:

# Method 1: Let curl handle Basic Auth encoding
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -u "[email protected]:your-password" \
  -H "Content-Type: application/json" \
  -d @request.json

# Method 2: Pre-encoded credentials
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Basic b2xpdmllci5yb2VsYW50c0BnbWFpbC5jb206..." \
  -H "Content-Type: application/json" \
  -d @request.json

Basic Auth Encoding: The credentials format is email:password encoded as base64. Most HTTP clients handle this automatically. See Authentication for details.

Optional Headers

X-Request-ID: <unique-request-id>
X-Idempotency-Key: <idempotency-key>

• X-Request-ID: Track requests across services (generated if not provided)

• X-Idempotency-Key: Prevent duplicate dispatches (recommended for production)

URL Patterns

Service Endpoints

All service endpoints follow this pattern:

POST /api/{service}[/{composable1}[/{composable2}]]?async={true|false}

Examples:

POST /api/invoicing
POST /api/invoicing?async=true
POST /api/invoicing/email
POST /api/invoicing/email/upload
POST /api/esign
POST /api/postal
POST /api/sms
POST /api/email
POST /api/file
POST /api/upload

Validation Endpoints

POST /api/{service}/validate

Examples:

POST /api/invoicing/validate
POST /api/esign/validate
POST /api/postal/validate
POST /api/sms/validate

Webhook Endpoints

Webhook callbacks follow this pattern:

POST /api/webhooks/{service}/providers/{provider}/endpoint.json

Examples:

POST /api/webhooks/esign/providers/universign/endpoint.json
POST /api/webhooks/esign/providers/signaturit/endpoint.json
POST /api/webhooks/postal/providers/mysendingbox/endpoint.json

Rate Limits

Production

• Authentication: 10 requests/minute per IP

• Dispatcher: 100 requests/minute per user

• Validation: 20 requests/minute per user

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1644851234

Rate Limit Exceeded (429):

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 45 seconds.",
  "retryAfter": 45
}

Timeouts

Connection Timeouts

• Dispatcher API: 30 seconds

• Provider APIs: 60 seconds (varies by provider)

Request Timeouts

• Sync requests: 120 seconds

• Async requests: 5 seconds (queues immediately)

• Validation: 10 seconds

Long-running operations: For operations that may take longer than 120 seconds (e.g., large PDF generation, postal dispatch), use ?async=true to avoid timeouts.

SSL/TLS

All endpoints require HTTPS with TLS 1.2 or higher.

Certificate Validation:

• Production certificates are valid and trusted

• Self-signed certificates are not supported

• Certificate pinning is not required

Regional Availability

Currently, all services are hosted in:

• Primary Region: Europe (France)

• Failover: Europe (Ireland)

Latency Expectations:

• Europe: < 50ms

• North America: 100-150ms

• Asia: 200-300ms

CORS

Dispatcher API

CORS is not enabled by default for security:

Security Warning: Do NOT call Dispatcher API directly from browser JavaScript. Use a backend proxy to protect your JWT tokens and prevent CSRF attacks.

Recommended Architecture:

Browser → Your Backend API → Dispatcher API

Health Check

Check service availability:

curl https://api.docs-dispatcher.io/healthz

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 1234567,
  "timestamp": "2026-02-13T12:30:00Z"
}

IP Whitelisting

For enhanced security, you can restrict API access to specific IP addresses:

1. Contact support to enable IP whitelisting

2. Provide list of allowed IPs/CIDR ranges

3. Requests from other IPs will receive 403 Forbidden

Service Status

Monitor service status and incidents:

• Status Page: https://status.docs-dispatcher.io (TBD)

• Incidents: Subscribe to updates via email or RSS

Environment Variables

Recommended environment variables for your application:

# Production
DOCS_DISPATCHER_API_URL=https://api.docs-dispatcher.io
[email protected]
DOCS_DISPATCHER_PASSWORD=your-secure-password

# Sandbox (coming soon)
DOCS_DISPATCHER_SANDBOX_API_URL=https://api.sandbox.docs-dispatcher.io
[email protected]
DOCS_DISPATCHER_SANDBOX_PASSWORD=sandbox-password

Security: Never commit credentials to version control. Use environment variables or secret management services (AWS Secrets Manager, HashiCorp Vault, etc.).

Next Steps

• Get a JWT - Authenticate with Dispatcher API

• Quickstart - Send your first request

• API Reference - Full OpenAPI specification