🧾 IBPS Invoice Processing API

Complete API Documentation for Invoice Management System

🔐 Authentication

POST /signup/

Create a new user account

Request Body (JSON):

ParameterTypeDescription
user_namestringUsername required
user_passwordstringPassword required
mobile_nostringMobile number (max 13 chars) optional

Example Request:

{
    "user_name": "john_doe",
    "user_password": "securepass123",
    "mobile_no": "9876543210"
}

Success Response (201):

{
    "message": "User created successfully",
    "user_id": 1
}

Error Responses:

400: {"error": "user_name and user_password are required"}
400: {"error": "User already exists"}
POST /login/

Authenticate user and login

Request Body (JSON):

ParameterTypeDescription
user_namestringUsername required
user_passwordstringPassword required

Example Request:

{
    "user_name": "john_doe",
    "user_password": "securepass123"
}

Success Response (200):

{
    "message": "Login successful",
    "user_id": 1,
    "user_name": "john_doe",
    "is_admin": true
}

Error Responses:

400: {"error": "user_name and user_password are required"}
401: {"error": "Invalid credentials"}

🔧 Utility

GET /status/

Get all status codes and their descriptions from the status lookup table

Query Parameters:

ParameterTypeDescription
No parameters required

Example Request:

GET /status/

Success Response (200):

{
    "statuses": [
        {
            "status": "A",
            "description": "Approved"
        },
        {
            "status": "P",
            "description": "Pending"
        },
        {
            "status": "R",
            "description": "Rejected"
        }
    ],
    "total_count": 3
}

Error Responses:

405: {"error": "Only GET method allowed"}
500: {"error": "Database error message"}

📄 Invoice Management

POST /upload/

Upload a new invoice PDF document with optional metadata and supporting documents

Request Body (multipart/form-data):

ParameterTypeDescription
user_idstringUser ID (also accepts auth_id) required
filefileMain invoice PDF file required
vendor_namestringName of the vendor/supplier (max 30 chars) optional
vendor_tax_idstringVendor's tax identification number (max 30 chars) optional
invoice_nostringInvoice number/reference (max 30 chars) optional
invoice_datestringInvoice date (YYYY-MM-DD or DD-MM-YYYY format) optional
amtnumberInvoice amount optional
po_nostringPurchase Order number (max 100 chars) optional
supporting_doc_1fileFirst supporting document (any file type) optional
supporting_doc_2fileSecond supporting document (any file type) optional
remarksstringAdditional notes or remarks optional
📝 Field Descriptions
  • user_id/auth_id: Unique identifier for the user uploading the invoice
  • file: The main invoice document (must be PDF)
  • vendor_name: The company or person who issued the invoice
  • vendor_tax_id: Tax ID, VAT number, or GST number of the vendor
  • invoice_no: The invoice reference number as shown on the document
  • invoice_date: Date the invoice was issued
  • amt: Total invoice amount (decimal number)
  • po_no: Purchase Order number associated with the invoice
  • supporting_doc_1/2: Additional documents like contracts, POs, delivery notes
  • remarks: Any additional information or comments about the invoice

Example (curl):

curl -X POST http://localhost:8000/upload/ \
  -F "user_id=123" \
  -F "file=@/path/to/invoice.pdf" \
  -F "vendor_name=ABC Corp" \
  -F "vendor_tax_id=TAX123456" \
  -F "invoice_no=INV-2024-001" \
  -F "invoice_date=2024-12-10" \
  -F "amt=1500.50" \
  -F "supporting_doc_1=@/path/to/contract.pdf" \
  -F "remarks=Q4 payment"

Success Response (201):

{
    "message": "Invoice uploaded successfully",
    "invoice_id": 1,
    "file_path": "docs/123/invoice.pdf",
    "supporting_doc_1": "docs/123/support1_contract.pdf",
    "supporting_doc_2": null
}

Error Responses:

400: {"error": "user_id is required"}
400: {"error": "No file uploaded"}
400: {"error": "Only PDF files are allowed"}
GET /invoices/

Get all invoices for a specific user

Query Parameters:

ParameterTypeDescription
user_idstringUser ID required

Example Request:

GET /invoices/?user_id=123

Success Response (200):

{
    "invoices": [
        {
            "id": 1,
            "auth_id": "123",
            "file_name": "docs/123/invoice.pdf",
            "vendor_name": "ABC Corp",
            "vendor_tax_id": "TAX123456",
            "invoice_no": "INV-2024-001",
            "invoice_date": "2024-12-10",
            "amt": 1500.50,
            "supporting_doc_1": null,
            "supporting_doc_2": null,
            "remarks": null,
            "data_fetch": "Y",
            "invoice_source": "E",
            "po_no": "PO-123",
            "status_verification": "P"
        }
    ]
}
POST /update/invoice/{invoice_id}/

