Reference

Every endpoint, every field, every response — generated from the same schema that validates your requests. Machine-readable: openapi.yaml.

GET /v1/me GET /v1/document-types POST /v1/documents GET /v1/documents GET /v1/documents/{id}POST /v1/documents/{id}/cancel GET /v1/customers GET /v1/errors The Document object Conventions

00Conventions

Base URL

https://api.chat-invoice.co.il/v1

Auth

Authorization: Bearer ci_live_… (or X-Api-Key)

Content

Content-Type: application/json; body ≤ 256 KB; UTF-8

Dates

YYYY-MM-DD, Asia/Jerusalem. Timestamps ISO-8601 UTC.

Money

Numbers (not strings), ILS, 2 decimals. unit_price is net or gross per prices_include_vat.

Ids

UUIDs, scoped to the key's business. A foreign id is a 404.

Headers out

X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Idempotent-Replayed

Scopes

documents:write · documents:read · customers:read (a default key has all three)

GET/v1/me

Business profile, allowed document types, allocation threshold, auto-send settings, limits and key info. Call it first.

{
  "business": {
    "id": "7f338082-d764-4fcb-8b69-1205043761b9",
    "name": "רמי המוביל",
    "legal_type": "osek_murshe",
    "legal_type_he": "עוסק מורשה",
    "tax_id": "333122216",
    "vat_rate": 18,
    "prices_include_vat": true
  },
  "allowed_document_types": [
    "quote",
    "order",
    "delivery_note",
    "return_note",
    "proforma",
    "tax_invoice",
    "tax_invoice_receipt",
    "receipt",
    "credit_note",
    "donation_receipt"
  ],
  "tax_authority_connected": true,
  "allocation_threshold_net": 5000,
  "auto_send": {
    "enabled": true,
    "channel": "whatsapp",
    "quiet_hours": "21:00-08:00"
  },
  "limits": {
    "per_minute": 60,
    "daily_documents": 300,
    "used_today": 3
  },
  "key": {
    "name": "WooCommerce",
    "prefix": "ci_live_zq2O",
    "scopes": [
      "documents:write",
      "documents:read",
      "customers:read"
    ],
    "created_at": "2026-09-07T09:00:00Z"
  }
}

GET/v1/document-types

The document types this business may issue, with their rules.

{
  "data": [
    {
      "type": "receipt",
      "name": "Receipt",
      "name_he": "קבלה",
      "requires_payments": true,
      "allows_discount": false,
      "based_on_types": [
        "tax_invoice",
        "proforma"
      ],
      "based_on_required": false
    }
  ]
}

POST/v1/documents

Issue a document. Requires Idempotency-Key. Returns 201 with the Document object plus allocation and delivery.

Request body

