🚀Quickstart (Mock Sandbox)

Get started with Docs-Dispatcher in 5 minutes using the validation endpoint - no real API calls, no provider configuration needed.

What You'll Do

In this quickstart, you'll:

1. Get a JWT authentication token

2. Validate an invoice request (without sending it)

3. Understand the request/response format

4. See what a successful dispatch looks like

No risk: The validation endpoint checks your request format without calling external providers or charging credits.

Prerequisites

• An account on Docs-Dispatcher (sign up at TBD)

• curl or an HTTP client

• No provider configuration needed for validation

Step 1: Get Your JWT Token

First, authenticate to get a JWT token:

curl -X POST https://api.docs-dispatcher.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-02-13T14:13:00Z"
}

Save the token - you'll use it in the next step:

export JWT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Validity: JWT tokens expire after 120 minutes. See Get a JWT for refresh workflow.

Step 2: Validate an Invoice Request

Now send a validation request to test your invoice format:

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": {
        "invoiceNumber": "INV-2026-001",
        "date": "2026-02-13",
        "dueDate": "2026-03-13",
        "customer": {
          "name": "Acme Corp",
          "email": "[email protected]",
          "address": "123 Main St, Paris, France"
        },
        "items": [
          {
            "description": "Web Development Services",
            "quantity": 10,
            "unitPrice": 150.00,
            "total": 1500.00
          }
        ],
        "subtotal": 1500.00,
        "taxRate": 0.20,
        "taxAmount": 300.00,
        "total": 1800.00
      }
    }
  }'

Success Response:

{
  "valid": true,
  "message": "Request is valid and ready for dispatch",
  "warnings": []
}

Validation Error Example:

{
  "valid": false,
  "errors": [
    {
      "field": "template.data.dueDate",
      "message": "Due date must be after invoice date"
    }
  ]
}

What just happened?

• Dispatcher validated your request structure

• Checked required fields for Qonto provider

• Verified date logic and calculations

• Did NOT call Qonto API or send the invoice

• Did NOT charge any credits

Step 3: Understand the Request Format

Let's break down the validation request:

providerName (required)

"providerName": "qonto"

Specifies which invoicing provider to use. Options:

• ipaidthat - iPaidThat

• qonto - Qonto

• pennylane - PennyLane

• superpdp - SuperPDP

documentType (required)

"documentType": "INVOICE"

What type of document to generate:

• INVOICE - Standard invoice

• E_INVOICE - Electronic invoice (France)

• QUOTE - Quote/Devis

• CREDIT - Credit note/Avoir

template (required)

"template": {
  "id": 123,
  "data": { ... }
}

• id - Template ID from Templater (created via UI or API)

• data - JSON object with template variables

Template Data Schema: Each template has its own data schema. The validation endpoint checks that your data matches the template's expected structure.

Step 4: Send a Real Invoice

Once your request validates successfully, change /validate to actual dispatch:

# Change this:
POST /api/invoicing/validate

# To this:
POST /api/invoicing

Real Dispatch Example:

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

Success Response:

{
  "success": true,
  "dispatchId": "disp_abc123def456",
  "providerResponse": {
    "invoiceId": "qonto_inv_789",
    "status": "sent",
    "url": "https://qonto.com/invoices/789"
  },
  "generatedDocument": {
    "url": "https://storage.docs-dispatcher.io/invoices/INV-2026-001.pdf",
    "size": 245678
  }
}

Real Dispatch Requirements:

• Provider must be configured (company or user level)

• Credits/billing must be set up

• External provider API credentials must be valid

• Will actually send the invoice to the customer

Next Steps

Now that you've validated your first request:

1. Set up provider configs - Configure Qonto, PennyLane, etc.

2. Full invoice recipe - Generate and send with all options

3. Async dispatch - Use webhooks for background processing

4. Use SDKs - Node.js, PHP, or Java instead of curl

Common Quickstart Issues

"Unauthorized" (401)

• JWT token expired (120min validity)

• Wrong credentials

• Fix: Get a new token via /auth

"Template not found" (404)

• Template ID doesn't exist

• Template belongs to different company

• Fix: Check template ID in Templater UI

"Invalid provider" (400)

• Provider name typo (case-sensitive)

• Provider not supported for service

• Fix: See Providers Overview for valid names

Validation Fails

• Check error messages for specific field issues

• Verify required fields for your provider

• Fix: See provider-specific docs for requirements

Validation vs Real Dispatch

Feature	/validate	Real dispatch
Checks request format	✅	✅
Validates field requirements	✅	✅
Calls external provider	❌	✅
Generates document	❌	✅
Sends to customer	❌	✅
Charges credits	❌	✅
Returns provider response	❌	✅

Quickstart Summary

You've learned:

• ✅ How to authenticate and get a JWT

• ✅ How to validate requests without risk

• ✅ The basic request structure for invoicing

• ✅ How to switch from validation to real dispatch

Ready for production? → Full Invoice Recipe