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)