field	type		notes
`type`	enum	required	`quote` `order` `delivery_note` `return_note` `proforma` `tax_invoice` `tax_invoice_receipt` `receipt` `credit_note` `donation_receipt`
`date`	string		Document date. Defaults to today (Israel). Cannot be in the future or earlier than the last document of the same type. `^\d{4}-\d{2}-\d{2}$`
`due_date`	string		Payment due date (tax_invoice / proforma only). Defaults to the business payment terms. `^\d{4}-\d{2}-\d{2}$`
`customer`	object	required	Either `id` of an existing customer, or `name` (+ optional details) to find-or-create one. Details never overwrite an existing card — they only fill empty fields.
`customer.id`	string		Existing customer id (from GET /v1/customers) uuid
`customer.name`	string		length 2–120
`customer.tax_id`	string		ח.פ / ע.מ / ת.ז — up to 9 digits, Israeli checksum validated. Required for a tax-authority allocation number. `^\d{5,9}$`
`customer.legal_type`	enum		`hevra_baam` `osek_murshe` `osek_patur` `amuta` `private`
`customer.email`	string		length 0–254 · email
`customer.phone`	string		`^\+?[0-9\-\s]{7,20}$`
`customer.address`	string		length 0–200
`customer.city`	string		length 0–80
`customer.identity_confirmed`	boolean		Send `true` only after a 409 customer_identity_conflict, to open a separate card that shares the same tax_id (e.g. a branch).
`items`	array of object	required	1–100 items
`items[].description`	string	required	length 1–200
`items[].quantity`	number	required	> 0 ≤ 1,000,000
`items[].unit_price`	number	required	Per unit, in ILS. Net or gross according to `prices_include_vat`. ≥ 0 ≤ 100,000,000
`items[].sku`	string		length 0–64
`prices_include_vat`	boolean		Whether `unit_price` already includes VAT. Defaults to the business setting.
`discount`	object		Document-level discount. Not allowed on receipts.
`discount.type`	enum	required	`percent` `amount`
`discount.value`	number	required	> 0 ≤ 100,000,000
`payments`	array of object		Required for receipt / tax_invoice_receipt / donation_receipt; forbidden otherwise. Must sum to the document total. 1–20 items
`payments[].method`	enum	required	`cash` `check` `credit_card` `bank_transfer` `paypal` `bit` `apple_pay` `google_pay` `paybox`
`payments[].amount`	number	required	> 0 ≤ 100,000,000
`payments[].date`	string		YYYY-MM-DD (Asia/Jerusalem) `^\d{4}-\d{2}-\d{2}$`
`payments[].reference`	string		Transfer / transaction reference length 0–64
`payments[].check_number`	string		length 0–20
`payments[].check_date`	string		YYYY-MM-DD (Asia/Jerusalem) `^\d{4}-\d{2}-\d{2}$`
`payments[].bank_code`	integer		≥ 1 ≤ 99
`payments[].branch`	string		length 0–10
`payments[].account`	string		length 0–20
`payments[].card_last_digits`	string		`^\d{4}$`
`payments[].card_type`	string		length 0–20
`based_on`	string		Source document id (credit_note: required, a tax_invoice / tax_invoice_receipt; receipt: a tax_invoice to close). uuid
`title`	string		Short header printed on the document (e.g. project name) length 0–120
`notes`	string		length 0–1000
`expected_total`	number		Optional safety check: if our computed total differs by more than 0.01 the document is NOT issued (422 total_mismatch). ≥ 0 ≤ 100,000,000
`send`	boolean		`false` suppresses the business auto-send for this document. default `true`
`external_ref`	string		Your own reference (order id). Echoed back and searchable in GET /v1/documents. length 0–64

Rules by type

type	Hebrew	English	payments	discount	exempt dealer / NPO
`quote`	הצעת מחיר	Quote	not allowed	yes	yes
`order`	הזמנה	Order	not allowed	yes	yes
`delivery_note`	תעודת משלוח	Delivery note	not allowed	yes	yes
`return_note`	החזרה מלקוח	Return note	not allowed	yes	yes
`proforma`	חשבונית עסקה	Proforma invoice	not allowed	yes	yes
`tax_invoice`	חשבונית מס	Tax invoice	not allowed	yes	no
`tax_invoice_receipt`	חשבונית מס/קבלה	Tax invoice receipt	required	yes	no
`receipt`	קבלה	Receipt	required	no	yes
`credit_note`	חשבונית זיכוי	Credit note	not allowed	yes	no
`donation_receipt`	קבלה על תרומה	Donation receipt	required	no	yes

Payment methods

method	עברית	extra fields
`cash`	מזומן	—
`bank_transfer`	העברה בנקאית	`reference`
`credit_card`	כרטיס אשראי	`card_last_digits`, `card_type`
`check`	המחאה	`check_number`, `check_date`, `bank_code`, `branch`, `account`
`bit` · `paybox` · `paypal` · `apple_pay` · `google_pay`	ביט · פייבוקס · PayPal · Apple Pay · Google Pay	`reference`

Examples

{
  "type": "quote",
  "customer": {
    "name": "ישראל ישראלי בע\"מ",
    "tax_id": "515123456",
    "email": "billing@example.co.il",
    "phone": "0501234567"
  },
  "items": [
    {
      "description": "הובלת דירה 4 חדרים",
      "quantity": 1,
      "unit_price": 2500
    },
    {
      "description": "אריזה",
      "quantity": 10,
      "unit_price": 45
    }
  ],
  "title": "הצעה למעבר דירה",
  "notes": "תוקף ההצעה 14 יום",
  "external_ref": "crm-8812"
}

