🔌Providers & Configurations

Understanding how Docs-Dispatcher resolves provider configurations is critical for successful API integration. This guide explains the hybrid 3-tier provider resolution system and how to configure providers for your services.

Overview

Docs-Dispatcher uses a flexible 3-tier provider resolution system that balances simplicity with control:

Tier 1: Company Default Config
      ↓ (can be overridden)
Tier 2: User Override Config
      ↓ (can be overridden)
Tier 3: Explicit providerName in Request

This system allows:

Companies to set default providers for all users
Individual users to override with their preferred providers
API requests to explicitly specify providers for one-off cases

How Provider Resolution Works

When you make a dispatch request, Dispatcher resolves the provider in this order:

Resolution Priority (Highest to Lowest)

Explicit providerName in Request - Always wins if provided
User Override Configuration - User-specific provider preference
Company Default Configuration - Fallback for all company users

If no configuration is found at any tier, the request fails with 400 Bad Request.

Real-World Example

Let's see how this works in practice:

Scenario Setup

Company: Acme Corp

Default invoicing provider: Qonto
Default SMS provider: Brevo

User: Alice

SMS override: OVH (she prefers OVH for SMS)

User: Bob

No overrides (uses company defaults)

Resolution Examples

Example 1: No Explicit Provider (Uses Defaults)

Alice sends an invoice:

POST /api/invoicing
{
  "documentType": "INVOICE",
  "template": { "id": 123, "data": {...} }
}

Resolution: Qonto (company default, Alice has no override)

Bob sends SMS:

POST /api/sms
{
  "phoneNumber": "+33612345678",
  "message": "Your order is ready"
}

Resolution: Brevo (company default, Bob has no override)

Alice sends SMS:

POST /api/sms
{
  "phoneNumber": "+33612345678",
  "message": "Your order is ready"
}

