> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://cla-demo.postmansolutions.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://cla-demo.postmansolutions.com/_mcp/server.

# DOCAI Fluxx Service API Signature Doc

## Overview

This document provides comprehensive API signatures and TypeScript payload definitions for the Document AI microservices.

## Service Architecture

```mermaid

graph LR

    A[fluxx-file-intake] --> B[DocAI Invoice File Intake Service]

    C[fluxx-extraction-service] --> D[DocAI Invoice Extraction Service]

    B --> E[(Documents Table)]

    D --> E

    D --> F[(ExtractedEntities Table)]

```

---

## Document AI Invoice File Intake Service

**Service Name**: `docai_invoice_file_intake_service`

**Called By**: `fluxx-file-intake` microservice

**Location**: `/src/docai-invoice-file-intake-service/`

### API Methods

#### `processFileIntake()`

**Signature:**

```typescript

public async processFileIntake(input: FileIntakeInput): Promise<FileIntakeResult>

```

**Description:** Main entry point for document intake, validation, and duplicate detection.

#### `getDocument()`

**Signature:**

```typescript

public async getDocument(documentId: number): Promise<DocumentRecord | null>

```

**Description:** Retrieve document information by document ID.

### Input Interfaces

#### `FileIntakeInput`

```typescript

export interface FileIntakeInput {

    clientId: string;           // Provided directly (e.g., "default_client-123456")

    pdfPath: string;            // Azure Blob Storage path to PDF

    pdfPrefix: string;          // Blob path prefix

    clientConfig: ClientConfig; // Full client configuration object

}

```

**Example Payload:**

```json

{

    "clientId": "default_client-123456",

    "pdfPath": "invoices/2024/11/invoice_001.pdf",

    "pdfPrefix": "invoices/2024/11/",

    "clientConfig": {

        "client_name": "Acme Corporation",

        "client_number": "ACME001",

        "client_id": "default_client-123456",

        "intake_config": {

            "verify_po_number": true

        },

        "ingest_config": {

            "unique_identifier_fields": ["invoice_number", "vendor_name"],

            "openai_config": {

                "model": "gpt-4",

                "prompt": "Extract invoice data...",

                "role": "system"

            }

        }

    }

}

```

### Output Interfaces

#### `FileIntakeResult`

```typescript

export interface FileIntakeResult {

    success: boolean;

    documentId: number;         // Documents.DocumentId

    documentHash: string;       // Documents.DocumentHash

    clientId: string;           // Client ID as string

    clientIdHash: number;       // Converted to number for SQL ClientId column

    error?: string;

    validationResults?: {

        isDuplicate: boolean;

        duplicateReason?: string;

        validationPassed: boolean;

        validationErrors?: string[];

    };

}

```

**Success Response Example:**

```json

{

    "success": true,

    "documentId": 12345,

    "documentHash": "a1b2c3d4e5f6...",

    "clientId": "default_client-123456",

    "clientIdHash": 987654321,

    "validationResults": {

        "isDuplicate": false,

        "validationPassed": true,

        "validationErrors": []

    }

}

```

**Error Response Example:**

```json

{

    "success": false,

    "documentId": 0,

    "documentHash": "",

    "clientId": "default_client-123456",

    "clientIdHash": 987654321,

    "error": "Document validation failed: Missing required field 'invoice_number'",

    "validationResults": {

        "isDuplicate": false,

        "validationPassed": false,

        "validationErrors": ["Missing required field 'invoice_number'"]

    }

}

```

#### `DocumentRecord`

```typescript

export interface DocumentRecord {

    DocumentId: number;

    BlobPath: string;

    ClientId: number;          // Stored as BIGINT in SQL

    DateUploaded: Date;

    DocumentHash: string;

    Name: string;

}

```

---

## Document AI Invoice Extraction Service

**Service Name**: `docai_invoice_extraction_service`

**Called By**: `fluxx-extraction-service` microservice

**Location**: `/src/docai-invoice-extraction-service/`

### API Methods

#### `processInvoiceExtraction()`

**Signature:**

```typescript

public async processInvoiceExtraction(input: ExtractionInput): Promise<ExtractionResult>

```

**Description:** Main entry point for PDF processing, AI extraction, and entity mapping.

#### `getExtractionResults()`

**Signature:**