{
  "type": "tax_invoice_receipt",
  "customer": {
    "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60"
  },
  "items": [
    {
      "description": "שירות חודשי — ספטמבר",
      "quantity": 1,
      "unit_price": 590
    }
  ],
  "payments": [
    {
      "method": "bank_transfer",
      "amount": 590,
      "reference": "778812"
    }
  ],
  "expected_total": 590,
  "external_ref": "order-10021"
}

{
  "type": "credit_note",
  "based_on": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "customer": {
    "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60"
  },
  "items": [
    {
      "description": "זיכוי — שירות חודשי ספטמבר",
      "quantity": 1,
      "unit_price": 590
    }
  ]
}

Response `201`

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "public_id": "RFayPUSCNKnD",
  "type": "tax_invoice_receipt",
  "number": 60294,
  "status": "closed",
  "date": "2026-09-07",
  "due_date": null,
  "external_ref": "order-10021",
  "customer": {
    "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60",
    "name": "ישראל ישראלי בע\"מ",
    "tax_id": "515123456"
  },
  "totals": {
    "subtotal": 500,
    "discount": 0,
    "vat": 90,
    "vat_rate": 18,
    "total": 590,
    "paid": 590,
    "currency": "ILS"
  },
  "allocation_number": null,
  "allocation": {
    "status": "not_required",
    "number": null,
    "reason": null
  },
  "delivery": {
    "status": "queued",
    "channel": "whatsapp",
    "scheduled_for": null
  },
  "view_url": "https://doc.chat-invoice.co.il/view/RFayPUSCNKnD",
  "pdf_url": "https://doc.chat-invoice.co.il/pdf/RFayPUSCNKnD",
  "based_on": null,
  "cancelled_at": null,
  "created_at": "2026-09-07T10:21:44.120Z"
}

Errors

400 validation_error · missing_idempotency_key · invalid_customer_tax_id · 404 customer_not_found · based_on_not_found · 409 idempotency_key_reused · request_in_progress · customer_identity_conflict · 422 legal_type_forbidden · payments_required · payments_not_allowed · payments_total_mismatch · discount_not_allowed · based_on_required · based_on_type_not_allowed · based_on_cancelled · total_mismatch · future_date · date_before_last_document · 429 daily_limit_reached · 502 document_generation_failed · engine_error — see errors.

GET/v1/documents

List issued documents, newest first. Cancelled documents are hidden unless include_cancelled=true. Keyset pagination via next_cursor.

query	type	notes
`type`	enum	one of the document types
`from` / `to`	date	document date range (inclusive)
`external_ref`	string	your reference as sent on creation
`include_cancelled`	boolean	default false
`limit`	1–100	default 50
`cursor`	string	`next_cursor` of the previous page

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "public_id": "RFayPUSCNKnD",
      "type": "tax_invoice_receipt",
      "number": 60294,
      "status": "closed",
      "date": "2026-09-07",
      "due_date": null,
      "external_ref": "order-10021",
      "customer": {
        "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60",
        "name": "ישראל ישראלי בע\"מ",
        "tax_id": "515123456"
      },
      "totals": {
        "subtotal": 500,
        "discount": 0,
        "vat": 90,
        "vat_rate": 18,
        "total": 590,
        "paid": 590,
        "currency": "ILS"
      },
      "allocation_number": null,
      "allocation": {
        "status": "not_required",
        "number": null,
        "reason": null
      },
      "delivery": {
        "status": "queued",
        "channel": "whatsapp",
        "scheduled_for": null
      },
      "view_url": "https://doc.chat-invoice.co.il/view/RFayPUSCNKnD",
      "pdf_url": "https://doc.chat-invoice.co.il/pdf/RFayPUSCNKnD",
      "based_on": null,
      "cancelled_at": null,
      "created_at": "2026-09-07T10:21:44.120Z"
    }
  ],
  "next_cursor": "MjAyNi0wOS0wN1QxMDoyMTo0NC4xMjBaZ..."
}

GET/v1/documents/{id}

