Receeco POS Agent

A lightweight middleware service that integrates with Point-of-Sale systems to generate instant digital receipts.

Features

• Real-time Integration: Captures transaction data instantly from POS terminals
• QR Code Generation: Creates unique QR codes for each transaction
• Offline Support: Queues transactions when backend is unavailable
• Short Code Generation: 6-digit codes for manual entry
• Zero Downtime: Maintains existing paper receipt workflows

Quick Start

1. Installation

npm install -g @receeco/pos-agent

2. Initialize Configuration

receeco-pos init --merchant-id=YOUR_MERCHANT_ID --api-key=YOUR_API_KEY

3. Start the Service

receeco-pos start

4. Test Integration

# Quick CLI test (built-in command)
receeco-pos test

# Visual browser-based testing
receeco-pos emulator

API Endpoints

POST /transactions

Process a new transaction and generate digital receipt.

Request Body:

{
  "merchantId": "merchant_123",
  "merchantName": "Test Store",
  "items": [
    {
      "name": "Rice (5kg)",
      "quantity": 1,
      "unitPrice": 85.0,
      "totalPrice": 85.0
    }
  ],
  "totalAmount": 85.0,
  "currency": "NGN",
  "paymentMethod": "card",
  "timestamp": "2024-01-15T14:30:00Z"
}

Response:

{
  "receiptId": "rcpt_abc123",
  "receiptUrl": "https://receeco.com/receipt/rcpt_abc123",
  "qrCodeUrl": "data:image/png;base64...",
  "qrCodeSvg": "<svg>...</svg>",
  "shortCode": "ABC123",
  "deepLinkUrl": "https://receeco.com/receipt/rcpt_abc123",
  "status": "success",
  "timestamp": "2024-01-15T14:30:00Z"
}

GET /health

Check service health status.

GET /queue/status

Check offline queue status.

Configuration

Create a .env file with your configuration:

MERCHANT_ID=your_merchant_id
RECEECO_API_KEY=your_api_key
RECEECO_API_URL=https://receeco.com/api
RECEECO_WEB_URL=https://receeco.com
PORT=3001
LOG_LEVEL=info

NODE_ENV=production

POS Integration Examples

Quickteller POS

Configure your POS to send transaction data to:

POST http://localhost:3001/transactions

Phoenix POS

Use webhook integration:

// In your POS system
fetch("http://localhost:3001/transactions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(transactionData),
});

CLI Commands

Basic Commands

• receeco-pos init - Initialize configuration
• receeco-pos start - Start the service
• receeco-pos status - Check service status
• receeco-pos test - Test with sample transaction
• receeco-pos emulator - Open visual browser-based testing tool
• receeco-pos clear-queue - Clear failed transactions from queue

Windows Service Management

• receeco-pos install-service - Install as Windows service
• receeco-pos start-service - Start Windows service
• receeco-pos stop-service - Stop Windows service
• receeco-pos uninstall-service - Remove Windows service

Support

For integration support, contact the Receeco team or visit our documentation at https://docs.receeco.com