# User Guide: Agricultural Purchase Invoice Tax Type

## Quick Start

This guide shows you how to use the new **Tax Type** field for agricultural purchase invoices.

---

## When to Use Tax Type

Use the **Tax Type** field when:
- ✅ Creating a Purchase Invoice for agricultural goods
- ✅ Supplier is an Individual (physical person)
- ✅ You checked the **"Agricultural Goods"** checkbox

---

## Step-by-Step Instructions

### Step 1: Create Purchase Invoice

1. Go to **Buying > Purchase Invoice > New**
2. Select a supplier (must be type: **Individual**)
3. Set posting date and other basic details

### Step 2: Enable Agricultural Goods

1. Find the **"Agricultural Goods"** checkbox (usually near the top)
2. **Check this box** ✅

**What happens:**
- The items table will now show two new columns:
  - **Tax Type** (dropdown)
  - **Agricultural Tax Amount (5%)** (read-only)

### Step 3: Add Items

1. Click **"Add Row"** in the items table
2. Select an item
3. Enter quantity and rate
4. **Important:** Select **Tax Type** for each item

### Step 4: Select Tax Type

For each item, choose one of:

| Tax Type | When to Use | Tax Calculation | Old Template Equivalent |
|----------|-------------|-----------------|-------------------------|
| **Tax Free** | Product is exempt from VAT | 0% (no tax) | ƏDV 0%, ƏDV-dən azadolma |
| **Taxable** | Product has 5% agricultural tax | 5% of amount | ƏDV 2% cəlb |

**Example:**
- Item: Wheat (100 kg @ 10 AZN/kg)
- Amount: 1,000 AZN
- Tax Type: **"Taxable"**
- Agricultural Tax Amount: **50 AZN** (automatically calculated)

### Step 5: Watch Auto-Calculation

As you enter or change:
- Quantity
- Rate
- Amount

The **Agricultural Tax Amount** field will automatically update if Tax Type is **"Taxable"**.

**Formula:** `Agricultural Tax Amount = Amount × 5%`

### Step 6: Save and Submit

1. Click **Save**
2. If you forgot to select Tax Type, you'll see an error:
   ```
   Missing Tax Type
   Please select Tax Type for items: [item codes]
   ```
3. Select Tax Type for all items
4. Click **Save** again
5. Click **Submit**

### Step 7: Send to E-Taxes

After submitting:

1. You'll see a button: **"Send Agricultural Act to E-Taxes"**
2. Click it to send to E-Taxes system
3. Follow the ASAN Imza signing process

**Note:** The button only appears if:
- ✅ Document is submitted
- ✅ "Agricultural Goods" is checked
- ✅ Supplier is type "Individual"

---

## Common Scenarios

### Scenario 1: All Items Tax Free

**Example:** Dairy products from a farmer (VAT exempt)

| Item | Qty | Rate | Amount | Tax Type | Tax Amount |
|------|-----|------|--------|----------|------------|
| Milk | 100 L | 2 AZN | 200 AZN | Tax Free | 0.00 AZN |
| Cheese | 10 kg | 15 AZN | 150 AZN | Tax Free | 0.00 AZN |
| **Total** | | | **350 AZN** | | **0.00 AZN** |

### Scenario 2: All Items Taxable

**Example:** Grain products (subject to 5% tax)

| Item | Qty | Rate | Amount | Tax Type | Tax Amount |
|------|-----|------|--------|----------|------------|
| Wheat | 1000 kg | 1 AZN | 1,000 AZN | Taxable | 50.00 AZN |
| Barley | 500 kg | 0.8 AZN | 400 AZN | Taxable | 20.00 AZN |
| **Total** | | | **1,400 AZN** | | **70.00 AZN** |

### Scenario 3: Mixed Items

**Example:** Mixed agricultural products

| Item | Qty | Rate | Amount | Tax Type | Tax Amount |
|------|-----|------|--------|----------|------------|
| Tomatoes | 200 kg | 3 AZN | 600 AZN | Tax Free | 0.00 AZN |
| Wheat | 500 kg | 1 AZN | 500 AZN | Taxable | 25.00 AZN |
| Eggs | 1000 pcs | 0.5 AZN | 500 AZN | Tax Free | 0.00 AZN |
| **Total** | | | **1,600 AZN** | | **25.00 AZN** |

---

## Validation Rules

The system will prevent you from saving if:

1. **Missing Tax Type** (when Agricultural Goods is checked)
   - Error: "Please select Tax Type for items: [list]"
   - Fix: Select "Tax Free" or "Taxable" for each item

2. **Agricultural Goods not checked** (but supplier is Individual)
   - No error, but buttons won't appear
   - Fix: Check "Agricultural Goods" checkbox

3. **Supplier not Individual** (but Agricultural Goods is checked)
   - No error, but buttons won't appear
   - Fix: Change supplier or uncheck "Agricultural Goods"

---

## Field Behavior

### Tax Type Field
- **Visibility:** Only when "Agricultural Goods" is checked
- **Required:** Yes (mandatory when visible)
- **Options:** (empty), Tax Free, Taxable
- **Default:** Empty (must select)
- **Location:** Items table, after Item Tax Template

