📖Dispatcher OpenAPI

Complete API reference for Docs-Dispatcher services.

OpenAPI Specification

The Dispatcher API is fully documented using OpenAPI 3.0.4 specification.

Specification URL: https://api.docs-dispatcher.io/docs/swagger.json

Current Version: OpenAPI 3.0.4

Interactive Documentation

Access the interactive API documentation:

ReDoc (Clean API Documentation)

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

Features:

• Clean, readable interface

• Search functionality

• Code samples in multiple languages

• Mobile-friendly

SwaggerUI (Interactive API Explorer)

https://api.docs-dispatcher.io/docs/swagger

Features:

• Try API calls directly from the browser

• Authentication setup

• Request/response examples

• Schema exploration

Download Specification

OpenAPI JSON:

curl https://api.docs-dispatcher.io/docs/swagger.json > dispatcher-api.json

API Overview

Base URL

https://api.docs-dispatcher.io

Authentication

All endpoints require JWT Bearer authentication:

Authorization: Bearer <JWT_TOKEN>

See Get a JWT for authentication workflow.

Content Type

All requests must include:

Content-Type: application/json

Main Endpoints

Health Check

GET /healthz

Authentication: Not required

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 1234567
}

Service Dispatch

POST /api/{service}
POST /api/{service}/{composable1}
POST /api/{service}/{composable1}/{composable2}

Services:

• invoicing - Invoice, quote, credit note generation

• esign - Electronic signature workflows

• postal - Physical mail dispatch

• sms - SMS messaging

• email - Email dispatch

• file - Document generation

• upload - File upload

Query Parameters:

• async - Boolean (default: false) - Use async mode

Example:

POST /api/invoicing?async=true

Validation

POST /api/{service}/validate

Validate request without executing (no provider calls, no charges).

Configuration

GET /api/configurations
GET /api/configurations/{type}/config
GET /api/configurations/{type}/providers
POST /api/configurations/{type}/validate

List and validate provider configurations.

Webhooks

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

Provider webhook callbacks.

Request Schema

CompositeRequest

The main request object supports multiple service types:

Request Types:

• BasicRequest - File generation

• EmailRequest - Email dispatch

• PostalRequest - Postal mail

• ESignRequest - Electronic signature

• InvoiceRequest - Invoicing

• SMSRequest - SMS messaging

• BasicListRequest - Batch operations

Common Fields:

{
  "providerName": "string",
  "template": {
    "id": "number",
    "name": "string",
    "data": {}
  },
  "metadata": {}
}

See Request Model for complete schema.

Response Formats

Success Response (Sync)

{
  "success": true,
  "dispatchId": "disp_abc123",
  "providerResponse": {
    // Provider-specific response
  },
  "generatedDocument": {
    "url": "https://...",
    "size": 245678
  }
}

Success Response (Async)

{
  "success": true,
  "dispatchId": "disp_abc123",
  "status": "queued",
  "message": "Request queued for processing"
}

Error Response

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    // Additional error context
  }
}

HTTP Status Codes

Code	Description	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid request data, missing fields
401	Unauthorized	Invalid or expired JWT token
403	Forbidden	Insufficient permissions
404	Not Found	Template or resource not found
409	Conflict	Duplicate resource (e.g., invoice number)
415	Unsupported Media Type	Missing or invalid Content-Type header
417	Expectation Failed	Missing required parameters
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
503	Service Unavailable	Provider temporarily unavailable

See Common Errors for detailed error handling.

Security Schemes

Bearer Authentication (JWT)

bearerAuth:
  type: http
  scheme: bearer
  bearerFormat: JWT

Usage:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Validity: 120 minutes

See Authentication for obtaining tokens.

Rate Limits

Endpoint	Limit	Window
/auth	10 requests	per minute
/api/* (dispatch)	100 requests	per minute
/api/*/validate	20 requests	per minute

Rate Limit Headers:

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

Pagination

List endpoints support pagination:

Query Parameters:

• page - Page number (1-indexed)

• limit - Items per page (default: 20, max: 100)

Response Headers:

X-Total-Count: 250
X-Page-Count: 13
Link: <https://api.../next>; rel="next", <https://api.../prev>; rel="prev"

Code Generation

Generate client code from the OpenAPI spec:

Using OpenAPI Generator

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Download spec
curl https://api.docs-dispatcher.io/docs/swagger.json > dispatcher-api.json

# Generate TypeScript client
openapi-generator-cli generate \
  -i dispatcher-api.json \
  -g typescript-axios \
  -o ./generated-client

# Generate Python client
openapi-generator-cli generate \
  -i dispatcher-api.json \
  -g python \
  -o ./python-client

# Generate Go client
openapi-generator-cli generate \
  -i dispatcher-api.json \
  -g go \
  -o ./go-client

Using Swagger Codegen

# Install Swagger Codegen
brew install swagger-codegen

# Generate Ruby client
swagger-codegen generate \
  -i https://api.docs-dispatcher.io/docs/swagger.json \
  -l ruby \
  -o ./ruby-client

Postman Collection

Import the API into Postman:

1. Open Postman

2. Click "Import" → "Link"

3. Enter: https://api.docs-dispatcher.io/docs/swagger.json

4. Configure authentication (Bearer token)

Alternatively, download the spec and import the file.

Testing with cURL

Health Check

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

Authenticated Request

export JWT_TOKEN="your-jwt-token"

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

Schema Validation

The API validates all requests against JSON Schema definitions.

Get Schema for a Service:

curl https://api.docs-dispatcher.io/api/configurations/invoicing/config \
  -H "Authorization: Bearer $JWT_TOKEN"

Response:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Invoicing Configuration",
  "type": "object",
  "properties": {
    // Schema definition
  },
  "required": ["field1", "field2"]
}

Versioning

The API uses URL-based versioning:

Current: v1 (implicit in /api/ endpoints)

Future versions:

• /api/v2/ - When introduced, v1 will be supported for 6 months

See Changelog for version history.

Support

• Interactive Docs: https://api.docs-dispatcher.io/docs

• OpenAPI Spec: https://api.docs-dispatcher.io/docs/swagger.json

• Issues: GitHub (TBD)

• Email: [email protected]

Next Steps

• Authentication Guide - Get your JWT token

• Core Concepts - Understand the request structure

• Recipes - Step-by-step integration examples

• SDKs - Use official client libraries instead of raw HTTP