• Bearer Token Authentication - Token-based secure access
• Basic Authentication - Username/Password support
• Multi-method Support - Use either authentication method
• Secure Credential Storage - Credentials stored in system parameters

• Transaction Details - Complete sales and return transaction records
• Line Item Details - Product-level data with tax information
• Payment Details - Multiple payment methods tracking (CASH, CARD, WALLET, OTHERS)
• Tax Calculation - Automatic tax computation with inclusive/exclusive support

• Dual Format Support - JSON (default) and XML responses
• Date Format Flexibility - Multiple date format support (YYYY-MM-DD, DD-Mon-YYYY, etc.)
• Location Filtering - Filter by specific POS locations/branches

• Immediate Data Access - Transaction data available immediately after POS operations
• Return Handling - Separate tracking of sales and return transactions
• Discount Tracking - Line-level and transaction-level discount information

Step 1: Configure Authentication Credentials

1. Navigate to Settings > General Settings
2. Scroll to Pathfinder Integra API section
3. Configure your authentication method:

Option A: Token Authentication (Recommended)
- Copy the automatically generated token
- Save the token securely for API requests

Option B: Basic Authentication
- Set a custom username
- Set a secure password
- Click "Save"

Step 2: Enable API for POS Locations

1. Go to Point of Sale > Configuration > Point of Sale
2. Open the POS configuration you want to enable
3. Check "Enable Pathfinder Integra API"
4. Save the configuration

Step 3: Test API Access

Use the examples in the API Examples section to verify your setup.

Endpoint

GET /api/integra/pos-data

Base URL Format:

https://your-odoo-domain.com/api/integra/pos-data

Authentication

Method 1: Bearer Token Authentication

Include the token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Method 2: Basic Authentication

Include username and password:

Authorization: Basic base64(username:password)

Parameters

Response Formats

JSON Response (Default)

Request with Accept: application/json header or no Accept header.

Structure:

{
  "Transactions": [
    {
      "LOCATION_CODE": "01",
      "TERMINAL_ID": "1",
      "SHIFT_NO": "1",
      "RCPT_NUM": "POS001",
      "RCPT_DT": "20240524",
      "BUSINESS_DT": "20240524",
      "RCPT_TM": "143000",
      "INV_AMT": "150.00",
      "TAX_AMT": "22.50",
      "RET_AMT": "0.00",
      "TRAN_STATUS": "SALES",
      "OP_CUR": "SAR",
      "BC_EXCH": "1.000",
      "DISCOUNT": "5.00",
      "ItemDetail": [...],
      "PaymentDetail": [...]
    }
  ]
}

XML Response

Request with Accept: application/xml header.

Structure:

<?xml version="1.0" encoding="UTF-8"?>
<Records>
  <TransactionDetails>
    <LOCATION_CODE>01</LOCATION_CODE>
    <TERMINAL_ID>1</TERMINAL_ID>
    <SHIFT_NO>1</SHIFT_NO>
    <RCPT_NUM>POS001</RCPT_NUM>
    <!-- Additional fields -->
  </TransactionDetails>
  <ItemDetails>
    <!-- Item data -->
  </ItemDetails>
  <PaymentDetails>
    <!-- Payment data -->
  </PaymentDetails>
</Records>

CURL Examples

Example 1: Token Authentication (JSON)

curl -X GET "https://your-odoo-domain.com/api/integra/pos-data?FromDt=2024-01-01&ToDt=2024-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Example 2: Basic Authentication (JSON)

curl -X GET "https://your-odoo-domain.com/api/integra/pos-data?FromDt=2024-01-01&ToDt=2024-01-31" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Accept: application/json"

Example 3: XML Response with Location Filter

curl -X GET "https://your-odoo-domain.com/api/integra/pos-data?FromDt=2024-01-01&ToDt=2024-01-31&LOCATION_CODE=2" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/xml"

Example 4: Alternative Date Format

curl -X GET "https://your-odoo-domain.com/api/integra/pos-data?FromDt=01-Jan-2024&ToDt=31-Jan-2024" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Python Examples

Example 1: Using Requests Library (Token Auth)

import requests
import json

# Configuration
base_url = "https://your-odoo-domain.com"
endpoint = "/api/integra/pos-data"
token = "YOUR_TOKEN_HERE"

# Parameters
params = {
    "FromDt": "2024-01-01",
    "ToDt": "2024-01-31"
}

# Headers
headers = {
    "Authorization": f"Bearer {token}",
    "Accept": "application/json"
}

