# Invoice API

## Create Invoice

Create a new invoice.

**Endpoint:** `POST https://api.quick.myquickapp.com/invoicing/invoice/new`

### Request Headers

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

### Request Body - Sales Invoice (Outgoing)

```json
{
  "org_id": "12345",
  "userid": "123",
  "invoicetype": "invoiceout",
  "partner": "917013",
  "invoicenumber": "INV-2024-0001",
  "invoicedatetime": "2024-03-10T10:00:00",
  "invoicestatus": "draft",
  "comments": "Invoice for services rendered",
  "invoicereference": "PO-12345",
  "invoiceterms": "Net 30 days",
  "invoicedue": "2024-04-09",
  "subtotal": 1000.00,
  "tax_amount": 150.00,
  "invoicetotal": 1150.00,
  "sourceid": "",
  "sourcenumber": "",
  "sourcetype": "",
  "chartofaccounts": "sales_101",
  "invoicejournal": "journal_1",
  "tradeaccount": "receivable_101",
  "line_items": [
    {
      "product_id": 201,
      "product_name": "Product Name",
      "description": "Product description",
      "quantity": 10,
      "price": 100.00,
      "discount": 0,
      "tax_rate": 15.0,
      "tax_included": true,
      "subtotal": 1000.00,
      "tax_amount": 150.00,
      "total": 1150.00
    }
  ],
  "recurring": {
    "enabled": false,
    "frequency": "monthly",
    "start_date": "2024-04-01",
    "next_run_date": "2024-04-01",
    "occurrences_count": 0
  }
}
```

### Response - Success (200)

```json
{
  "statusCode": 200,
  "headers": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Headers": "*",
    "Access-Control-Allow-Methods": "GET,POST,OPTIONS"
  },
  "body": {
    "message": "Invoice created successfully",
    "invoice": {
      "id": 50001,
      "orgid": 12345,
      "partner": "917013",
      "invoicenumber": "INV-2024-0001",
      "invoicetype": "invoiceout",
      "userid": 123,
      "invoicestatus": "draft",
      "comments": "Invoice for services rendered",
      "invoicereference": "PO-12345",
      "invoiceterms": "Net 30 days",
      "invoicedue": "2024-04-09",
      "subtotal": 1000.00,
      "tax_amount": 150.00,
      "invoicetotal": 1150.00,
      "chartofaccounts": "sales_101",
      "invoicejournal": "journal_1",
      "tradeaccount": "receivable_101",
      "created_at": "2024-03-10T10:30:00"
    }
  }
}
```

### Response - Error (400)

```json
{
  "statusCode": 400,
  "headers": {...},
  "body": {
    "message": "Invalid recurring configuration: frequency is required"
  }
}
```

---

## Get Invoices

Retrieve invoices with filtering and pagination.

**Endpoint:** `POST https://api.quick.myquickapp.com/invoicing/listinvoices/`

### Request Headers

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

### Request Body - Simple List

```json
{
  "org_id": "12345",
  "include_items": false
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "",
    "invoices": [
      {
        "id": 50001,
        "orgid": 12345,
        "invoicenumber": "INV-2024-0001",
        "invoicetype": "invoiceout",
        "invoicestatus": "draft",
        "partner": {
          "id": 917013,
          "partnername": "Customer Name",
          "display_name": "Customer Name",
          "imageUrl": "https://s3-url-here.com/image.jpg"
        },
        "invoicedatetime": "2024-03-10T10:00:00",
        "invoicetotal": 1150.00,
        "due_amount": 1150.00,
        "creator": "John Doe",
        "recurring": {
          "enabled": false
        }
      }
    ],
    "pagination": {
      "page_number": 1,
      "page_size": 25,
      "total_items": 1,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  }
}
```

### Request Body - With Filters

```json
{
  "org_id": "12345",
  "partner_ids": ["917013", "917014"],
  "status_filter": "draft",
  "date_from": "2024-03-01",
  "date_to": "2024-03-31",
  "amount_min": 100,
  "amount_max": 5000,
  "sort_by": "number",
  "sort_order": "desc",
  "page_size": 25,
  "page_number": 1
}
```

### Request Body - Search

```json
{
  "org_id": "12345",
  "search_key": "INV-2024",
  "page_size": 25,
  "page_number": 1
}
```

---

## Add Invoice Line

Add a line item to an existing invoice.

**Endpoint:** `POST https://api.quick.myquickapp.com/invoicing/addline`