```typescript

public async getExtractionResults(documentId: number): Promise<ExtractedEntitiesRecord | null>

```

**Description:** Retrieve extraction results by document ID.

### Input Interfaces

#### `ExtractionInput`

```typescript

export interface ExtractionInput {

    documentId: number;          // Documents.DocumentId from File Intake Service

    clientId: string;            // Client ID as string from File Intake Service

    documentHash: string;        // Documents.DocumentHash from File Intake Service

    pdfPath: string;             // Documents.BlobPath from File Intake Service

    pdfPrefix: string;           // Blob path prefix

    clientConfig: ClientConfig;  // Full client configuration object

    imageUrls?: string[];        // Pre-generated image URLs (optional)

    imagePrefixes?: string[];    // Image path prefixes (optional)

}

```

**Example Payload:**

```json

{

    "documentId": 12345,

    "clientId": "default_client-123456",

    "documentHash": "a1b2c3d4e5f6...",

    "pdfPath": "invoices/2024/11/invoice_001.pdf",

    "pdfPrefix": "invoices/2024/11/",

    "clientConfig": {

        "client_name": "Acme Corporation",

        "client_number": "ACME001",

        "client_id": "default_client-123456",

        "ingest_config": {

            "openai_config": {

                "model": "gpt-4",

                "prompt": "Extract the following fields from this invoice...",

                "retry_prompt": "Please try again with more detail...",

                "role": "system"

            },

            "freight_patterns": [

                {

                    "vendor": "FedEx",

                    "patterns": ["freight", "shipping", "delivery"]

                }

            ],

            "freight_as_line_item": true

        }

    },

    "imageUrls": ["images/invoice_001_page_1.png"],

    "imagePrefixes": ["images/"]

}

```

### Output Interfaces

#### `ExtractionResult`

```typescript

export interface ExtractionResult {

    success: boolean;

    documentId: number;

    extractedEntityId?: number;  // ExtractedEntities.ExtractedEntityId

    extractedData?: InvoiceExtractionData;

    error?: string;

    processingSteps?: {

        imagesGenerated: boolean;

        boundingRegionsExtracted: boolean;

        aiExtractionCompleted: boolean;

        invoiceMapped: boolean;

        transformationCompleted: boolean;

        postProcessingCompleted: boolean;

    };

}

```

**Success Response Example:**

```json

{

    "success": true,

    "documentId": 12345,

    "extractedEntityId": 67890,

    "extractedData": {

        "invoiceNumber": "INV-2024-001",

        "invoiceDate": "2024-01-15",

        "dueDate": "2024-02-15",

        "vendorName": "Sample Vendor Inc.",

        "vendorAddress": "123 Vendor St, City, ST 12345",

        "totalAmount": 1250.00,

        "subTotal": 1200.00,

        "taxAmount": 50.00,

        "extractionMethod": "ai",

        "confidence": 0.89,

        "processingDate": "2024-11-17T10:30:00Z",

        "lineItems": [

            {

                "description": "Professional Services",

                "quantity": 10,

                "unitPrice": 100.00,

                "amount": 1000.00,

                "lineNumber": 1

            },

            {

                "description": "Materials",

                "quantity": 1,

                "unitPrice": 200.00,

                "amount": 200.00,

                "lineNumber": 2

            }

        ]

    },

    "processingSteps": {

        "imagesGenerated": true,

        "boundingRegionsExtracted": true,

        "aiExtractionCompleted": true,

        "invoiceMapped": true,

        "transformationCompleted": true,

        "postProcessingCompleted": true

    }

}

```

**Error Response Example:**

```json

{

    "success": false,

    "documentId": 12345,

    "error": "AI extraction failed: Unable to process PDF due to poor image quality",

    "processingSteps": {

        "imagesGenerated": true,

        "boundingRegionsExtracted": false,

        "aiExtractionCompleted": false,

        "invoiceMapped": false,

        "transformationCompleted": false,

        "postProcessingCompleted": false

    }

}

```

#### `InvoiceExtractionData`