# Make request
response = requests.get(
    f"{base_url}{endpoint}",
    params=params,
    headers=headers
)

# Check response
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Example 2: Basic Authentication

import requests
from requests.auth import HTTPBasicAuth

base_url = "https://your-odoo-domain.com"
endpoint = "/api/integra/pos-data"

params = {
    "FromDt": "2024-01-01",
    "ToDt": "2024-01-31",
    "LOCATION_CODE": "2"
}

response = requests.get(
    f"{base_url}{endpoint}",
    params=params,
    auth=HTTPBasicAuth('username', 'password'),
    headers={"Accept": "application/json"}
)

if response.status_code == 200:
    transactions = response.json()
    print(f"Retrieved {len(transactions.get('Transactions', []))} transactions")
else:
    print(f"Error: {response.status_code} - {response.text}")

Example 3: Processing XML Response

import requests
import xml.etree.ElementTree as ET

base_url = "https://your-odoo-domain.com"
endpoint = "/api/integra/pos-data"
token = "YOUR_TOKEN_HERE"

params = {
    "FromDt": "2024-01-01",
    "ToDt": "2024-01-31"
}

headers = {
    "Authorization": f"Bearer {token}",
    "Accept": "application/xml"
}

response = requests.get(
    f"{base_url}{endpoint}",
    params=params,
    headers=headers
)

if response.status_code == 200:
    root = ET.fromstring(response.content)

    # Parse transactions
    for transaction in root.findall('.//TransactionDetails'):
        rcpt_num = transaction.find('RCPT_NUM').text
        inv_amt = transaction.find('INV_AMT').text
        print(f"Receipt: {rcpt_num}, Amount: {inv_amt}")
else:
    print(f"Error: {response.status_code}")

Example 4: Save to File

import requests
import json
from datetime import datetime

base_url = "https://your-odoo-domain.com"
endpoint = "/api/integra/pos-data"
token = "YOUR_TOKEN_HERE"

params = {
    "FromDt": "2024-01-01",
    "ToDt": "2024-01-31"
}

headers = {
    "Authorization": f"Bearer {token}",
    "Accept": "application/json"
}

response = requests.get(
    f"{base_url}{endpoint}",
    params=params,
    headers=headers
)

if response.status_code == 200:
    data = response.json()

    # Save to file
    filename = f"pos_data_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
    with open(filename, 'w') as f:
        json.dump(data, f, indent=2)

    print(f"Data saved to {filename}")
else:
    print(f"Error: {response.status_code}")

Postman Usage

Setup Postman Collection

1. Create New Request
   - Method: GET
   - URL: {{base_url}}/api/integra/pos-data

2. Configure Authorization
   - For Bearer Token:

   • Type: Bearer Token
   • Token: Your token value

• For Basic Auth:
  • Type: Basic Auth
  • Username: Your username
  • Password: Your password

3. Add Parameters
   - Key: FromDt, Value: 2024-01-01
   - Key: ToDt, Value: 2024-01-31
   - Key: LOCATION_CODE, Value: 2 (optional)

4. Set Headers
   - Key: Accept, Value: application/json or application/xml

5. Save and Send

Postman Environment Variables

Create environment variables for easier management:

{
  "base_url": "https://your-odoo-domain.com",
  "token": "YOUR_TOKEN_HERE",
  "username": "integra_api_user",
  "password": "YOUR_PASSWORD_HERE"
}

🔒 Multi-layer Security

• HTTPS/SSL Required: All API communications must use HTTPS encryption
• Token-based Authentication: Secure Bearer token authentication
• Basic Authentication Support: Username/password authentication option
• Credential Encryption: Passwords stored using MD5 hashing
• System Parameter Storage: Secure storage of credentials in Odoo system parameters

🛡️ Access Control

• POS-level Control: Enable/disable API per POS configuration
• IP-based Access Ready: Framework ready for IP whitelist implementation
• Request Logging: Comprehensive error logging and request tracking
• Date Range Validation: Server-side validation of date parameters

✅ Best Practices

1. Always use HTTPS in production
2. Rotate tokens periodically
3. Use strong passwords for basic authentication
4. Monitor API access logs regularly
5. Enable API only for necessary POS locations
6. Keep Odoo and module updated

• Query Optimization: Uses optimized ORM queries for large datasets
• Date Range Limit: Recommended to query data in monthly chunks
• Caching: Response caching not implemented (real-time data)
• Concurrent Requests: Supports multiple simultaneous API calls