# Welcome to Docs-Dispatcher

> **Multi-service document generation and dispatch platform** Generate invoices, quotes, and documents, then dispatch them via email, postal, SMS, eSign, and upload services.

## What is Docs-Dispatcher?

Docs-Dispatcher is a comprehensive API platform that combines:

1. **Document Generation** - Create PDFs, DOCX, XLSX from templates using multiple rendering engines
2. **Multi-Provider Dispatch** - Send documents via 12+ external providers across 7 services
3. **Workflow Automation** - Chain services together (generate → validate → send)

### Key Services

| Service       | Providers                         | What it does                                                              |
| ------------- | --------------------------------- | ------------------------------------------------------------------------- |
| **Invoicing** | iPaidThat, Qonto, PennyLane       | Generate and send invoices, quotes, credit notes via accounting platforms |
| **eSign**     | Universign, Signaturit            | Electronic signature workflows                                            |
| **Postal**    | MySendingBox                      | Physical mail dispatch (print and post)                                   |
| **SMS**       | Brevo, OVH, SMS Factor, SMS Magic | SMS notifications                                                         |
| **Email**     | SMTP                              | Email dispatch                                                            |
| **File**      | Printer services                  | Document generation only (no external dispatch)                           |
| **Upload**    | Storage                           | File upload and storage                                                   |

## What's Covered in V1 (Dev/API Docs)

This documentation focuses on **Dispatcher API usage** for developers:

✅ **Covered:**

* API authentication (JWT)
* Service endpoints (POST /api/invoicing, etc.)
* Provider configuration and selection
* Request/response formats
* Validation endpoints (test without sending)
* Webhook events
* SDK usage (Node.js, PHP, Java)
* Error handling and troubleshooting

❌ **Not Covered in V1** (deferred to V2):

* Templater UI (template management interface)
* Template creation workflows
* Visual template designer
* Printer-api internals

**Why?** Most developers use Dispatcher programmatically via API. Template management is typically done once during setup, then automated via API.

## Quick Navigation

### First-Time Setup

1. [Quickstart (Mock Sandbox)](https://docs.docs-dispatcher.io/docs-dispatcher/start-here/quickstart) - Send your first invoice in 5 minutes
2. [Get a JWT](https://docs.docs-dispatcher.io/docs-dispatcher/authentication/get-jwt) - Authenticate with Dispatcher API
3. [Providers & Configurations](https://docs.docs-dispatcher.io/docs-dispatcher/core-concepts/providers-configurations) - Understand config resolution

### Common Tasks

* [Generate & Send an Invoice](https://docs.docs-dispatcher.io/docs-dispatcher/how-to-recipes/invoice)
* [Validate Before Sending](https://docs.docs-dispatcher.io/docs-dispatcher/how-to-recipes/validate-send)
* [Async Dispatch with Webhooks](https://docs.docs-dispatcher.io/docs-dispatcher/how-to-recipes/async-flow)
* [Troubleshoot Errors](https://docs.docs-dispatcher.io/docs-dispatcher/troubleshooting-and-errors/debug-checklist)

### Reference

* [All Providers](https://docs.docs-dispatcher.io/docs-dispatcher/providers/providers) - Capabilities matrix
* [Webhook Events](https://docs.docs-dispatcher.io/docs-dispatcher/webhooks/events) - Event catalog
* [OpenAPI Spec](https://docs.docs-dispatcher.io/docs-dispatcher/api-reference/dispatcher) - Full API reference

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                      Your Application                        │
└─────────────────┬───────────────────────────────────────────┘
                  │ HTTPS + JWT
                  ↓
┌─────────────────────────────────────────────────────────────┐
│                  Dispatcher API                             │
│                                                              │
│  Authentication:                                            │
│  - POST /auth (get JWT, 120min validity)                   │
│  - GET /auth/refresh (refresh token)                       │
│                                                              │
│  Service Orchestration:                                     │
│  - POST /api/invoicing                                      │
│  - POST /api/esign                                          │
│  - POST /api/postal                                         │
│  - POST /api/sms                                            │
│  - POST /api/email                                          │
│  - POST /api/file                                           │
│  - POST /api/upload                                         │
└─────────────────┬───────────────────────────────────────────┘
                  │ Multi-provider dispatch
                  ↓
┌─────────────────────────────────────────────────────────────┐
│            External Service Providers                       │
│  Invoicing: iPaidThat, Qonto, PennyLane          │
│  eSign: Universign, Signaturit                    │
│  Postal: MySendingBox                                       │
│  SMS: Brevo, OVH, SMS Factor, SMS Magic                    │
└─────────────────────────────────────────────────────────────┘
```

## Core Concepts

### 1. Hybrid Provider Configuration

Dispatcher uses a 3-tier resolution system:

```
Company Default Config → User Override → Explicit providerName in Request
```

**Example:**

* Company has Qonto configured as default invoicing provider
* User Alice has PennyLane override
* Request specifies `"providerName": "ipaidthat"`
* **Result:** iPaidThat is used (explicit wins)

👉 [Learn more about provider resolution](https://docs.docs-dispatcher.io/docs-dispatcher/core-concepts/providers-configurations)

### 2. Sync vs Async

All dispatch endpoints support `?async=true|false`:

* **Sync** (default): Wait for provider response, return result immediately
* **Async**: Queue request, return immediately, receive webhook on completion

👉 [When to use async](https://docs.docs-dispatcher.io/docs-dispatcher/core-concepts/sync-async)

### 3. Validation Endpoint

Test your request without actually sending:

```bash
POST /api/invoicing/validate
```

Returns validation errors without calling external providers or charging credits.

👉 [Validation workflow](https://docs.docs-dispatcher.io/docs-dispatcher/core-concepts/validation)

## Getting Started

**New to Docs-Dispatcher?** Start here:

1. [**Quickstart Guide**](https://docs.docs-dispatcher.io/docs-dispatcher/start-here/quickstart) - Send invoice using validation endpoint (no real API calls)
2. [**Authentication**](https://docs.docs-dispatcher.io/docs-dispatcher/authentication/get-jwt) - Get your JWT token
3. [**Invoice Recipe**](https://docs.docs-dispatcher.io/docs-dispatcher/how-to-recipes/invoice) - Generate and send a real invoice
4. [**SDK Overview**](https://docs.docs-dispatcher.io/docs-dispatcher/sdks/overview) - Use Node/PHP/Java SDK instead of curl

## Support & Resources

* **Issues & Bugs**: GitHub Issues (link TBD)
* **API Status**: <https://status.docs-dispatcher.io> (TBD)
* **Changelog**: [Version history](https://docs.docs-dispatcher.io/docs-dispatcher/start-here/changelog)

## Documentation Structure

This GitBook is organized by task (not by service layer):

* **Start Here**: Quick onboarding
* **Authentication**: JWT workflows
* **Core Concepts**: Understanding the platform
* **Recipes**: Step-by-step how-tos
* **Providers**: Per-provider details
* **Webhooks**: Event-driven workflows
* **SDKs**: Client libraries
* **Troubleshooting**: Debug guides
* **API Reference**: OpenAPI specs

***

**Ready to start?** → [Quickstart Guide](https://docs.docs-dispatcher.io/docs-dispatcher/start-here/quickstart)