Update invoice details and supporting documents

URL Parameters:

ParameterTypeDescription
invoice_idintegerInvoice ID required

Request Body (multipart/form-data):

ParameterTypeDescription
file_namestringNew file name optional
vendor_namestringVendor name optional
vendor_tax_idstringVendor Tax ID optional
invoice_nostringInvoice number optional
invoice_datestringInvoice date (YYYY-MM-DD) optional
amtnumberInvoice amount optional
po_nostringPurchase Order number optional
remarksstringRemarks optional
supporting_doc_1fileFirst supporting document optional
supporting_doc_2fileSecond supporting document optional

Example Request:

POST /update/invoice/1/
Content-Type: multipart/form-data

vendor_name: Updated Vendor
amt: 2000.00

Success Response (200):

{
    "message": "Invoice updated successfully",
    "id": 1,
    "updated_fields": ["vendor_name", "amt"]
}

Error Responses:

404: {"error": "Invoice not found"}
405: {"error": "Only POST method allowed"}
500: {"error": "Internal server error"}
POST /update/status/{invoice_id}/

Update the status_verification field for an invoice

URL Parameters:

ParameterTypeDescription
invoice_idintegerInvoice ID required

Request Body (JSON):

ParameterTypeDescription
statusstringStatus value: 'R' (Rejected) or 'P' (Pending) required
📝 Allowed Status Values
  • R - Rejected
  • P - Pending

Status values are case-insensitive ('r', 'R', 'p', 'P' are all valid)

Example Request:

POST /update/status/123/
Content-Type: application/json

{
    "status": "R"
}

Success Response (200):

{
    "message": "Status updated successfully",
    "invoice_id": 123,
    "status_verification": "R"
}

Error Responses:

400: {"error": "status is required"}
400: {"error": "Invalid status 'X'. Only 'R' (Rejected) or 'P' (Pending) are allowed."}
404: {"error": "Invoice not found"}
405: {"error": "Only POST method allowed"}
GET /invoice/{invoice_id}/file/

Download the invoice PDF file

URL Parameters:

ParameterTypeDescription
invoice_idintegerInvoice ID required

Example Request:

GET /invoice/1/file/

Success Response:

Returns the PDF file with Content-Type: application/pdf

Error Responses:

404: {"error": "Invoice not found"}
404: {"error": "File not found on server"}
GET /invoice/{invoice_id}/data/

Get invoice details with AI-extracted data

URL Parameters:

ParameterTypeDescription
invoice_idintegerInvoice ID required

Example Request:

GET /invoice/1/data/

Success Response (200):

{
    "invoice": {
        "id": 1,
        "auth_id": "123",
        "file_name": "docs/123/invoice.pdf",
        "vendor_name": "ABC Corp",
        "vendor_tax_id": "TAX123456",
        "invoice_no": "INV-2024-001",
        "invoice_date": "2024-12-10",
        "amt": 1500.50,
        "data_fetch": "Y"
    },
    "invoice_data": {
        "id": 1,
        "status": "OK",
        "data": {
            "status": true,
            "data": {
                "language": "English",
                "vendor_name": "ABC Corp",
                "invoice_number": "INV-2024-001",
                "total_amt": 1500.50,
                "items": [...]
            }
        },
        "manual_verified": "N",
        "modified_by": "2024-12-10T10:30:00",
        "refetch": "N",
        "remarks": null
    }
}
POST /invoice/{invoice_id}/refetch/

Mark an invoice for reprocessing by AI

URL Parameters:

ParameterTypeDescription
invoice_idintegerInvoice ID required

Example Request:

POST /invoice/1/refetch/

Success Response (200):

{
    "message": "Invoice marked for refetching",
    "invoice_id": 1
}

⚙️ Invoice Processing

POST /process-invoices/

Process a specific invoice using AI extraction. Only the user who uploaded the invoice can process it.

Request Body (JSON or form-data):

FieldTypeDescription
invoice_idintegerThe ID of the invoice to process required
user_idstringUser ID who uploaded the invoice required
🔐 Permission Check

Only the user who uploaded the invoice (matching auth_id) can trigger processing.

Returns 403 Forbidden if user doesn't have permission.

Example Request:

POST /process-invoices/
Content-Type: application/json

{
    "invoice_id": 123,
    "user_id": "1"
}

Success Response (200):