Resolution: OVH (Alice's user override)

Example 2: Explicit Provider (Overrides Everything)

Alice sends invoice with explicit provider:

POST /api/invoicing
{
  "providerName": "pennylane",
  "documentType": "INVOICE",
  "template": { "id": 123, "data": {...} }
}

Resolution: PennyLane (explicit request wins, ignores Qonto default)

Bob sends SMS with explicit provider:

POST /api/sms
{
  "providerName": "sms_magic",
  "phoneNumber": "+33612345678",
  "message": "Your order is ready"
}

Resolution: SMS Magic (explicit request wins, ignores Brevo default)

Provider Configuration Structure

Each provider requires a configuration object with provider-specific credentials and settings.

Configuration Storage

Provider configurations are stored in:

Company level: GET /api/v1/companies/:companyId/configs
User level: GET /api/v1/users/:userId/configs

Common Configuration Fields

All provider configs share these fields:

{
  "service": "invoicing",
  "providerName": "qonto",
  "isDefault": true,
  "isActive": true,
  "config": {
    // Provider-specific fields
  }
}

Field

Type

Description

service

string

Service type: invoicing, esign, postal, sms, email

providerName

string

Provider identifier (see Available Providers)

isDefault

boolean

Set as default for this service

isActive

boolean

Enable/disable without deleting

config

object

Provider-specific credentials and settings

Provider-Specific Config Examples

Invoicing: Qonto

{
  "service": "invoicing",
  "providerName": "qonto",
  "isDefault": true,
  "isActive": true,
  "config": {
    "apiKey": "qonto_live_abc123xyz",
    "organizationSlug": "acme-corp",
    "useSandbox": false
  }
}

eSign: Universign

{
  "service": "esign",
  "providerName": "universign",
  "isDefault": true,
  "isActive": true,
  "config": {
    "username": "[email protected]",
    "password": "secure-password",
    "apiUrl": "https://api.universign.com/v1"
  }
}

SMS: Brevo

{
  "service": "sms",
  "providerName": "brevo",
  "isDefault": true,
  "isActive": true,
  "config": {
    "apiKey": "xkeysib-abc123xyz",
    "sender": "Acme"
  }
}

Postal: MySendingBox

{
  "service": "postal",
  "providerName": "mysendingbox",
  "isDefault": true,
  "isActive": true,
  "config": {
    "apiKey": "msb_live_abc123xyz",
    "webhookSecret": "whsec_def456uvw"
  }
}

Available Providers

Docs-Dispatcher supports 12 external providers across 7 services:

Invoicing (4 providers)

Provider

providerName

Document Types

Webhooks

iPaidThat

ipaidthat

INVOICE, E_INVOICE, QUOTE, CREDIT

PennyLane

pennylane

INVOICE, E_INVOICE, QUOTE, CREDIT

Qonto

qonto

INVOICE, E_INVOICE, QUOTE, CREDIT

SuperPDP

superpdp

INVOICE, E_INVOICE, QUOTE, CREDIT

eSign (3 providers)

Provider

providerName

Webhooks

Signaturit

signaturit

Yes

Universign

universign

Yes

Yousign

yousign

Postal (1 provider)

Provider

providerName

Webhooks

MySendingBox

mysendingbox

Yes

SMS (4 providers)

Provider

providerName

Webhooks

Brevo

brevo

OVH

ovh

SMS Factor

sms_factor

SMS Magic

sms_magic

Email (Built-in SMTP)

Email uses SMTP configuration without external providers.

File & Upload

These services don't require provider configuration (internal printer services).

Setting Up Provider Configurations

Provider configurations are managed through the Templater UI at company and user levels.

Company-Level Setup (Admins Only)

Log in to Templater UI
Navigate to Admin > Company Settings > Providers
Add provider configuration:
- Select service (e.g., Invoicing)
- Select provider (e.g., Qonto)
- Enter credentials
- Set as default (optional)
- Save configuration

User-Level Setup

Log in to Templater UI
Navigate to My Account > Provider Overrides
Add override configuration:
- Select service
- Select provider
- Enter credentials
- Save override

Note: User overrides only work if the provider is already configured at company level with proper credentials OR if the user provides their own credentials.

Multi-Provider Scenarios

Scenario 1: Different Providers Per User

Use Case: Each sales rep uses their own accounting platform.

Setup:

Company: No default invoicing provider
Alice: PennyLane configuration
Bob: Qonto configuration
Charlie: iPaidThat configuration

Requests:

# Alice's request (uses her PennyLane config)
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $ALICE_JWT" \
  -d '{"documentType": "INVOICE", ...}'

# Bob's request (uses his Qonto config)
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $BOB_JWT" \
  -d '{"documentType": "INVOICE", ...}'

Scenario 2: Multiple Providers for Same Service

Use Case: Company uses different invoicing providers for different regions.

Setup:

Company default: Qonto (France)
Explicit provider in request for other regions

Requests:

# French invoice (uses Qonto default)
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT" \
  -d '{"documentType": "INVOICE", ...}'

# Swiss invoice (explicit SuperPDP)
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT" \
  -d '{"providerName": "superpdp", "documentType": "INVOICE", ...}'

Scenario 3: Sandbox vs Production

Use Case: Test with sandbox before production dispatch.

Setup:

Company default: Qonto with useSandbox: true
Explicit production provider in request

Requests:

# Test in sandbox (uses company default with sandbox flag)
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT" \
  -d '{"documentType": "INVOICE", ...}'

# Production dispatch (explicit provider without sandbox)
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "providerName": "qonto",
    "documentType": "INVOICE",
    "providerOverride": {
      "useSandbox": false
    },
    ...
  }'

Common Configuration Issues

Issue 1: "Provider not configured" (400)

Error:

{
  "error": "provider_not_configured",
  "message": "No configuration found for service 'invoicing' and provider 'qonto'"
}

Causes:

No company default configured
No user override configured
Explicit provider has no configuration

Solution:

Verify provider is configured in Templater UI
Check isActive: true in configuration
Verify JWT token belongs to correct user/company

