6. API Specifications

6.1 API Design Principles

Standards:

RESTful design with resource-based URLs
JSON request/response bodies
HTTP status codes per RFC 7231
OAuth 2.0 Bearer token authentication
URL path versioning (/v1, /v2)
Consistent error response envelope
HATEOAS links for related resources (optional)

Base URL: https://api.egflow.com/v1

Response Envelope (All Responses):

{
  "success": true|false,
  "data": { },
  "metadata": {
    "timestamp": "ISO8601",
    "requestId": "uuid",
    "apiVersion": "1.0"
  },
  "errors": null|[]
}

6.2 Complete API Endpoint Catalog

6.2.1 Batch Management APIs

Method	Endpoint	Description	Auth Role	Rate Limit
POST	`/v1/organizations/{orgId}/batches`	Upload batch XML	Batch Operator	10/hour
POST	`/v1/organizations/{orgId}/batches/{batchId}/start`	Start processing	Batch Operator	30/hour
GET	`/v1/organizations/{orgId}/batches/{batchId}`	Get batch status	Read-Only	100/min
GET	`/v1/organizations/{orgId}/batches`	List batches (with filters)	Read-Only	100/min
GET	`/v1/organizations/{orgId}/batches/{batchId}/items`	List invoice items	Read-Only	100/min
GET	`/v1/organizations/{orgId}/batches/{batchId}/items/{itemId}`	Get item details	Read-Only	100/min
PUT	`/v1/organizations/{orgId}/batches/{batchId}`	Update batch metadata	Batch Operator	30/hour

6.2.2 Organization APIs

Method	Endpoint	Description	Auth Role	Rate Limit
GET	`/v1/organizations/{orgId}`	Get organization details	Read-Only	100/min
PUT	`/v1/organizations/{orgId}`	Update organization config	Org Admin	10/hour

6.2.3 Template APIs

Method	Endpoint	Description	Auth Role	Rate Limit
GET	`/v1/organizations/{orgId}/templates`	List templates (filter: category, status)	Read-Only	100/min
GET	`/v1/organizations/{orgId}/templates/{templateId}`	Get template details	Read-Only	100/min
GET	`/v1/organizations/{orgId}/template-categories`	List template categories	Read-Only	100/min

6.2.4 Schema Management APIs

Method	Endpoint	Description	Auth Role	Rate Limit
GET	`/v1/organizations/{orgId}/schemas`	List supported vendor formats	Read-Only	100/min
POST	`/v1/organizations/{orgId}/schemas/validate`	Pre-validate XML	Batch Operator	20/hour

6.2.5 Invoice APIs

Method	Endpoint	Description	Auth Role	Rate Limit
GET	`/v1/organizations/{orgId}/invoices/{invoiceId}/pdf`	Download PDF	Read-Only	1000/hour
GET	`/v1/organizations/{orgId}/invoices/{invoiceId}/html`	Download HTML	Read-Only	1000/hour

6.2.6 System APIs

Method	Endpoint	Description	Auth Role	Rate Limit
GET	`/v1/health`	Health check	None	Unlimited
GET	`/v1/version`	API version info	None	Unlimited

6.3 Detailed API Specifications

6.3.1 POST /organizations/{orgId}/batches (Batch Upload)

Purpose: Upload batch invoice XML file for processing

Request Headers:

Authorization: Bearer {jwt-token}
Content-Type: multipart/form-data

Request Body:

file: [XML file binary]
metadata: {
  "batchName": "Invoice_November_2025",
  "priority": "normal"
}

Success Response (201 Created):

{
  "success": true,
  "data": {
    "batchId": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "uploaded",
    "uploadedAt": "2025-11-21T10:30:00Z",
    "fileInfo": {
      "fileName": "invoices_nov.xml",
      "fileSize": 15728640,
      "checksum": "sha256:a3d5e7f9...",
      "detectedFormat": "GASEL"
    },
    "blobPath": "acme-batches-2025/11/21/550e8400.../source.xml"
  }
}

Error Responses:

// 400 Bad Request - Invalid XML
{
  "success": false,
  "errors": [{
    "code": "INVALID_XML",
    "message": "XML file is not well-formed",
    "field": "file",
    "details": {
      "line": 142,
      "column": 23,
      "error": "Unexpected end tag: </Invoice>",
      "suggestion": "Check that all opening tags have matching closing tags",
      "documentationUrl": "https://docs.egflow.com/errors/INVALID_XML"
    }
  }]
}

// 413 Payload Too Large
{
  "success": false,
  "errors": [{
    "code": "FILE_TOO_LARGE",
    "message": "File exceeds 100MB limit",
    "details": {
      "fileSize": 105906176,
      "limit": 104857600,
      "suggestion": "Split large batches into multiple files"
    }
  }]
}

// 415 Unsupported Media Type
{
  "success": false,
  "errors": [{
    "code": "UNSUPPORTED_FORMAT",
    "message": "Cannot detect vendor format",
    "details": {
      "detectedNamespace": "http://unknown.com/schema",
      "supportedFormats": ["GASEL", "XELLENT", "ZYNERGY"],
      "suggestion": "Ensure XML uses one of the supported vendor formats",
      "documentationUrl": "https://docs.egflow.com/vendor-formats"
    }
  }]
}

// 429 Too Many Requests
{
  "success": false,
  "errors": [{
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many batch uploads",
    "details": {
      "limit": 10,
      "window": "1 hour",
      "retryAfter": "2025-11-21T11:30:00Z"
    }
  }]
}

Response Headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 5
X-RateLimit-Reset: 1700226000
Location: /v1/organizations/{orgId}/batches/{batchId}

6.3.2 POST /organizations/{orgId}/batches/{batchId}/start

Purpose: Start asynchronous processing of uploaded batch

Request:

{
  "validationMode": "strict"
}

Success Response (202 Accepted):

{
  "success": true,
  "data": {
    "batchId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "queuedAt": "2025-11-21T10:35:00Z",
    "estimatedProcessingTime": "15-30 minutes",
    "queuePosition": 2
  }
}

Error Responses:

// 409 Conflict - Already Processing
{
  "success": false,
  "errors": [{
    "code": "CONFLICT",
    "message": "Batch is already processing",
    "details": {
      "currentStatus": "processing",
      "startedAt": "2025-11-21T10:00:00Z",
      "estimatedCompletionAt": "2025-11-21T11:30:00Z"
    }
  }]
}

// 503 Service Unavailable - Queue Full
{
  "success": false,
  "errors": [{
    "code": "SERVICE_UNAVAILABLE",
    "message": "System at capacity, retry later",
    "details": {
      "queueDepth": 10500,
      "estimatedWaitTime": "30-60 minutes",
      "retryAfter": "2025-11-21T11:00:00Z",
      "suggestion": "Consider scheduling batch for off-peak hours (22:00-06:00 CET)"
    }
  }]
}