{
    "message": "Invoice processed successfully",
    "invoice_id": 123,
    "result": {
        "invoice_id": 123,
        "status": "success",
        "message": "Processed successfully"
    }
}

Already Processed Response (200):

{
    "message": "Invoice already processed",
    "invoice_id": 123,
    "status": "already_processed"
}

Error Responses:

400: {"error": "invoice_id is required"}
400: {"error": "user_id is required"}
400: {"error": "invoice_id must be a valid integer"}
403: {"error": "Permission denied. You can only process invoices you uploaded."}
404: {"error": "Invoice not found"}
500: {"error": "Processing failed", "invoice_id": 123, "result": {...}}

📤 Direct Data Extraction

POST /invoice/extract-data/

Upload a PDF and extract invoice data using AI. Saves to invoice_direct_data table.

Request Body (multipart/form-data):

FieldTypeDescription
filefilePDF file to process required
📁 File Storage

Files are saved to: /direct_pdf/{client_ipv4}/{filename}.pdf

The client's IPv4 address is used to organize uploaded files.

Example Request:

POST /invoice/extract-data/
Content-Type: multipart/form-data

file: invoice.pdf

Success Response (201):

{
    "id": 1,
    "filename": "direct_pdf/192_168_1_100/invoice.pdf",
    "data": {
        "status": true,
        "message": "PDF processed successfully using raw PDF upload",
        "model": "gemini-2.5-pro",
        "data": {
            "language": "English",
            "type": "computerized",
            "vendor_name": "ABC Corp",
            "invoice_number": "INV-2024-001",
            "total_amt": 1500.50,
            "confidence": {...},
            "items": [...]
        }
    },
    "status": "OK"
}

Error Responses:

400: {"error": "No file uploaded"}
400: {"error": "Only PDF files are allowed"}
GET /invoice/extract-data/get/

Retrieve extracted data by ID from invoice_direct_data table

Query Parameters:

ParameterTypeDescription
idintegerRecord ID required

Example Request:

GET /invoice/extract-data/get/?id=1

Success Response (200):

{
    "id": 1,
    "data": {
        "status": true,
        "message": "PDF processed successfully using raw PDF upload",
        "model": "gemini-2.5-pro",
        "data": {
            "language": "English",
            "type": "computerized",
            "vendor_name": "ABC Corp",
            "invoice_number": "INV-2024-001",
            "total_amt": 1500.50,
            "confidence": {...},
            "items": [...]
        }
    },
    "status": "OK",
    "pdf_data": "base64_encoded_pdf_content..."
}

Error Responses:

400: {"error": "id is required"}
404: {"error": "Record not found"}
GET /invoice/extract-data/file/

Download the PDF file for a given invoice_direct_data record

Query Parameters:

ParameterTypeDescription
idintegerRecord ID required

Example Request:

GET /invoice/extract-data/file/?id=1

Success Response:

Returns the PDF file with Content-Type: application/pdf

Error Responses:

400: {"error": "id is required"}
404: {"error": "Record not found"}
404: {"error": "File not found on server"}
GET /check/

Interactive verification UI - displays PDF on one side and extracted data on the other

Query Parameters:

ParameterTypeDescription
idintegerRecord ID from invoice_direct_data table required

Example Usage:

Open in browser: /check/?id=1
🖥️ Visual Verification

This endpoint returns an interactive HTML page with:

  • PDF viewer on the left side
  • Extracted data with confidence scores on the right side
  • Support for translated data display
  • Line items display

📊 Analytics

POST /analytics/google/v1/

Process PDF using Google Gemini AI with usage tracking, pricing calculation, and database logging

Request Body (JSON):

ParameterTypeDescription
api_keystringAPI key for authentication required
modelstringGemini model name required
pdf_base64stringBase64 encoded PDF content required
pdf_namestringOriginal PDF filename optional
🤖 Supported Models
  • gemini-2.5-pro - Input: $1.25/1M tokens, Output: $10.00/1M tokens
  • gemini-3-pro-preview - Input: $2.00/1M tokens, Output: $12.00/1M tokens
  • gemini-3-pro-image-preview - Input: $2.00/1M tokens, Output: $12.00/1M tokens
  • gemini-2.0-flash - Input: $0.10/1M tokens, Output: $0.40/1M tokens

💰 Prices saved to database are converted to INR at 1 USD = 90 INR

Example Request:

{
    "api_key": "your_api_key",
    "model": "gemini-2.5-flash",
    "pdf_base64": "JVBERi0xLjQK...",
    "pdf_name": "invoice.pdf"
}

Success Response (200):