```typescript

export interface InvoiceExtractionData {

    invoiceNumber?: string;

    invoiceDate?: string;          // ISO date string

    dueDate?: string;              // ISO date string

    vendorName?: string;

    vendorAddress?: string;

    totalAmount?: number;

    subTotal?: number;

    taxAmount?: number;

    lineItems?: LineItem[];

    extractionMethod: 'ai' | 'document_intelligence' | 'hybrid';

    confidence: number;            // 0.0 to 1.0

    processingDate: string;        // ISO timestamp

    rawAiData?: any;               // Raw AI service response

    rawDiData?: any;               // Raw Document Intelligence response

}

```

#### `LineItem`

```typescript

export interface LineItem {

    description?: string;

    quantity?: number;

    unitPrice?: number;

    amount?: number;

    account?: string;              // Accounting code

    class?: string;                // Classification

    customer?: string;             // Customer reference

    item?: string;                 // Item code

    equipment?: string;            // Equipment reference

    lineNumber?: number;           // Line sequence

}

```

#### `ExtractedEntitiesRecord`

```typescript

export interface ExtractedEntitiesRecord {

    ExtractedEntityId: number;

    CreatedOn: Date;

    DateExported?: Date;

    DateFiled?: Date;

    DocumentId: number;

    ExtractedEntitiesPayload: string;  // JSON string of InvoiceExtractionData

    ModifiedOn: Date;

    Stage: string;                     // Current processing stage

    Status: string;                    // Current status

    Substatus?: string;                // Detailed substatus

}

```

---

## Common Interfaces

### `ClientConfig`

```typescript

export interface ClientConfig {

    client_name: string;

    client_number: string;

    client_id: string;

    stages?: {

        [stageName: string]: {

            is_entry?: boolean;

            is_exit?: boolean;

            show_in_stepper?: boolean;

            continue_on_success?: boolean;

            ordinal_pos?: number;

            workflow_name?: string;

            resolutions?: any;

        };

    };

    intake_config?: {

        verify_po_number?: boolean;

        [key: string]: any;

    };

    ingest_config?: {

        openai_config?: {

            prompt: string;

            retry_prompt: string;

            cprompt: string;            // Completion prompt

            role: string;

            mprompt: string;            // Manual prompt

            mrole: string;              // Manual role

            model: string;              // OpenAI model name

        };

        freight_as_line_item?: boolean;

        freight_patterns?: Array<{

            vendor: string;

            patterns: string[];

        }>;

        event_actions?: any;

        unique_identifier_fields?: string[];

        [key: string]: any;

    };

    [key: string]: any;

}

```

### `ProcessData`

```typescript

export interface ProcessData {

    documentId: number;          // Documents.DocumentId

    clientId: string;            // Client ID as string

    pdfPath: string;             // Documents.BlobPath

    pdfPrefix: string;

    clientConfig?: ClientConfig;

    imageUrls?: string[];

    imagePrefixes?: string[];

    diJsonUrl?: string;          // Document Intelligence JSON URL

    diJsonPrefix?: string;

    aiExtractedContent?: any;

}

```

---

## Service Factory Functions

### Document AI Invoice File Intake Service

```typescript

// Create service instance

export function createDocAiInvoiceFileIntakeService(

    databaseService?: IFileIntakeDatabaseService

): DocAiInvoiceFileIntakeService

  

// Initialize with configuration

export function initializeDocAiInvoiceFileIntakeService(

    config?: DocAiInvoiceFileIntakeServiceConfig

): DocAiInvoiceFileIntakeService

  

// Configuration interface

export interface DocAiInvoiceFileIntakeServiceConfig {

    database?: {

        connectionString: string;

        database: string;

        timeout?: number;

    };

    azure?: {

        blobStorageConnectionString: string;

    };

}

```

### Document AI Invoice Extraction Service

```typescript

// Create service instance

export function createDocAiInvoiceExtractionService(

    databaseService?: IExtractionDatabaseService

): DocAiInvoiceExtractionService

  

// Initialize with configuration

export function initializeDocAiInvoiceExtractionService(

    config?: DocAiInvoiceExtractionServiceConfig

): DocAiInvoiceExtractionService

  

// Configuration interface

export interface DocAiInvoiceExtractionServiceConfig {

    database?: {

        connectionString: string;

        database: string;

        timeout?: number;

    };

    azure?: {

        blobStorageConnectionString: string;

        documentIntelligenceEndpoint: string;

        documentIntelligenceKey: string;

    };

    ai?: {

        openaiApiKey: string;

        openaiEndpoint?: string;

    };

}

```