One document, including items[], payments[], title and notes.

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "public_id": "RFayPUSCNKnD",
  "type": "tax_invoice_receipt",
  "number": 60294,
  "status": "closed",
  "date": "2026-09-07",
  "due_date": null,
  "external_ref": "order-10021",
  "customer": {
    "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60",
    "name": "ישראל ישראלי בע\"מ",
    "tax_id": "515123456"
  },
  "totals": {
    "subtotal": 500,
    "discount": 0,
    "vat": 90,
    "vat_rate": 18,
    "total": 590,
    "paid": 590,
    "currency": "ILS"
  },
  "allocation_number": null,
  "view_url": "https://doc.chat-invoice.co.il/view/RFayPUSCNKnD",
  "pdf_url": "https://doc.chat-invoice.co.il/pdf/RFayPUSCNKnD",
  "based_on": null,
  "cancelled_at": null,
  "created_at": "2026-09-07T10:21:44.120Z",
  "title": "שירות חודשי",
  "notes": null,
  "items": [
    {
      "description": "שירות חודשי — ספטמבר",
      "quantity": 1,
      "unit_price": 500,
      "line_total": 500,
      "sku": null
    }
  ],
  "payments": [
    {
      "method": "bank_transfer",
      "amount": 590,
      "date": "2026-09-07",
      "reference": "778812",
      "check_number": null,
      "bank_code": null,
      "card_last_digits": null
    }
  ]
}

POST/v1/documents/{id}/cancel

Cancel a quote / order / delivery note / return note / proforma. Accounting documents answer 422 use_credit_note.

field	type		notes
`reason`	string		length 0–200

Returns 200 with the Document object (status: "cancelled").

GET/v1/customers

Search the business's customers by name (contains) or exact tax id. q, limit ≤ 50.

{
  "data": [
    {
      "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60",
      "name": "ישראל ישראלי בע\"מ",
      "tax_id": "515123456",
      "legal_type": "hevra_baam",
      "email": "billing@example.co.il",
      "phone": "0501234567",
      "city": "תל אביב"
    }
  ]
}

GET/v1/errors

The error catalog as JSON (no auth required).

99The Document object

field	type	notes
`id`	string	uuid
`public_id`	string
`type`	enum	`quote` `order` `delivery_note` `return_note` `proforma` `tax_invoice` `tax_invoice_receipt` `receipt` `credit_note` `donation_receipt`
`number`	integer
`status`	enum	`open` `closed` `cancelled`
`date`	string	date
`due_date`	string \| null	date
`external_ref`	string \| null
`customer`	object
`customer.id`	string \| null
`customer.name`	string \| null
`customer.tax_id`	string \| null
`totals`	object
`totals.subtotal`	number
`totals.discount`	number
`totals.vat`	number
`totals.vat_rate`	number
`totals.total`	number
`totals.paid`	number
`totals.currency`	string
`allocation_number`	string \| null
`allocation`	object	Only on creation responses.
`allocation.status`	enum	`not_required` `issued` `skipped_customer_tax_id_missing` `skipped_business_tax_id_missing` `failed`
`allocation.number`	string \| null
`allocation.reason`	string \| null
`delivery`	object	Only on creation responses. Auto-send to the end customer per the business settings.
`delivery.status`	enum	`queued` `deferred_quiet_hours` `disabled` `suppressed` `no_recipient` `send_failed`
`delivery.channel`	string \| null
`delivery.scheduled_for`	string \| null	date-time
`view_url`	string	uri
`pdf_url`	string	uri
`based_on`	string \| null	uuid
`cancelled_at`	string \| null	date-time
`created_at`	string	date-time
`items`	array of object	Only on GET /v1/documents/{id}.
`items[].description`	string
`items[].quantity`	number
`items[].unit_price`	number
`items[].line_total`	number
`items[].sku`	string \| null
`payments`	array of object	Only on GET /v1/documents/{id}.
`payments[].method`	string
`payments[].amount`	number
`payments[].date`	string	date
`payments[].reference`	string \| null

ChatInvoice · API v1.0 · updated 2026-09-07 · openapi.yaml · llms.txt