{
    "status": true,
    "message": "PDF processed successfully",
    "model": "gemini-2.5-flash",
    "token_usage": {
        "input_tokens": 1234,
        "output_tokens": 567,
        "total_tokens": 1801
    },
    "price": 0.00456,
    "time_taken": 3.45,
    "log_id": 123,
    "data": {
        "language": "English",
        "type": "computerized",
        "vendor_name": "ABC Corp",
        "invoice_number": "INV-2024-001",
        "total_amt": 1500.50,
        "items": [...]
    }
}
📈 Usage Logging

Each API call is logged to the invoice_time table with:

  • Company, plan, and model information
  • Token usage (input, output, total)
  • Calculated price based on token usage
  • API call and response timestamps
  • Time taken for processing
  • Full output from Gemini

Error Responses:

400: {"error": "api_key is required"}
400: {"error": "model is required"}
400: {"error": "pdf_base64 is required"}
400: {"error": "Invalid model. Supported models: ..."}
401: {"error": "Invalid API key"}
POST /analytics/vertex/v1/

Process PDF using Google Vertex AI with usage tracking, pricing calculation, and database logging

Request Body (JSON):

ParameterTypeDescription
api_keystringAPI key for authentication required
modelstringGemini model name required
pdf_base64stringBase64 encoded PDF content required
pdf_namestringOriginal PDF filename optional
project_idstringVertex AI project ID optional
locationstringVertex AI location (default: us-central1) optional
🤖 Supported Models (Vertex AI Pricing)
  • gemini-2.5-pro - Input: $1.25/1M tokens, Output: $10.00/1M tokens
  • gemini-2.5-flash - Input: $0.10/1M tokens, Output: $0.40/1M tokens
  • gemini-3-pro-preview - Input: $2.00/1M tokens, Output: $12.00/1M tokens
  • gemini-3-pro-image-preview - Input: $2.00/1M tokens, Output: $12.00/1M tokens

💰 Prices saved to database are converted to INR at 1 USD = 90 INR

Example Request:

{
    "api_key": "your_api_key",
    "model": "gemini-2.5-flash",
    "pdf_base64": "JVBERi0xLjQK...",
    "pdf_name": "invoice.pdf",
    "project_id": "my-project",
    "location": "us-central1"
}

Success Response (200):

{
    "status": true,
    "message": "PDF processed successfully via Vertex AI",
    "model": "gemini-2.5-flash",
    "token_usage": {
        "input_tokens": 1234,
        "output_tokens": 567,
        "total_tokens": 1801
    },
    "price": 0.41,
    "time_taken": 3.45,
    "log_id": 123,
    "data": {
        "language": "English",
        "type": "computerized",
        "vendor_name": "ABC Corp",
        "invoice_number": "INV-2024-001",
        "total_amt": 1500.50,
        "items": [...]
    }
}

Error Responses:

400: {"error": "api_key is required"}
400: {"error": "model is required"}
400: {"error": "pdf_base64 is required"}
400: {"error": "Invalid model. Supported models: ..."}
401: {"error": "Invalid API key"}
POST /analytics/google/v2/ ⚡ Optimized

Process PDF using Google AI Studio (Gemini) with reduced token usage - optimized prompt and generation config

Request Body (JSON):

ParameterTypeDescription
api_keystringAPI key for authentication required
modelstringGemini model name required
pdf_base64stringBase64 encoded PDF content required
pdf_namestringOriginal PDF filename optional
🤖 Supported Models (Same as V1)
  • gemini-2.5-pro - Input: $1.25/1M tokens, Output: $10.00/1M tokens
  • gemini-3-pro-preview - Input: $2.00/1M tokens, Output: $12.00/1M tokens
  • gemini-3-pro-image-preview - Input: $2.00/1M tokens, Output: $12.00/1M tokens
  • gemini-2.5-flash - Input: $0.30/1M tokens, Output: $2.50/1M tokens

💰 Prices saved to database are converted to INR at 1 USD = 90 INR

⚡ V2 Optimizations
  • Shorter prompt: ~50% fewer input tokens
  • temperature=0: Deterministic, consistent output
  • response_mime_type=json: No markdown wrapper, direct JSON
  • Expected savings: 20-40% lower cost with same accuracy

Example Request:

{
    "api_key": "your_api_key",
    "model": "gemini-2.5-flash",
    "pdf_base64": "JVBERi0xLjQK...",
    "pdf_name": "invoice.pdf"
}

Success Response (200):

