✅Validation

Validation endpoints let you test dispatch requests without actually calling external providers or charging credits. This guide explains how validation works, its benefits, and how to use it effectively.

What is Validation?

Validation endpoints check if your dispatch request is correctly structured and ready for real dispatch without actually sending it.

Key Benefits

1. No external API calls - Providers are not contacted

2. No credits charged - Free to validate as many times as needed

3. Fast feedback - Validation completes in < 100ms

4. Catch errors early - Find issues before production

5. Safe testing - No risk of sending duplicate invoices/emails/SMS

What Gets Validated

Validation endpoints check:

• Request structure - Required fields present

• Field types - Correct data types (string, number, boolean)

• Field values - Valid enums, formats, ranges

• Provider compatibility - Provider supports service/document type

• Template existence - Template ID is valid

• Data schema - Template data matches expected schema

• Business rules - Dates, calculations, constraints

What Doesn't Get Validated

Validation endpoints do not check:

• Provider credentials - Not tested (no API call made)

• Template rendering - Document not generated

• External dependencies - Third-party APIs not called

• Rate limits - Not enforced during validation

• Account balance - Credits not checked

Validation Endpoints

All services have a validation endpoint:

POST /api/{service}/validate

Available Endpoints

Service	Validation Endpoint
Invoicing	POST /api/invoicing/validate
eSign	POST /api/esign/validate
Postal	POST /api/postal/validate
SMS	POST /api/sms/validate
Email	POST /api/email/validate
File	POST /api/file/validate
Upload	Not available (use multipart/form-data)

How Validation Works

Validation Flow

Client Request → Validation Endpoint
                        ↓
                 Parse & Validate
                        ↓
                 Check Template
                        ↓
                 Verify Schema
                        ↓
                 Return Result
                 (< 100ms)

No external calls:

• Provider APIs are not contacted

• Documents are not generated

• Credits are not charged

Using Validation Endpoints

Basic Example

curl -X POST https://api.docs-dispatcher.io/api/invoicing/validate \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "qonto",
    "documentType": "INVOICE",
    "template": {
      "id": 123,
      "data": {
        "invoiceNumber": "INV-2026-001",
        "date": "2026-02-13",
        "customer": {
          "name": "Acme Corp",
          "email": "[email protected]"
        },
        "items": [
          {
            "description": "Web Development",
            "quantity": 10,
            "unitPrice": 150.00,
            "total": 1500.00
          }
        ],
        "subtotal": 1500.00,
        "taxRate": 0.20,
        "taxAmount": 300.00,
        "total": 1800.00
      }
    }
  }'

Success Response

When validation passes:

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

Error Response

When validation fails:

{
  "valid": false,
  "errors": [
    {
      "field": "template.data.dueDate",
      "message": "Due date must be after invoice date",
      "value": "2026-02-01"
    },
    {
      "field": "template.data.total",
      "message": "Total (1800.00) does not match subtotal (1500.00) + tax (300.00)",
      "expected": 1800.00,
      "actual": 1700.00
    }
  ]
}

Warning Response

Validation passes but with warnings:

{
  "valid": true,
  "message": "Request is valid but has warnings",
  "warnings": [
    {
      "field": "template.data.customer.email",
      "message": "Email domain 'gmial.com' looks like a typo. Did you mean 'gmail.com'?",
      "suggestion": "gmail.com"
    }
  ]
}

Service-Specific Validation

Invoicing Validation

POST /api/invoicing/validate

Validates:

• Document type supported by provider

• Required fields for invoice/quote/credit

• Date logic (invoice date, due date)

• Calculations (subtotal + tax = total)

• Customer information

• Item line totals

Example:

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

  const validation = await response.json();

  if (!validation.valid) {
    console.error('Validation errors:', validation.errors);
    throw new Error('Invoice validation failed');
  }

  if (validation.warnings.length > 0) {
    console.warn('Validation warnings:', validation.warnings);
  }

  return validation;
};

eSign Validation

POST /api/esign/validate

Validates:

• Signer information (email, name)

• Signing order logic

• Signature type supported by provider

• Expiration settings

• Callback URL format

Example:

// PHP
function validateESignRequest($contractData, $signers) {
    $client = new \GuzzleHttp\Client();

    $response = $client->post(
        'https://api.docs-dispatcher.io/api/esign/validate',
        [
            'headers' => [
                'Authorization' => 'Bearer ' . $_ENV['JWT_TOKEN'],
                'Content-Type' => 'application/json'
            ],
            'json' => [
                'providerName' => 'universign',
                'template' => [
                    'id' => 456,
                    'data' => $contractData
                ],
                'signers' => $signers,
                'esign' => [
                    'signatureType' => 'ADVANCED',
                    'expiresInDays' => 30
                ],
            ]
        ]
    );

    $validation = json_decode($response->getBody(), true);

    if (!$validation['valid']) {
        throw new Exception('eSign validation failed: ' . json_encode($validation['errors']));
    }

    return $validation;
}

SMS Validation

POST /api/sms/validate

Validates:

• Phone number format (E.164: [phone])

• Message length (160 chars standard, 1530 concatenated)

• Sender ID format (11 chars max, alphanumeric)

• Provider supports destination country

Example:

// Java
public ValidationResult validateSMS(String phoneNumber, String message) throws Exception {
    Map<String, Object> request = Map.of(
        "providerName", "brevo",
        "sms", Map.of(
            "phoneNumber", phoneNumber,
            "message", message,
            "sender", "Acme"
        )
    );

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

    HttpResponse<String> response = client.send(
        httpRequest,
        HttpResponse.BodyHandlers.ofString()
    );

    ValidationResult result = new ObjectMapper().readValue(
        response.body(),
        ValidationResult.class
    );

    if (!result.isValid()) {
        throw new ValidationException(result.getErrors());
    }

    return result;
}

Postal Validation

POST /api/postal/validate

Validates:

• Recipient address completeness

• Country code format (ISO 3166-1 alpha-2)

• Postal code format for country

• Mail type supported by provider

Example:

# curl
curl -X POST https://api.docs-dispatcher.io/api/postal/validate \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "mysendingbox",
    "template": {
      "id": 789,
      "data": {
        "recipientName": "John Doe"
      }
    },
    "postal": {
      "mailType": "REGISTERED",
      "recipient": {
        "name": "John Doe",
        "company": "Acme Corp",
        "address": "123 Main St",
        "city": "Paris",
        "postalCode": "75001",
        "country": "FR"
      }
    }
  }'

Email Validation

POST /api/email/validate

Validates:

• Email address format

• Subject and body presence

• Attachment settings

• CC/BCC format

Example:

// Node.js
const validateEmail = async (emailData) => {
  const response = await fetch(
    'https://api.docs-dispatcher.io/api/email/validate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${jwtToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        template: {
          id: 123,
          data: emailData.templateData
        },
        email: {
          to: emailData.recipient,
          subject: emailData.subject,
          body: emailData.body,
          attachGenerated: true
        }
      })
    }
  );

  return await response.json();
};

Common Validation Errors

1. Missing Required Field

{
  "valid": false,
  "errors": [
    {
      "field": "documentType",
      "message": "Field 'documentType' is required for invoicing service"
    }
  ]
}

Fix: Add the missing field to your request.

2. Invalid Field Type

{
  "valid": false,
  "errors": [
    {
      "field": "template.id",
      "message": "Field 'template.id' must be a number, got string",
      "value": "123",
      "expectedType": "number"
    }
  ]
}

Fix: Change field type (e.g., "123" to 123).

3. Invalid Enum Value

{
  "valid": false,
  "errors": [
    {
      "field": "documentType",
      "message": "Invalid document type: 'RECEIPT'. Must be one of: INVOICE, E_INVOICE, QUOTE, CREDIT",
      "value": "RECEIPT",
      "validValues": ["INVOICE", "E_INVOICE", "QUOTE", "CREDIT"]
    }
  ]
}

Fix: Use a valid enum value.

4. Template Not Found

{
  "valid": false,
  "errors": [
    {
      "field": "template.id",
      "message": "Template with ID 999 not found or not accessible",
      "value": 999
    }
  ]
}

Fix: Verify template ID exists and belongs to your company.

5. Schema Mismatch

