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

NameTypeSampleExplanation
document_id
post
int123Existing BUSINESS document id from Documents.List or Documents.Get (not an uploaded file id). The server checks account and customer access.

Optional Parameters

NameTypeSampleWhat it gives
expected_updated_date
post
string2026-11-16 08:00:00Recommended: 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.
items
post
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_fields
post
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_amount
post
number236Final 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.
total
post
number200Net amount before VAT; send final_amount together. When VAT applies, the server derives net total from final_amount and tax.
tax
post
number18VAT percentage from 0 to 100, not the VAT amount. Omission keeps existing VAT.
discount
post
number0Document discount value. Omission keeps existing discount; caller must reflect the discount in final_amount.
discount_type
post
stringpercentagepercentage or price. Omission keeps the existing mode.
currency
post
stringILSPrinted currency value; send the same currency format used on the existing document. No conversion or charge is performed.
note
post
stringUpdated customer noteDocument notes. Omitted keeps the existing note; empty string clears it.
note_header
post
stringHeader noteNote printed above the document items. Empty string clears it.
proposal_title
post
stringUpdated proposalTitle shown on the document. Empty string clears it.
name
post
stringCustomer namePrinted customer name only; does not change the customer record or document owner.
email
post
string[email protected]Printed email only. Does not send the document.
mobile
post
string0500000000Printed mobile number only.
phone
post
string030000000Printed phone number only.
address
post
string1 Main StPrinted billing address.
city
post
stringTel AvivPrinted city value. Use the same format as the saved document.
corporation
post
string123456789Printed tax/company registration id.
company_name
post
stringExample LtdPrinted customer company name.
document_lang
post
stringheDocument language: he or en. Omission keeps existing language.
due_date
post
date/datetime2026-12-01Due 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.Update

Sample 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"
}