Create Purchase Receipt Skill

Purpose

Creates a Goods Receipt (GR) record in NexERP when goods are physically received from a supplier. This is triggered by a Delivery Order from the supplier.

When to Use

• Supplier truck arrives with goods
• Driver provides Delivery Order (DO)
• Warehouse receives and inspects goods
• Need to update inventory levels

Database Tables

• tbl_preceipt_txn - Goods receipt header
• tbl_preceipt_item - Line items received
• tbl_preceipt_movement - Inventory movement records

Usage

python create-purchase-receipt/main.py \
  --supplier-name "NINGBO METALWIRE" \
  --receipt-date "2025-10-27" \
  --items '[
    {
      "product_name": "WIRE D1.2-L105.8",
      "quantity": 200,
      "unit_price": 8.50,
      "po_reference": "PO25100055"
    }
  ]' \
  --delivery-order "DO-2024000" \
  --json

Required Fields

| Field | Type | Description | |-------|------|-------------| | supplier_name | string | Supplier name (fuzzy match) | | receipt_date | string | Receipt date (YYYY-MM-DD) | | items | JSON array | Line items received |

Optional Fields

| Field | Type | Description | |-------|------|-------------| | delivery_order | string | Supplier's DO number | | po_reference | string | Related PO number | | remark | string | Any notes |

Item Fields

| Field | Required | Description | |-------|----------|-------------| | product_name | Yes | Product name or SKU | | quantity | Yes | Quantity received | | unit_price | Yes | Price per unit | | discount | No | Discount percentage (0-100) | | remark | No | Item-specific notes |

Output (JSON)

Success

{
  "success": true,
  "gr_number": "GR25100048",
  "txn_id": 2210,
  "supplier": "NINGBO METALWIRE PRODUCTS CO.,LTD",
  "receipt_date": "2025-10-27",
  "items_count": 1,
  "subtotal": 1700.00,
  "grand_total": 1700.00,
  "delivery_order": "DO-2024000"
}

Error

{
  "success": false,
  "error": "Supplier 'XYZ' not found"
}

Document Number Format

• Format: GR{YY}{MM}{NNNN}
• Example: GR25100048 = October 2025, receipt #48

Business Rules

1. Supplier Validation: Must exist in tbl_supplier
2. Product Validation: Must exist in tbl_product_code
3. Inventory Update: Automatically updates stock levels
4. PO Linking: Can link to existing PO for tracking
5. No Tax Calculation: GR records quantities only (tax on invoice)

Example Scenarios

Scenario 1: Full Delivery

# All items from PO received
python create-purchase-receipt/main.py \
  --supplier-name "ACTION BOLT" \
  --receipt-date "2025-10-27" \
  --items '[
    {"product_name": "WIRE D1.2", "quantity": 200, "unit_price": 8.50}
  ]' \
  --po-reference "PO25100055" \
  --json

Scenario 2: Partial Delivery

# Only 150 out of 200 units received
python create-purchase-receipt/main.py \
  --supplier-name "ACTION BOLT" \
  --receipt-date "2025-10-27" \
  --items '[
    {"product_name": "WIRE D1.2", "quantity": 150, "unit_price": 8.50}
  ]' \
  --po-reference "PO25100055" \
  --remark "Partial delivery - 50 units backordered" \
  --json

Scenario 3: Multi-Item Delivery

python create-purchase-receipt/main.py \
  --supplier-name "NINGBO" \
  --receipt-date "2025-10-27" \
  --delivery-order "DO-2024000" \
  --items '[
    {"product_name": "WIRE D1.2-L105.8", "quantity": 100, "unit_price": 8.50},
    {"product_name": "WIRE D0.8-L133.5", "quantity": 200, "unit_price": 7.30}
  ]' \
  --json

Integration with Database Agent

# After Document Agent extracts Delivery Order
extracted_data = {
    "document_type": "delivery_order",
    "issuer": "NINGBO METALWIRE PRODUCTS CO.,LTD",
    "do_number": "DO-2024000",
    "po_reference": "PO25100054",
    "delivery_date": "2025-10-27",
    "line_items": [
        {"description": "WIRE D1.2-L105.8", "qty_delivered": 100, "unit_price": 8.50}
    ]
}

# Call skill via Bash
result = bash_tool.execute(
    f"python skills/purchasing/create-purchase-receipt/main.py "
    f"--supplier-name '{extracted_data['issuer']}' "
    f"--receipt-date '{extracted_data['delivery_date']}' "
    f"--delivery-order '{extracted_data['do_number']}' "
    f"--items '{json.dumps(items)}' "
    "--json"
)

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Supplier not found | Invalid supplier name | Check tbl_supplier | | Product not found | Invalid SKU/name | Check tbl_product_code | | Invalid date | Wrong date format | Use YYYY-MM-DD | | Negative quantity | Invalid input | Quantity must be > 0 |

Testing

# Test with sample delivery order
python create-purchase-receipt/main.py \
  --supplier-name "NINGBO" \
  --receipt-date "2025-10-27" \
  --items '[{"product_name": "WIRE D1.2", "quantity": 50, "unit_price": 8.50}]' \
  --verbose --json

Notes

• GR updates inventory immediately
• Can create GR without PO (direct receipt)
• Multiple GRs can reference same PO (partial deliveries)
• GR is the SOURCE for Purchase Return (if defects found)

---

Database: carrickc (MariaDB) Tables: tbl_preceipt_txn, tbl_preceipt_item, tbl_preceipt_movement Document Format: GR25100048 Inventory Impact: Yes (increases stock)