{
  "valid": false,
  "errors": [
    {
      "field": "template.data.customer.email",
      "message": "Field 'customer.email' is required by template schema",
      "requiredBy": "template_123"
    }
  ]
}

Fix: Add missing fields required by template schema.

6. Business Rule Violation

{
  "valid": false,
  "errors": [
    {
      "field": "template.data.dueDate",
      "message": "Due date (2026-01-01) must be after invoice date (2026-02-13)",
      "value": "2026-01-01",
      "constraint": "dueDate > invoiceDate"
    }
  ]
}

Fix: Adjust values to satisfy business rules.

Validation vs Real Dispatch

Comparison Table

Feature	Validation	Real Dispatch
Request structure	✅ Checked	✅ Checked
Required fields	✅ Validated	✅ Validated
Field types	✅ Validated	✅ Validated
Business rules	✅ Validated	✅ Validated
Template exists	✅ Checked	✅ Checked
Data schema	✅ Validated	✅ Validated
Provider API call	❌ Not called	✅ Called
Document generation	❌ Not generated	✅ Generated
External dispatch	❌ Not sent	✅ Sent
Credits charged	❌ Free	✅ Charged
Provider credentials	❌ Not tested	✅ Tested
Response time	< 100ms	Varies (1-120s)

From Validation to Real Dispatch

Once validation passes, simply change the endpoint:

# 1. Validate first
curl -X POST https://api.docs-dispatcher.io/api/invoicing/validate \
  -H "Authorization: Bearer $JWT" \
  -d @request.json

# If valid response received:
# {"valid": true, "message": "Request is valid and ready for dispatch"}

# 2. Then dispatch for real
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT" \
  -d @request.json

Same request body, different endpoint:

• /validate - Test without risk

• Real endpoint - Actually send

Using Validation for Testing

Development Workflow

// Development environment
const isDevelopment = process.env.NODE_ENV === 'development';

async function dispatchInvoice(invoiceData) {
  const endpoint = isDevelopment
    ? 'https://api.docs-dispatcher.io/api/invoicing/validate'
    : 'https://api.docs-dispatcher.io/api/invoicing';

  const response = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(invoiceData)
  });

  const result = await response.json();

  if (isDevelopment) {
    if (!result.valid) {
      console.error('Validation failed:', result.errors);
    } else {
      console.log('Validation passed! Ready for production.');
    }
  }

  return result;
}

Pre-Production Checks

Validate requests before production deployment:

// Test suite
describe('Invoice Dispatch', () => {
  it('should validate invoice request structure', async () => {
    const response = await fetch(
      'https://api.docs-dispatcher.io/api/invoicing/validate',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${testJwtToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          providerName: 'qonto',
          documentType: 'INVOICE',
          template: {
            id: 123,
            data: {
              invoiceNumber: 'TEST-001',
              customer: {...},
              items: [...],
              total: 1800.00
            }
          }
        })
      }
    );

    const validation = await response.json();

    expect(validation.valid).toBe(true);
    expect(validation.errors).toHaveLength(0);
  });
});

CI/CD Integration

Add validation to CI/CD pipelines:

# .github/workflows/test.yml
name: Test Dispatch Requests

on: [push, pull_request]

jobs:
  validate-requests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Validate Invoice Request
        run: |
          curl -X POST https://api.docs-dispatcher.io/api/invoicing/validate \
            -H "Authorization: Bearer ${{ secrets.JWT_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d @test-fixtures/invoice-request.json \
            --fail-with-body

      - name: Validate eSign Request
        run: |
          curl -X POST https://api.docs-dispatcher.io/api/esign/validate \
            -H "Authorization: Bearer ${{ secrets.JWT_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d @test-fixtures/esign-request.json \
            --fail-with-body

Best Practices

1. Always Validate Before Dispatch

// ✅ Good - validate first, then dispatch
async function safeDispatch(request) {
  // Step 1: Validate
  const validation = await validateRequest(request);

  if (!validation.valid) {
    throw new Error(`Validation failed: ${JSON.stringify(validation.errors)}`);
  }

  // Step 2: Dispatch
  return await dispatchRequest(request);
}

