POST
Documents.Update
עדכון מסמך עסקי קיים באותו מזהה ומספר: פריטים, סכום, שדות הזמנה, פרטי לקוח מודפסים והערות. שלחו רק שדות שהשתנו; יתר הנתונים נשמרים. Updates IN PLACE and creates no new business document.
Permissions
- On a company subdomain (e.g. https://{user_domain}.bull36.com) the user must match that Host — Login and protected APIs reject another company with success=0, error user_not_in_company. On a main brand host (bull36.com, biz1.co.il, mastrocrm.com, …) the company domain gate is skipped.
- A valid staff bearer token from this account is required. Customer portal tokens are rejected.
- The document must belong to the account and its customer must be accessible to the current user. Proposal visibility restrictions also apply.
- The permission to create/edit the saved document type is required; blocked document states cannot be bypassed by owners or administrators.
Action
- Updates the existing document id in place. Keeps document number, type, customer, company, draft state and creation date.
- Only supplied editable fields change. items replaces all rows; order_all_fields merges individual custom field values.
- Uses the existing document update/PDF workflow. Order reservations are recalculated; the App update does not create a physical product stock movement. PDF work may finish after the response.
Push Service
- These routes do not promise a dedicated realtime event. Refresh the document through Documents.Get after changes.
Automation
- Runs the existing document update workflow. Synchronization of a detailed order with its linked Orders-list record may trigger existing update_order automations.
- Does not issue a new document or change the saved draft state. PDF processing may continue after the update acknowledgement.
Special Instructions
- On a company subdomain (e.g. https://{user_domain}.bull36.com) the user must match that Host — Login and protected APIs reject another company with success=0, error user_not_in_company. On a main brand host (bull36.com, biz1.co.il, mastrocrm.com, …) the company domain gate is skipped.
- Supported types: purchase_orders (הזמנה), detail_orders (הזמנה מפורטת), order_proposals (הצעת מחיר). Issued invoices, receipts and other accounting document types are rejected.
- Use a staff bearer token. Customer portal tokens cannot call these routes. Account ownership, customer assignment/sharing and proposal visibility are checked on the server.
- Documents.Edit and Documents.Delete remain uploaded-file operations. Use Documents.Update, Documents.Remove and Documents.Cancel for BUSINESS documents; the numeric id alone never switches resource type.
- Call Documents.Get first to inspect data and actions. Capabilities are advisory; the server checks them again when writing. Blocked actions return HTTP 409 document_action_blocked with a reason.
- Approved, paid or closed documents are blocked. Canceled documents cannot be updated or canceled again. Closed, paid or linked line items block update and cancel.
- Update and cancel require the permission to create/edit that document type. Remove requires Delete Order permission. Financial edits by team members also require discount-edit permissions and must respect the order price lock.
- No implicit cancellation cascade is exposed: any related document blocks cancellation. Handle relations through the dashboard before retrying. Removal also checks reverse links and children.
- Errors: 400 invalid id/unsupported parameter/empty update; 401 missing or invalid bearer token; 403 access/field permission denied; 404 document not found; 409 changed/busy/blocked; 422 unsupported type or invalid values. Do not blindly retry a mutation after a network timeout; inspect Documents.Get first.
- Send at least one editable field. Omitted fields are preserved; empty text clears text. items is a full replacement, while order_all_fields is a partial merge.
- Identity, customer_id, invoice_setting_id, type, approval, payment state, draft state, numbering, creation date and relation ids cannot be changed through Update. Unknown top-level parameters are rejected.
- Example to change only notes: {document_id:123,note:"Updated"}. Example for items: send document_id, items as JSON and final_amount for the entire document.
- An update follows the existing document workflow: PDF/inventory/automation processing may continue after the update response. Read Documents.Get again to obtain the refreshed pdf_url. Success acknowledges the database update and does not certify PDF completion.
- Optional item fields: item_auto_g_id (stable row id), item_type (product or title), item_discount and item_discount_type (percentage/price), item_vat_include (0/1), item_notes, item_costprice, item_edition, item_productdesc, item_storageid (warehouse id), item_SKU, item_create_date, item_group_id and iteeeem_group_unique_id. Do not set payment, closure or document-relation fields.
Required Parameters
| Name | Type | Sample | Explanation |
|---|---|---|---|
document_idpost | int | 123 | Existing BUSINESS document id from Documents.List or Documents.Get (not an uploaded file id). The server checks account and customer access. |
Optional Parameters
| Name | Type | Sample | What it gives |
|---|---|---|---|
expected_updated_datepost | string | 2026-11-16 08:00:00 | Recommended: copy data.updated_date from Documents.Get. A mismatch returns HTTP 409 document_changed; reload before retrying. Omit only if intentional last-write-wins behavior is acceptable. |
itemspost | json array | [{"iteeeem_id":0,"item_name":"Service","item_qty":2,"item_price":100,"item_total":200}] | Full REPLACEMENT of all line items, up to 250 rows. Omitted items keeps existing rows; [] clears rows. Each row requires iteeeem_id (0 for free text), item_name, item_qty, item_price, item_total. Send final_amount with any replacement. Preserve item_auto_g_id from Get for unchanged rows. Only product/title row types can be replaced. Product and warehouse ids must belong to this account. Closed, paid or linked lines cannot be edited. |
order_all_fieldspost | json object | {"order-delivery_note":"Call first"} | Partial merge of custom order fields by their saved order-* or order_* keys. Omitted keys keep existing values; an empty string clears a value. {} changes nothing. Relationship ids order_id_of_main and order_for_cust_id cannot be changed. |
final_amountpost | number | 236 | Final amount INCLUDING VAT for the entire document, not a delta. Required with items or total. The net total is derived as final_amount / (1 + tax / 100), using the existing dashboard calculation. Caller must send the correct full amount consistent with the rows and discounts; this route does not charge a payment. |
totalpost | number | 200 | Net amount before VAT; send final_amount together. When VAT applies, the server derives net total from final_amount and tax. |
taxpost | number | 18 | VAT percentage from 0 to 100, not the VAT amount. Omission keeps existing VAT. |
discountpost | number | 0 | Document discount value. Omission keeps existing discount; caller must reflect the discount in final_amount. |
discount_typepost | string | percentage | percentage or price. Omission keeps the existing mode. |
currencypost | string | ILS | Printed currency value; send the same currency format used on the existing document. No conversion or charge is performed. |
notepost | string | Updated customer note | Document notes. Omitted keeps the existing note; empty string clears it. |
note_headerpost | string | Header note | Note printed above the document items. Empty string clears it. |
proposal_titlepost | string | Updated proposal | Title shown on the document. Empty string clears it. |
namepost | string | Customer name | Printed customer name only; does not change the customer record or document owner. |
emailpost | string | [email protected] | Printed email only. Does not send the document. |
mobilepost | string | 0500000000 | Printed mobile number only. |
phonepost | string | 030000000 | Printed phone number only. |
addresspost | string | 1 Main St | Printed billing address. |
citypost | string | Tel Aviv | Printed city value. Use the same format as the saved document. |
corporationpost | string | 123456789 | Printed tax/company registration id. |
company_namepost | string | Example Ltd | Printed customer company name. |
document_langpost | string | he | Document language: he or en. Omission keeps existing language. |
due_datepost | date/datetime | 2026-12-01 | Due date in UTC: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. Empty string clears it. Send UTC date/time as Y-m-d H:i:s, for example 2026-07-20 10:00:00. The SDK converts user local Date/local datetime input to UTC before posting. |
Authentication
Send the bearer token returned by Login in the request header. The user must be from the same company domain as this Host — a token from another company is rejected (user_not_in_company).
Authorization: Bearer YOUR TOKEN
Sample Request
{
"url": "\/app\/Documents.Update",
"method": "POST",
"headers": {
"Authorization": "Bearer YOUR TOKEN"
},
"body": {
"document_id": "123",
"note": "Updated note",
"order_all_fields": "{\"order-delivery_note\": \"Call first\"}"
},
"url_user": "https:\/\/{user}.bull36.com\/app\/Documents.Update",
"url_domain": "https:\/\/{domain}\/app\/Documents.Update"
}Endpoint
POST /app/Documents.Update
POST https://{user}.bull36.com/app/Documents.Update
POST https://{domain}/app/Documents.UpdateSample Output
{
"success": 1,
"document_id": 123,
"message": "OK"
}JavaScript Example
const token = 'YOUR TOKEN';
const body = new URLSearchParams({
"document_id": "123",
"note": "Updated note",
"order_all_fields": "{\"order-delivery_note\": \"Call first\"}"
});
const response = await fetch('/app/Documents.Update', {
method: 'POST',
headers: { Authorization: 'Bearer ' + token },
body
});
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.message || 'Request failed');
console.log(result);
// Full item replacement example. Read the document first and keep unchanged row ids.
async function replaceItems(document, items, finalAmount) {
const body = new URLSearchParams({
document_id: String(document.id),
expected_updated_date: document.updated_date || "",
items: JSON.stringify(items),
final_amount: String(finalAmount)
});
const response = await fetch("/app/Documents.Update", {
method: "POST", headers: { Authorization: "Bearer " + token }, body
});
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.message || "Update failed");
return result;
}Error Example
{
"success": 0,
"error": "document_action_blocked",
"message": "Document is approved"
}