{
    "status": true,
    "message": "PDF processed (V2 optimized)",
    "model": "gemini-2.5-flash",
    "token_usage": {"input": 850, "output": 450, "total": 1300},
    "price": 0.00285,
    "time_taken": 2.8,
    "log_id": 456,
    "data": {...}
}
POST /analytics/vertex/v2/ ⚡ Optimized

Process PDF using Google Vertex AI with reduced token usage - optimized prompt and generation config

Request Body (JSON):

ParameterTypeDescription
api_keystringAPI key for authentication required
modelstringGemini model name required
pdf_base64stringBase64 encoded PDF content required
pdf_namestringOriginal PDF filename optional
project_idstringGoogle Cloud Project ID optional, uses default
locationstringVertex AI region (e.g., asia-south1) optional
🤖 Supported Models (Vertex AI Pricing)
  • gemini-2.5-pro - Input: $1.25/1M tokens, Output: $10.00/1M tokens
  • gemini-3-pro-preview - Input: $2.00/1M tokens, Output: $12.00/1M tokens
  • gemini-3-pro-image-preview - Input: $2.00/1M tokens, Output: $12.00/1M tokens
  • gemini-2.5-flash - Input: $0.30/1M tokens, Output: $2.50/1M tokens

💰 Prices saved to database are converted to INR at 1 USD = 90 INR

⚡ V2 Optimizations
  • Shorter prompt: ~50% fewer input tokens
  • temperature=0: Deterministic, consistent output
  • response_mime_type=json: No markdown wrapper, direct JSON
  • Expected savings: 20-40% lower cost with same accuracy

Example Request:

{
    "api_key": "your_api_key",
    "model": "gemini-2.5-flash",
    "pdf_base64": "JVBERi0xLjQK...",
    "pdf_name": "invoice.pdf",
    "project_id": "my-gcp-project",
    "location": "asia-south1"
}

Success Response (200):

{
    "status": true,
    "message": "PDF processed via Vertex AI (V2 optimized)",
    "model": "gemini-2.5-flash",
    "token_usage": {"input": 850, "output": 450, "total": 1300},
    "price": 0.00195,
    "time_taken": 2.5,
    "log_id": 789,
    "data": {...}
}

Error Responses:

400: {"error": "api_key is required"}
400: {"error": "model is required"}
400: {"error": "pdf_base64 is required"}
400: {"error": "Invalid model. Supported models: ..."}
401: {"error": "Invalid API key"}

🪝 Webhooks

ALL /webhook/

Receive webhook requests for all HTTP methods. POST requests with email data are saved to the email_invoice database table with attachments stored to filesystem.

📧 Email Data Storage (Microsoft 365 Webhooks)

For POST requests containing email data from Microsoft 365, the data is stored in the email_invoice database table:

  • messageId, subject, bodyPreview, etc. - Saved to database columns
  • attachments - Files are decoded from base64 and saved to /email/webhook/{row_id}/{filename}
  • Only attachment filenames are stored in the database JSON column

Request Body (JSON for email webhook):

{
    "messageId": "AAMkADhlMWZl...",
    "subject": "Invoice Attached",
    "bodyPreview": "Please find attached...",
    "toRecipients": "user@example.com",
    "attachments": "[{\"name\":\"invoice.pdf\",\"contentBytes\":\"JVBERi0xLjQ...\"}]"
}

Success Response (200):

{
    "status": "success",
    "message": "Webhook received and logged",
    "timestamp": "2024-12-15T10:30:00.123456",
    "method": "POST",
    "db_row_id": 123
}
📁 Log Storage

All webhook requests are also logged to webhook_logs.json.

GET /webhook/show/

Display all logged webhooks from webhook_logs.json as JSON, sorted by timestamp (newest first)

Example Request:

GET /webhook/show/

Success Response (200):

{
    "total_webhooks": 3,
    "logs": {
        "2024-12-15T10:30:00.123456": {
            "method": "POST",
            "data": {...},
            "headers": {...}
        }
    }
}
GET /webhook/data/

Display all stored email records from email_invoice table with PDF/image preview on left and email data on right

🖥️ Visual Interface

Returns an interactive HTML page with:

  • Left panel: PDF viewer and image previews for attachments
  • Right panel: Email metadata (subject, from, to, body preview, etc.)
  • Statistics showing total email count

Example Request:

Open in browser: /webhook/data/
GET /webhook/attachment/{row_id}/{filename}

Serve attachment file from filesystem for viewing or download

URL Parameters:

ParameterTypeDescription
row_idintegerDatabase row ID required
filenamestringAttachment filename required

Example Request:

GET /webhook/attachment/123/invoice.pdf

Success Response:

Returns the file with appropriate Content-Type header

Error Responses:

404: {"error": "File not found"}