invoice_az/TIRE_DISPOSAL_IMPLEMENTATION.md

# Tire Products For Disposal Act - Implementation Summary

**Date:** 2026-01-29
**Status:** ✅ Completed

## Overview

Successfully implemented support for "Tire Products For Disposal Act" in Purchase Invoice e-taxes integration. This follows the same pattern as "Metal Scrap Reception Act" with identical workflow and validation.

## What Was Implemented

### 1. Custom Fields (jey_erp app)
**File:** `/apps/jey_erp/jey_erp/custom_fields.py`

- Added "Tire Products For Disposal Act" to `act_kind` dropdown field options
- Updated from 2 options to 3 options:
  - Agricultural Products Act
  - Metal Scrap Reception Act
  - **Tire Products For Disposal Act** (NEW)

### 2. Backend API (invoice_az app)
**File:** `/apps/invoice_az/invoice_az/send_purchase_api.py`

#### New Function Added:
- `generate_tire_disposal_serial_number(token)` - Generates serial numbers from tire disposal endpoint
  - Endpoint: `/api/po/invoice/public/v1/act/generateSerialNumber/tireProductsForDisposalAct`
  - Returns: `{"success": True, "serial_number": "TP25012912345"}`
  - Error handling: 401, 500, 404 responses

#### Modified Functions:
1. **`validate_invoice_for_sending()`**
   - Added "Tire Products For Disposal Act" to valid_act_kinds list
   - Added tax-free validation for tire products (same as metal scrap)
   - Tax-free items not allowed - all items must be "Taxable"

2. **`send_purchase_invoice_to_etaxes()`**
   - Added tire products to serial number routing logic
   - Routes to `generate_tire_disposal_serial_number()` when act_kind is "Tire Products For Disposal Act"

3. **`build_act_payload()`**
   - Added kind selection for tire products
   - Sets `kind: "tireProductsForDisposalAct"` when act_kind is "Tire Products For Disposal Act"

### 3. Frontend UI (invoice_az app)
**File:** `/apps/invoice_az/invoice_az/client/purchase_invoice.js`

- Updated button text logic in `add_purchase_act_buttons()`
- Added "Send Tire Disposal Act to E-Taxes" button text for tire products

### 4. Documentation (invoice_az app)
**File:** `/apps/invoice_az/CLAUDE.md`

- Added tire disposal endpoint to Constants and URLs section
- Added tire products to "Workflow: Sending Purchase Acts to E-Taxes" section
- Documented tax validation rules (only Taxable, no Tax Free)

## Technical Details

### API Integration
**Endpoint:** `https://new.e-taxes.gov.az/api/po/invoice/public/v1/act/generateSerialNumber/tireProductsForDisposalAct`
- Method: GET
- Headers: `x-authorization: Bearer {token}`
- Response: `{"serialNumber": "TP25012912345****"}`

**Kind Value:** `"tireProductsForDisposalAct"`
- Used in act creation payload
- Same create/sign endpoints as other act types

### Tax Validation Rules
**Same as Metal Scrap:**
- Only "Taxable" (5% tax) allowed
- "Tax Free" (0% tax) NOT allowed
- Validation error if any item has tax_type = "Tax Free"

### Workflow
1. User creates Purchase Invoice with Individual supplier
2. Checks `purchase_type` checkbox
3. Selects `act_kind` = "Tire Products For Disposal Act"
4. Adds items with product_group_code
5. Sets all items to tax_type = "Taxable"
6. Submits document
7. Clicks "Send Tire Disposal Act to E-Taxes"
8. System generates serial number from tire disposal endpoint
9. Creates draft act on E-Taxes
10. User clicks "Sign Act with ASAN Imza"
11. System signs with ASAN Imza
12. E-Taxes Purchase Outbox record updated with status "Sent and Signed"

## Files Modified

### jey_erp app
- `jey_erp/custom_fields.py` - Added new option to act_kind dropdown

### invoice_az app
- `invoice_az/send_purchase_api.py` - Added tire disposal serial generation, validation, routing, kind selection
- `invoice_az/client/purchase_invoice.js` - Added button text for tire disposal
- `CLAUDE.md` - Updated documentation

## Deployment Steps Completed

1. ✅ Updated custom fields in jey_erp app
2. ✅ Applied custom fields using `bench --site site1 execute jey_erp.custom_fields.create_custom_fields`
3. ✅ Built JavaScript assets using `bench build --app invoice_az`
4. ✅ Cleared cache using `bench --site site1 clear-cache`

## Testing Instructions

### Test Case 1: Complete Workflow
1. Create Purchase Invoice
2. Select Individual supplier (with FIN, passport, DOB, names)
3. Check `purchase_type` checkbox
4. Select `act_kind` = "Tire Products For Disposal Act"
5. Add items with product_group_code
6. Set all items to tax_type = "Taxable"
7. Submit document
8. Click "Send Tire Disposal Act to E-Taxes"
9. Verify draft created with serial number
10. Click "Sign Act with ASAN Imza"
11. Verify act signed successfully
12. Check E-Taxes Purchase Outbox record created

### Test Case 2: Tax-Free Validation (Should Fail)
1. Create Purchase Invoice with tire disposal act
2. Add item with tax_type = "Tax Free"
3. Try to send to E-Taxes
4. **Expected:** Error message "Tire disposal items cannot be tax-free. Please change Tax Type to 'Taxable' for items: [item_code]"

### Test Case 3: All Act Types Still Work
1. Test Agricultural Products Act - Should work with both Tax Free and Taxable
2. Test Metal Scrap Reception Act - Should work with only Taxable
3. Test Tire Products For Disposal Act - Should work with only Taxable

## Code Review Checklist

- ✅ New serial number function follows existing pattern (metal scrap)
- ✅ Error handling implemented (401, 500, 404)
- ✅ Tax validation added for tire products (no tax-free items)
- ✅ Serial number routing logic updated
- ✅ Payload kind selection updated
- ✅ Button text logic updated
- ✅ Documentation updated
- ✅ Custom fields applied
- ✅ JavaScript assets built
- ✅ Cache cleared

## Summary of Changes

**Total Lines Changed:** ~100 lines across 3 main files

| File | Lines Added | Type | Description |
|------|-------------|------|-------------|
| custom_fields.py | 2 | Modified | Added tire products option |
| send_purchase_api.py | ~75 | Add/Modify | Serial function, validation, routing, kind |
| purchase_invoice.js | 3 | Modified | Button text logic |
| CLAUDE.md | ~20 | Add | Documentation updates |

## Notes

- Implementation follows exact same pattern as Metal Scrap Reception Act
- Only differences: display name, API endpoint, kind value
- Same tax validation rules (only Taxable, no Tax Free)
- No new fields or special logic required
- Fully backward compatible with existing act types

## Result

✅ **Implementation Complete**

Users can now:
- Select "Tire Products For Disposal Act" from act_kind dropdown
- Send tire disposal acts to E-Taxes
- See dynamic button text ("Send Tire Disposal Act to E-Taxes")
- Receive proper validation for tax-free items
- Sign acts with ASAN Imza
- Track acts in E-Taxes Purchase Outbox

The feature is production-ready and follows all established patterns for consistency and maintainability.