### Request Headers

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

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "invoice_id": 50001,
  "product_id": 201,
  "product_name": "Product Name",
  "description": "Product description",
  "quantity": 5,
  "price": 100.00,
  "discount": 10,
  "tax_rate": 15.0,
  "tax_included": true,
  "subtotal": 450.00,
  "tax_amount": 67.50,
  "total": 517.50
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Line item added successfully",
    "line_item": {
      "id": 60001,
      "invoiceid": 50001,
      "product_id": 201,
      "description": "Product description",
      "quantity": 5,
      "price": 100.00,
      "discount": 10,
      "tax_rate": 15.0,
      "subtotal": 450.00,
      "tax_amount": 67.50,
      "total": 517.50
    }
  }
}
```

---

## Cancel Invoice

Cancel an invoice (only draft or proforma status).

**Endpoint:** `POST https://api.quick.myquickapp.com/invoicing/invoice/new`

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "cancel_invoice": true,
  "id": 50001
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Invoice has been cancelled."
  }
}
```

---

## Validate Invoice

Validate and post an invoice (change status from draft to open).

**Endpoint:** `POST https://api.quick.myquickapp.com/invoicing/invoice/new`

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "validate_invoice": true,
  "id": 50001
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Invoice validated and posted",
    "invoice": {
      "id": 50001,
      "invoicestatus": "open",
      "journal_entry_id": 70001
    }
  }
}
```

---

## Get Invoice Balances

Get balance information for an invoice (amount due, payments, etc.).

**Endpoint:** `POST https://api.quick.myquickapp.com/invoicing/getinvoice`

### Request Body

```json
{
  "org_id": "12345",
  "id": 50001,
  "include_items": true
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "invoices": [
      {
        "id": 50001,
        "invoicenumber": "INV-2024-0001",
        "invoicetotal": 1150.00,
        "amount_paid": 350.00,
        "due_amount": 800.00,
        "journals": [
          {
            "id": 70001,
            "journalname": "INV-2024-0001",
            "journaldate": "2024-03-10",
            "amount": 1150.00
          }
        ],
        "payjournals": [
          {
            "id": 80001,
            "journalname": "Payment 001",
            "journaldate": "2024-03-15",
            "amount": 350.00
          }
        ]
      }
    ]
  }
}
```

---

## Recurring Invoices

### Create Recurring Invoice

```json
{
  "org_id": "12345",
  "userid": "123",
  "invoicetype": "invoiceout",
  "partner": "917013",
  "invoicenumber": "INV-2024-0002",
  "invoicedatetime": "2024-03-10T10:00:00",
  "invoicestatus": "draft",
  "subtotal": 500.00,
  "tax_amount": 75.00,
  "invoicetotal": 575.00,
  "recurring": {
    "enabled": true,
    "is_parent": true,
    "frequency": "monthly",
    "start_date": "2024-04-01",
    "next_run_date": "2024-04-01",
    "occurrences_count": 0,
    "status": "active"
  }
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Invoice created successfully",
    "invoice": {
      "id": 50002,
      "invoicenumber": "INV-2024-0002",
      "recurring": {
        "enabled": true,
        "is_parent": true,
        "frequency": "monthly",
        "start_date": "2024-04-01",
        "next_run_date": "2024-04-01",
        "occurrences_count": 0,
        "status": "active"
      }
    }
  }
}
```

### Pause Recurring Invoice

```json
{
  "org_id": "12345",
  "userid": "123",
  "pause_recurring": true,
  "id": 50002
}
```

### Resume Recurring Invoice

```json
{
  "org_id": "12345",
  "userid": "123",
  "resume_recurring": true,
  "id": 50002
}
```

### Cancel Recurring Contract

```json
{
  "org_id": "12345",
  "userid": "123",
  "cancel_recurring": true,
  "id": 50002,
  "cancellation_reason": "Customer requested cancellation"
}
```

### Generate Child Invoice Manually

```json
{
  "org_id": "12345",
  "userid": "123",
  "generate_child_invoice": true,
  "id": 50002
}
```

---

## Invoice Types

| Type | Description | Prefix |
|------|-------------|--------|
| `invoiceout` | Sales Invoice (Outgoing) | INV- |
| `creditout` | Credit Note (Outgoing) | CRN- |
| `invoicein` | Purchase Invoice (Incoming) | BILL- |
| `creditin` | Credit Note (Incoming) | RFD- |

---

## Invoice Status

| Status | Description |
|--------|-------------|
| `draft` | Invoice is being created |
| `proforma` | Proforma invoice |
| `open` | Invoice is posted and active |
| `paid` | Invoice is fully paid |
| `cancelled` | Invoice has been cancelled |
| `overdue` | Invoice is past due date |