// ❌ Bad - dispatch without validation
async function unsafeDispatch(request) {
  return await dispatchRequest(request); // May fail with real API call
}

2. Handle Validation Errors Gracefully

async function dispatchWithValidation(request) {
  try {
    // Validate
    const validation = await fetch('/api/invoicing/validate', {
      method: 'POST',
      headers: {...},
      body: JSON.stringify(request)
    });

    const validationResult = await validation.json();

    if (!validationResult.valid) {
      // Show user-friendly errors
      const errorMessages = validationResult.errors.map(err =>
        `${err.field}: ${err.message}`
      ).join('\n');

      throw new ValidationError(errorMessages);
    }

    // Dispatch
    const dispatch = await fetch('/api/invoicing', {
      method: 'POST',
      headers: {...},
      body: JSON.stringify(request)
    });

    return await dispatch.json();

  } catch (error) {
    if (error instanceof ValidationError) {
      console.error('Validation failed:', error.message);
      // Show errors to user
    } else {
      console.error('Dispatch failed:', error);
      // Handle dispatch errors
    }
  }
}

3. Cache Validation Results

For repeated requests with same structure:

const validationCache = new Map();

async function validateWithCache(request) {
  const cacheKey = JSON.stringify(request);

  // Check cache
  if (validationCache.has(cacheKey)) {
    console.log('Using cached validation result');
    return validationCache.get(cacheKey);
  }

  // Validate
  const validation = await validateRequest(request);

  // Cache result (if valid)
  if (validation.valid) {
    validationCache.set(cacheKey, validation);
  }

  return validation;
}

4. Log Validation Failures

Track validation failures for debugging:

async function validateAndLog(request) {
  const validation = await validateRequest(request);

  if (!validation.valid) {
    logger.warn('Validation failed', {
      service: 'invoicing',
      errors: validation.errors,
      request: request,
      timestamp: new Date().toISOString()
    });
  }

  return validation;
}

5. Use Validation in Development

Enable auto-validation in development:

// config.js
const config = {
  autoValidate: process.env.NODE_ENV === 'development',
  validationEndpoint: 'https://api.docs-dispatcher.io/api/{service}/validate',
  dispatchEndpoint: 'https://api.docs-dispatcher.io/api/{service}'
};

// dispatcher.js
async function dispatch(service, request) {
  // Auto-validate in development
  if (config.autoValidate) {
    const validation = await validate(service, request);

    if (!validation.valid) {
      console.error('Auto-validation failed:', validation.errors);
      throw new Error('Request validation failed. See console for details.');
    }

    console.log('Auto-validation passed ✅');
  }

  // Actual dispatch
  return await dispatchRequest(service, request);
}

Validation Response Schema

Success Response

{
  valid: boolean;           // true
  message: string;          // "Request is valid and ready for dispatch"
  warnings: Array<{         // Optional warnings (non-blocking)
    field: string;
    message: string;
    suggestion?: string;
  }>;
}

Error Response

{
  valid: boolean;           // false
  errors: Array<{
    field: string;          // Field path (e.g., "template.data.dueDate")
    message: string;        // Human-readable error message
    value?: any;            // Actual value provided
    expectedType?: string;  // Expected type
    validValues?: any[];    // Valid enum values
    constraint?: string;    // Business rule violated
  }>;
}

Related Documentation

• Provider Configurations - Configure providers

• Request Model - Understand request structure

• Sync vs Async - Choose execution mode

• Quickstart - Validation in action

Summary

Validation endpoints are powerful tools for:

1. Risk-free testing - Validate without external calls or charges

2. Early error detection - Catch issues before dispatch

3. Development workflow - Test request structure during development

4. CI/CD integration - Validate requests in automated pipelines

5. User feedback - Provide immediate validation feedback

Key advantages:

• Free (no credits charged)

• Fast (< 100ms response)

• Safe (no external API calls)

• Comprehensive (checks structure, schema, business rules)

Remember:

• Validation checks request format, not provider credentials

• Always validate before real dispatch in production

• Use validation in development for faster feedback

• Handle validation errors gracefully with user-friendly messages

Validation is your safety net for building reliable integrations with Docs-Dispatcher.