### Agricultural Tax Amount Field
- **Visibility:** Only when "Agricultural Goods" is checked
- **Editable:** No (read-only, auto-calculated)
- **Formula:**
  - If Tax Type = "Taxable": `Amount × 5%`
  - If Tax Type = "Tax Free": `0`
  - If Tax Type = empty: `0`
- **Updates:** Automatically when qty/rate/amount/tax_type changes

---

## Button Visibility Logic

The **"Send Agricultural Act to E-Taxes"** button appears when:

| Condition | Status |
|-----------|--------|
| Document submitted | ✅ Required |
| Agricultural Goods checked | ✅ Required |
| Supplier type = Individual | ✅ Required |
| Tax Type selected for all items | ✅ Required (validation) |

If ANY condition is not met, the button won't appear.

---

## Troubleshooting

### Problem: Tax Type field not visible

**Possible causes:**
1. "Agricultural Goods" checkbox is not checked
2. Browser cache is old

**Solutions:**
1. Check the "Agricultural Goods" checkbox
2. Refresh the page (Ctrl+F5)
3. Clear browser cache

### Problem: Agricultural Tax Amount not calculating

**Possible causes:**
1. Tax Type is not set to "Taxable"
2. Amount is 0 or empty
3. JavaScript error

**Solutions:**
1. Ensure Tax Type = "Taxable"
2. Enter a valid quantity and rate
3. Check browser console for errors
4. Refresh the page

### Problem: Button not visible after submission

**Possible causes:**
1. "Agricultural Goods" is not checked
2. Supplier is not type "Individual"
3. Document is cancelled

**Solutions:**
1. Check "Agricultural Goods" checkbox (before submission)
2. Verify supplier type in Supplier master
3. Ensure document status is "Submitted" (not "Cancelled")

### Problem: Validation error "Missing Tax Type"

**Cause:** One or more items don't have Tax Type selected

**Solution:**
1. Look at the error message - it lists the item codes
2. Find those items in the table
3. Select "Tax Free" or "Taxable" for each
4. Save again

---

## Tips and Best Practices

### Tip 1: Set Tax Type While Adding Items
Don't wait until the end - set Tax Type as you add each item.

### Tip 2: Default to Tax Free
If unsure, start with "Tax Free" - you can change it later.

### Tip 3: Check Tax Amount
Always verify the "Agricultural Tax Amount" looks correct before submitting.

### Tip 4: Use Item Master Product Code
Ensure each item has a **Product Group Code** set (required for E-Taxes).

### Tip 5: Save Frequently
Save your work often - you can edit before submission.

---

## Keyboard Shortcuts

| Action | Shortcut |
|--------|----------|
| Save document | Ctrl + S |
| Add new row | Ctrl + N (when in table) |
| Refresh page | Ctrl + F5 |
| Submit document | Ctrl + Shift + S |

---

## Frequently Asked Questions

### Q: What's the difference between Tax Free and Taxable?

**A:**
- **Tax Free:** Product is exempt from VAT (0% tax)
- **Taxable:** Product has 5% agricultural tax

### Q: Can I change Tax Type after submission?

**A:** No, you must cancel and amend the document to change Tax Type.

### Q: What if I selected the wrong Tax Type?

**A:**
1. If not submitted: Just change it and save
2. If submitted: Cancel the document, amend it, fix Tax Type, resubmit

### Q: Do I need to fill Item Tax Template too?

**A:** No, the new **Tax Type** field replaces Item Tax Template for agricultural goods. However, the old field is still there for compatibility.

### Q: What happens to old invoices?

**A:** Old invoices with Item Tax Template will continue to work. You may need to add Tax Type before sending new acts. See `MIGRATION_GUIDE.md` for details.

### Q: Why is the button not appearing?

**A:** Check all conditions:
1. ✅ Document submitted
2. ✅ Agricultural Goods checked
3. ✅ Supplier type = Individual

All three must be true.

### Q: Can I use this for Company suppliers?

**A:** No, this feature is only for Individual suppliers (physical persons). Company suppliers use regular purchase invoices.

---

## Additional Resources

- **Implementation Details:** `IMPLEMENTATION_SUMMARY.md`
- **Migration Guide:** `MIGRATION_GUIDE.md`
- **Developer Guide:** `CLAUDE.md`

---

## Support

If you have questions:
1. Check this guide first
2. Review error messages carefully
3. Check the validation rules section
4. Contact your system administrator

---

## Quick Reference Card

```
┌─────────────────────────────────────────────────────┐
│  AGRICULTURAL PURCHASE INVOICE - TAX TYPE           │
├─────────────────────────────────────────────────────┤
│                                                     │
│  1. Check "Agricultural Goods" ✅                   │
│                                                     │
│  2. Add items and select Tax Type:                 │
│     • Tax Free = 0% (no tax)                       │
│     • Taxable = 5% (auto-calculated)               │
│                                                     │
│  3. Tax Amount = Amount × 5% (if Taxable)          │
│                                                     │
│  4. Submit → Send to E-Taxes                       │
│                                                     │
│  Requirements:                                      │
│  ✅ Document submitted                             │
│  ✅ Agricultural Goods checked                     │
│  ✅ Supplier type = Individual                     │
│  ✅ Tax Type selected for ALL items                │
│                                                     │
└─────────────────────────────────────────────────────┘
```

---

**Last Updated:** 2026-01-28
**Version:** 1.0
