# Tax API

## Get Tax Rates

Retrieve tax rates configured for an organization.

**Endpoint:** `POST https://api.quick.myquickapp.com/accounting/submit-taxes/`

### Request Headers

```
Authorization: Bearer {api_key}
Content-Type: application/json
language: en
```

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Headers": "*",
    "Access-Control-Allow-Methods": "GET,POST,OPTIONS"
  },
  "body": {
    "taxes": [
      {
        "id": "tax_1",
        "name": "VAT 15%",
        "code": "VAT15",
        "rate": 15.0,
        "type": "sales",
        "is_active": true,
        "default": true,
        "account_id": "tax_payable_1",
        "description": "Standard VAT rate"
      },
      {
        "id": "tax_2",
        "name": "VAT 0%",
        "code": "VAT0",
        "rate": 0.0,
        "type": "sales",
        "is_active": true,
        "default": false,
        "account_id": "tax_payable_1",
        "description": "Zero-rated VAT"
      },
      {
        "id": "tax_3",
        "name": "Input VAT",
        "code": "INPUT_VAT",
        "rate": 15.0,
        "type": "purchase",
        "is_active": true,
        "default": true,
        "account_id": "tax_receivable_1",
        "description": "Input VAT for purchases"
      }
    ]
  }
}
```

---

## Create Tax Rate

Create a new tax rate.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "create",
  "name": "VAT 15%",
  "code": "VAT15",
  "rate": 15.0,
  "type": "sales",
  "account_id": "tax_payable_1",
  "description": "Standard VAT rate"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Tax rate created successfully",
    "tax": {
      "id": "tax_4",
      "name": "VAT 15%",
      "code": "VAT15",
      "rate": 15.0,
      "type": "sales",
      "is_active": true,
      "default": false,
      "account_id": "tax_payable_1",
      "description": "Standard VAT rate"
    }
  }
}
```

---

## Edit Tax Rate

Update an existing tax rate.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "edit",
  "tax_id": "tax_4",
  "name": "VAT 15% (Exclusive)",
  "code": "VAT15_EXC",
  "rate": 15.0,
  "type": "sales",
  "account_id": "tax_payable_1",
  "description": "VAT 15% exclusive"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Tax rate updated successfully",
    "tax": {
      "id": "tax_4",
      "name": "VAT 15% (Exclusive)",
      "code": "VAT15_EXC",
      "rate": 15.0,
      "type": "sales",
      "description": "VAT 15% exclusive"
    }
  }
}
```

---

## Delete Tax Rate

Delete or deactivate a tax rate.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "delete",
  "tax_id": "tax_4",
  "deactivate": true
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Tax rate deactivated successfully"
  }
}
```

---

## Calculate Tax

Calculate tax on a given amount.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "calculate_tax",
  "amount": 1000.00,
  "tax_id": "tax_1",
  "tax_included": false
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "amount": 1000.00,
    "tax_rate": 15.0,
    "tax_amount": 150.00,
    "total": 1150.00,
    "tax_included": false
  }
}
```

### Request Body - Tax Included

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "calculate_tax",
  "amount": 1150.00,
  "tax_id": "tax_1",
  "tax_included": true
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "amount": 1000.00,
    "tax_rate": 15.0,
    "tax_amount": 150.00,
    "total": 1150.00,
    "tax_included": true
  }
}
```

---

## Tax Report

Get tax report for a date range.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "tax_report",
  "date_from": "2024-03-01",
  "date_to": "2024-03-31",
  "tax_type": "sales",
  "group_by": "tax_rate"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "report_period": {
      "start": "2024-03-01",
      "end": "2024-03-31"
    },
    "tax_type": "sales",
    "summary": {
      "total_sales": 50000.00,
      "total_tax": 7500.00,
      "total_inclusive": 57500.00
    },
    "by_tax_rate": [
      {
        "tax_id": "tax_1",
        "tax_name": "VAT 15%",
        "rate": 15.0,
        "taxable_amount": 50000.00,
        "tax_amount": 7500.00
      },
      {
        "tax_id": "tax_2",
        "tax_name": "VAT 0%",
        "rate": 0.0,
        "taxable_amount": 0,
        "tax_amount": 0
      }
    ],
    "by_invoice": [
      {
        "invoice_id": 50001,
        "invoice_number": "INV-2024-0001",
        "customer": "Customer Name",
        "date": "2024-03-10",
        "subtotal": 1000.00,
        "tax_amount": 150.00,
        "total": 1150.00
      }
    ]
  }
}
```

---

## VAT Return

Get VAT return summary.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "vat_return",
  "date_from": "2024-01-01",
  "date_to": "2024-03-31",
  "vat_period": "Q1-2024"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "vat_period": "Q1-2024",
    "period": {
      "start": "2024-01-01",
      "end": "2024-03-31"
    },
    "output_tax": {
      "total_sales": 150000.00,
      "taxable_amount": 150000.00,
      "tax_amount": 22500.00
    },
    "input_tax": {
      "total_purchases": 50000.00,
      "taxable_amount": 50000.00,
      "tax_amount": 7500.00
    },
    "vat_payable": {
      "output_tax": 22500.00,
      "input_tax": 7500.00,
      "net_vat": 15000.00,
      "due_date": "2024-04-25",
      "status": "pending"
    }
  }
}
```

---

## Tax Transactions

Get tax transactions for a period.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "tax_transactions",
  "date_from": "2024-03-01",
  "date_to": "2024-03-31",
  "tax_id": "tax_1"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "tax_id": "tax_1",
    "tax_name": "VAT 15%",
    "date_from": "2024-03-01",
    "date_to": "2024-03-31",
    "transactions": [
      {
        "id": 50001,
        "type": "invoice",
        "document_number": "INV-2024-0001",
        "date": "2024-03-10",
        "customer": "Customer Name",
        "taxable_amount": 1000.00,
        "tax_amount": 150.00,
        "total": 1150.00
      },
      {
        "id": 50002,
        "type": "credit_note",
        "document_number": "CRN-2024-0001",
        "date": "2024-03-15",
        "customer": "Customer Name",
        "taxable_amount": -200.00,
        "tax_amount": -30.00,
        "total": -230.00
      }
    ],
    "summary": {
      "total_taxable_amount": 800.00,
      "total_tax_amount": 120.00,
      "transaction_count": 2
    }
  }
}
```

---

## Tax Types

| Type | Description |
|------|-------------|
| `sales` | Sales tax/VAT (output tax) |
| `purchase` | Purchase tax/VAT (input tax) |
| `withholding` | Withholding tax |
| `excise` | Excise duty |
| `customs` | Customs duty |

---

## Tax Calculation Examples

### Example 1: Calculate tax on R1000 (exclusive)

```json
{
  "amount": 1000.00,
  "rate": 15.0,
  "tax_included": false
}
// Result: Tax = R150, Total = R1150
```

### Example 2: Calculate tax on R1150 (inclusive)

```json
{
  "amount": 1150.00,
  "rate": 15.0,
  "tax_included": true
}
// Result: Tax = R150, Base = R1000
```

### Example 3: Multiple tax rates

```json
{
  "items": [
    {
      "amount": 1000.00,
      "tax_id": "tax_1",
      "rate": 15.0
    },
    {
      "amount": 500.00,
      "tax_id": "tax_2",
      "rate": 0.0
    }
  ]
}
// Result: Total tax = R150
```