DOCAI Fluxx Service API Signature Doc

Overview

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

Service Architecture

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:

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

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

`getDocument()`

Signature:

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

Description: Retrieve document information by document ID.

Input Interfaces

`FileIntakeInput`

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:

{
    "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`

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:

{
    "success": true,
    "documentId": 12345,
    "documentHash": "a1b2c3d4e5f6...",
    "clientId": "default_client-123456",
    "clientIdHash": 987654321,
    "validationResults": {
        "isDuplicate": false,
        "validationPassed": true,
        "validationErrors": []
    }
}

Error Response Example:

{
    "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`

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:

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

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

`getExtractionResults()`

Signature:

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

Description: Retrieve extraction results by document ID.

Input Interfaces

`ExtractionInput`

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:

{
    "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`

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:

{
    "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:

{
    "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`

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`

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`

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`

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`

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

// 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

// 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

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

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

{
    success: false,
    error: "Error message with details",
    // Service-specific error details...
}

Database Schema Integration

Documents Table (File Intake Service)

[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)

[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])
);