Issue 2: "Invalid provider credentials" (502)

Error:

{
  "error": "provider_error",
  "message": "Authentication failed with provider 'qonto'"
}

Causes:

API key expired or revoked
Incorrect credentials
Provider API down

Solution:

Re-enter credentials in Templater UI
Test credentials with provider's API directly
Check provider status page

Issue 3: "Provider not supported for service" (400)

Error:

{
  "error": "invalid_provider",
  "message": "Provider 'qonto' is not supported for service 'sms'"
}

Causes:

Wrong providerName for service
Typo in provider name (case-sensitive)

Solution:

See Available Providers for valid combinations
Verify provider name spelling

Best Practices

1. Use Company Defaults for Consistency

Set company defaults for services used by all users:

✅ Good: Company default Qonto for invoicing
✅ Good: Company default Brevo for SMS

2. User Overrides for Special Cases

Use user overrides sparingly:

✅ Good: Sales rep with personal accounting platform
❌ Bad: Every user has different provider (manage at company level instead)

3. Explicit Providers for Edge Cases

Use explicit providerName for:

Multi-region dispatches
A/B testing providers
One-off provider usage

4. Test with Validation Endpoint

Before configuring a new provider, test with validation:

# Test provider configuration
curl -X POST https://api.docs-dispatcher.io/api/invoicing/validate \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "providerName": "qonto",
    "documentType": "INVOICE",
    "template": {...}
  }'

5. Secure Credential Storage

Never hardcode credentials in requests:

// ❌ Bad - credentials in code
const request = {
  providerName: 'qonto',
  providerOverride: {
    apiKey: 'qonto_live_abc123xyz'  // NEVER do this
  }
};

// ✅ Good - credentials in Templater config
const request = {
  providerName: 'qonto'  // Uses configured credentials
};

6. Monitor Provider Usage

Track which providers are used for billing and monitoring:

# Get provider usage stats
curl -X GET https://api.docs-dispatcher.io/api/v1/stats/providers \
  -H "Authorization: Bearer $JWT"

Code Examples

Example 1: Using Company Default

# curl
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "INVOICE",
    "template": {
      "id": 123,
      "data": {...}
    }
  }'

// Node.js
const response = await fetch('https://api.docs-dispatcher.io/api/invoicing', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documentType: 'INVOICE',
    template: {
      id: 123,
      data: {...}
    }
  })
});

// PHP
$client = new \GuzzleHttp\Client();
$response = $client->post('https://api.docs-dispatcher.io/api/invoicing', [
    'headers' => [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'documentType' => 'INVOICE',
        'template' => [
            'id' => 123,
            'data' => [...]
        ]
    ]
]);

// Java
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.docs-dispatcher.io/api/invoicing"))
    .header("Authorization", "Bearer " + jwtToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"documentType\":\"INVOICE\",\"template\":{\"id\":123,\"data\":{...}}}"
    ))
    .build();

Example 2: Explicit Provider Override

# curl
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "pennylane",
    "documentType": "INVOICE",
    "template": {
      "id": 123,
      "data": {...}
    }
  }'

// Node.js
const response = await fetch('https://api.docs-dispatcher.io/api/invoicing', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    providerName: 'pennylane',  // Explicit override
    documentType: 'INVOICE',
    template: {
      id: 123,
      data: {...}
    }
  })
});

// PHP
$response = $client->post('https://api.docs-dispatcher.io/api/invoicing', [
    'headers' => [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'providerName' => 'pennylane',  // Explicit override
        'documentType' => 'INVOICE',
        'template' => [
            'id' => 123,
            'data' => [...]
        ]
    ]
]);

// Java
String requestBody = String.format(
    "{\"providerName\":\"pennylane\",\"documentType\":\"INVOICE\",\"template\":{\"id\":123,\"data\":{...}}}"
);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.docs-dispatcher.io/api/invoicing"))
    .header("Authorization", "Bearer " + jwtToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(requestBody))
    .build();