---

## Usage Examples

### File Intake Service Usage

```typescript

import {

    DocAiInvoiceFileIntakeService,

    FileIntakeInput,

    FileIntakeResult

} from './src/docai-invoice-file-intake-service';

  

const service = new DocAiInvoiceFileIntakeService();

  

const input: FileIntakeInput = {

    clientId: "default_client-123456",

    pdfPath: "invoices/2024/11/invoice_001.pdf",

    pdfPrefix: "invoices/2024/11/",

    clientConfig: {

        client_name: "Acme Corporation",

        client_id: "default_client-123456",

        intake_config: {

            verify_po_number: true

        }

    }

};

  

const result: FileIntakeResult = await service.processFileIntake(input);

  

if (result.success) {

    console.log(`Document processed: ID ${result.documentId}`);

} else {

    console.error(`Processing failed: ${result.error}`);

}

```

### Extraction Service Usage

```typescript

import {

    DocAiInvoiceExtractionService,

    ExtractionInput,

    ExtractionResult

} from './src/docai-invoice-extraction-service';

  

const service = new DocAiInvoiceExtractionService();

  

const input: ExtractionInput = {

    documentId: 12345,

    clientId: "default_client-123456",

    documentHash: "a1b2c3d4e5f6...",

    pdfPath: "invoices/2024/11/invoice_001.pdf",

    pdfPrefix: "invoices/2024/11/",

    clientConfig: {

        client_name: "Acme Corporation",

        client_id: "default_client-123456",

        ingest_config: {

            openai_config: {

                model: "gpt-4",

                prompt: "Extract invoice data...",

                role: "system"

            }

        }

    }

};

  

const result: ExtractionResult = await service.processInvoiceExtraction(input);

  

if (result.success && result.extractedData) {

    console.log(`Extracted invoice: ${result.extractedData.invoiceNumber}`);

    console.log(`Total amount: $${result.extractedData.totalAmount}`);

} else {

    console.error(`Extraction failed: ${result.error}`);

}

```

---

## Error Handling

Both services use consistent error handling patterns:

### Common Error Types

* **`INVALID_INPUT`**: Missing required fields or invalid data format

* **`DATABASE_ERROR`**: SQL Server connection or query failures

* **`AZURE_SERVICE_ERROR`**: Azure Blob Storage or Document Intelligence failures

* **`AI_SERVICE_ERROR`**: OpenAI API failures or timeout

* **`DUPLICATE_DOCUMENT`**: Document already exists (File Intake only)

* **`VALIDATION_ERROR`**: Business rule validation failures

### Error Response Structure

```typescript

{

    success: false,

    error: "Error message with details",

    // Service-specific error details...

}

```

---

## Database Schema Integration

### Documents Table (File Intake Service)

```sql

[Documents] (

    [DocumentId] BIGINT IDENTITY(1,1) PRIMARY KEY,

    [BlobPath] VARCHAR(800) NOT NULL,

    [ClientId] BIGINT NOT NULL,

    [DateUploaded] DATETIMEOFFSET DEFAULT SYSDATETIMEOFFSET(),

    [DocumentHash] VARCHAR(48) UNIQUE NOT NULL,

    [Name] VARCHAR(200) NOT NULL,

    FOREIGN KEY ([ClientId]) REFERENCES [dbo].[Clients]([ClientId])

);

```

### ExtractedEntities Table (Extraction Service)

```sql

[ExtractedEntities] (

    [ExtractedEntityId] BIGINT IDENTITY(1,1) PRIMARY KEY,

    [CreatedOn] DATETIMEOFFSET DEFAULT SYSDATETIMEOFFSET(),

    [DateExported] DATETIMEOFFSET,

    [DateFiled] DATETIMEOFFSET,

    [DocumentId] BIGINT NOT NULL,

    [ExtractedEntitiesPayload] NVARCHAR(MAX) NOT NULL,

    [ModifiedOn] DATETIMEOFFSET DEFAULT SYSDATETIMEOFFSET(),

    [Stage] VARCHAR(50) NOT NULL,

    [Status] VARCHAR(50) NOT NULL,

    [Substatus] VARCHAR(50),

    FOREIGN KEY ([DocumentId]) REFERENCES [dbo].[Documents]([DocumentId])

);

```