> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/developers/api-guides/projects-and-documents.md).

# Projects and documents

Find projects, read and add their lines, read their documents, create Tax Invoices, and send ERP numbers back from your accounting system, with the OrderEazi API.

Your system may need to find an order in OrderEazi, read what's on it, add to it, or record the numbers your accounting system gave its documents. Every order in OrderEazi is a project, with its lines and documents, such as the Quote, the Sales Order (the document that confirms an order to the client), and the Tax Invoice.

### Before you start

You'll need **Read** on **For Project** to read, and **Write** to change projects and create documents. See [Authentication](/central/developers/authentication.md). In these endpoints, `{pro}` is the project number, such as `PRO001234`.

### How to find a project

`POST /api/project/search/{term}` finds projects whose client order number or reference contains the term, and returns their project numbers. The term needs at least 3 characters.

`POST /api/project/search/keyvalue` finds projects by their key values (custom fields):

```json
{ "Search": [ { "Key": "WebStoreId", "Value": "10045" } ], "Type": 0 }
```

A `Type` of `0` matches the value exactly, ignoring capitals. Any other `Type` matches part of the value.

When nothing matches, both return a `400`. To check a project exists, use `GET /api/project/{pro}/exists`. To read its status, use `GET /api/project/{pro}/projectstatus`.

### How to read, add, and delete lines

* **Read:** `GET /api/project/{pro}/lines` returns each line, with its `ProjectLineId`, `Code`, `Quantity`, and prices. It also shows how much is on each document, such as `QtyOnSo` (on the Sales Order) and `QtyOnInv` (on Tax Invoices).
* **Add:** `POST /api/project/{pro}/lines` adds one line:

  ```json
  { "Code": "CHAIR-01", "Quantity": 10, "SellingPrice": 1450.00, "CostPrice": 850.00 }
  ```
* **Delete:** `DELETE /api/project/{pro}/lines/{projectLineId}` deletes a line.

### How to add information to a project

* **Key values:** `POST /api/project/{pro}/projectkeyvalue` adds or updates custom fields, such as `{ "KeyValues": [ { "Key": "Region", "Value": "West" } ] }`. Send `""` to clear a value.
* **Tags:** `POST /api/project/{pro}/tag` adds tags, such as `[ { "TagName": "VIP" } ]`, and `DELETE /api/project/{pro}/tag` removes them. Both need **Read** and **Write** on **For Project**.
* **Notes:** `POST /api/project/{pro}/note` adds a note, such as `{ "Note": "Client called about delivery" }`.
* **Attachments:** `POST /api/project/{pro}/attachment` uploads files, as base64 in `FileBytes`.
* **Client order reference:** `PATCH /api/project/{pro}/customerorderreference?reference=PO-5521` adds a reference.
* **Expected delivery date:** `POST /api/project/updateExpectedDeliveryDate` sets it, with the `ProjectNumber` and `DeliveryDate`.

### How to read documents

* **A project's documents:** `GET /api/project/{pro}/documents`.
* **A client's documents of one type:** `GET /api/client/{clientId}/documents/{type}`, such as `TaxInvoice`.
* **Documents related to one:** `GET /api/project/documents/related/{documentNumber}`.

Each document has its `DocumentNumber`, `DocumentType`, dates, client, and products. Its `DocumentUrl` opens the PDF for someone signed in to OrderEazi in a browser. It doesn't work with an API key.

### How to create a Tax Invoice

Create a Tax Invoice from a project's Sales Order with `POST /api/project/{pro}/document`:

```json
{
  "DocumentType": "TaxInvoice",
  "CustomerName": "Clientco (Pty) Ltd",
  "WarehouseName": "Johannesburg Warehouse",
  "DocumentNumber": "IN100234",
  "DocumentId": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f",
  "Lines": [ { "Code": "CHAIR-01", "Quantity": 10, "SellingPrice": 1450.00 } ]
}
```

* **`CustomerName`:** This must be the project's client.
* **Sales Order first:** The project must have a Sales Order. You can't invoice more than is on it, or more than is left to invoice.
* **`WarehouseName`:** This is required on the Enterprise licence.
* **`DocumentNumber` and `DocumentId`:** These are optional. Send your accounting system's invoice number and ID to link the two.

The response has the new Tax Invoice's `DocumentNumber`. To create a Purchase Order the same way, see [Purchase Orders](/central/developers/api-guides/purchase-orders.md).

### How to send ERP numbers back

When your accounting system creates its own copy of an OrderEazi document, send back the number and ID it gave it. These are the document's ERP number and ERP ID, and they link the two copies:

```bash
curl -X PATCH "https://yourcompany.ordereazi.com/api/PRO001234/document/INV000812?erpnumber=IN100234&erpid=9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "X-OrderEazi-Key: YOUR_API_KEY" \
  -H "x-api-version: 2.0"
```

* **The path:** It's `/api/{pro}/document/{documentNumber}`, with no `project/`.
* **`documentNumber`:** This is OrderEazi's number for the document, such as `INV000812`.
* **`erpnumber` and `erpid`:** Both are required.

The numbers replace any that were there, and OrderEazi sends a webhook to say the document was synced. See [Webhooks](/central/developers/webhooks.md).

### How to move a project on

`GET /api/project/{pro}/advanceworkflow/{workflowAction}` moves a project on to its next step. `{workflowAction}` says which step, such as `8` (delivered) or `11` (proof of delivery received).

> **Warning:** Although it's a GET, it changes the project, so only call it when you mean to.

### Related pages

* [Receiving orders from a sales channel](/central/developers/api-guides/receiving-orders-from-a-sales-channel.md): create projects from orders
* [Purchase Orders](/central/developers/api-guides/purchase-orders.md): create and receive Purchase Orders