Services Overview - Learn about all 7 services
Request Model - Understand request structure
Validation - Test configurations before dispatch
Providers Reference - Detailed provider docs

Summary

Key takeaways:

3-tier resolution: Company Default → User Override → Explicit Request
Explicit wins: Always use providerName in request to override defaults
Configure via UI: Manage providers in Templater for security
Test with validation: Use /validate endpoint before real dispatch
Monitor usage: Track provider usage for billing and debugging

Understanding provider configuration is essential for production use. Once configured correctly, Dispatcher automatically routes requests to the right provider with the right credentials.

PreviousServices NextSync vs Async

Last updated 5 days ago

hashtagOverview

hashtagHow Provider Resolution Works

hashtagResolution Priority (Highest to Lowest)

hashtagReal-World Example

hashtagScenario Setup

hashtagResolution Examples

hashtagExample 1: No Explicit Provider (Uses Defaults)

hashtagExample 2: Explicit Provider (Overrides Everything)

hashtagProvider Configuration Structure

hashtagConfiguration Storage

hashtagCommon Configuration Fields

hashtagProvider-Specific Config Examples

hashtagInvoicing: Qonto

hashtageSign: Universign

hashtagSMS: Brevo

hashtagPostal: MySendingBox

hashtagAvailable Providers

hashtagInvoicing (4 providers)

hashtageSign (3 providers)

hashtagPostal (1 provider)

hashtagSMS (4 providers)

hashtagEmail (Built-in SMTP)

hashtagFile & Upload

hashtagSetting Up Provider Configurations

hashtagCompany-Level Setup (Admins Only)

hashtagUser-Level Setup

hashtagMulti-Provider Scenarios

hashtagScenario 1: Different Providers Per User

hashtagScenario 2: Multiple Providers for Same Service

hashtagScenario 3: Sandbox vs Production

hashtagCommon Configuration Issues

hashtagIssue 1: "Provider not configured" (400)

hashtagIssue 2: "Invalid provider credentials" (502)

hashtagIssue 3: "Provider not supported for service" (400)

hashtagBest Practices

hashtag1. Use Company Defaults for Consistency

hashtag2. User Overrides for Special Cases

hashtag3. Explicit Providers for Edge Cases

hashtag4. Test with Validation Endpoint

hashtag5. Secure Credential Storage

hashtag6. Monitor Provider Usage

hashtagCode Examples

hashtagExample 1: Using Company Default

hashtagExample 2: Explicit Provider Override

hashtagRelated Documentation

hashtagSummary

Overview

How Provider Resolution Works

Resolution Priority (Highest to Lowest)

Real-World Example

Scenario Setup

Resolution Examples

Example 1: No Explicit Provider (Uses Defaults)

Example 2: Explicit Provider (Overrides Everything)

Provider Configuration Structure

Configuration Storage

Common Configuration Fields

Provider-Specific Config Examples

Invoicing: Qonto

eSign: Universign

SMS: Brevo

Postal: MySendingBox

Available Providers

Invoicing (4 providers)

eSign (3 providers)

Postal (1 provider)

SMS (4 providers)

Email (Built-in SMTP)

File & Upload

Setting Up Provider Configurations

Company-Level Setup (Admins Only)

User-Level Setup

Multi-Provider Scenarios

Scenario 1: Different Providers Per User

Scenario 2: Multiple Providers for Same Service

Scenario 3: Sandbox vs Production

Common Configuration Issues

Issue 1: "Provider not configured" (400)

Issue 2: "Invalid provider credentials" (502)

Issue 3: "Provider not supported for service" (400)

Best Practices

1. Use Company Defaults for Consistency

2. User Overrides for Special Cases

3. Explicit Providers for Edge Cases

4. Test with Validation Endpoint

5. Secure Credential Storage

6. Monitor Provider Usage

Code Examples

Example 1: Using Company Default

Example 2: Explicit Provider Override

Related Documentation

Summary