# ChatInvoice Public API

> Issue legally valid Israeli accounting documents (quotes, invoices, receipts, credit notes) for a ChatInvoice business from any external system. Base URL https://api.chat-invoice.co.il/v1 · Bearer API key (ci_live_…) · JSON · ILS · dates YYYY-MM-DD (Asia/Jerusalem) · server-to-server only.

Key facts: the caller never sends document numbers, VAT rates, totals or allocation numbers — the engine computes them from the business settings and Israeli law. POST /v1/documents requires an Idempotency-Key header. Exempt dealers / NPOs cannot issue tax invoices (use receipt / proforma). Accounting documents are never cancelled — issue a credit_note with based_on. Documents are always issued; allocation numbers and customer delivery are best-effort and reported in allocation.status / delivery.status.

## Docs
- [Guide (English)](https://api.chat-invoice.co.il/docs)
- [Guide (Hebrew)](https://api.chat-invoice.co.il/docs/he)
- [Reference — endpoints & fields](https://api.chat-invoice.co.il/docs/reference)
- [Error catalog](https://api.chat-invoice.co.il/docs/errors)
- [Integration guide for AI agents](https://api.chat-invoice.co.il/docs/agents)
- [Changelog](https://api.chat-invoice.co.il/docs/changelog)

## Machine-readable
- [OpenAPI 3.1 (YAML)](https://api.chat-invoice.co.il/openapi.yaml)
- [OpenAPI 3.1 (JSON)](https://api.chat-invoice.co.il/openapi.json)
- [Full docs as text](https://api.chat-invoice.co.il/llms-full.txt)
- Error catalog as JSON: GET https://api.chat-invoice.co.il/v1/errors


---

# English guide

Developer guide — ChatInvoice API

Issue documents from any system

The ChatInvoice API lets a website, shop, CRM or any other system issue legally valid Israeli accounting documents on behalf of a business — quotes, invoices, receipts and credit notes — with sequential numbering, a digitally signed PDF, a tax-authority allocation number when required, and delivery to the customer per the business settings.

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

Auth
Authorization: Bearer ci_live_…

Format
JSON · dates YYYY-MM-DD (Israel time) · amounts in ILS, 2 decimals

Spec
OpenAPI 3.1 · Reference · Errors

01Quick start

Create a key in the app: Settings → Connections → API → “Create key”. It is shown once — store it server-side.

Check the connection and see what the business may issue:
curl https://api.chat-invoice.co.il/v1/me -H "Authorization: Bearer $CHATINVOICE_API_KEY"

Issue a quote for a new customer:

curlNodePythonPHP

curl -X POST https://api.chat-invoice.co.il/v1/documents \
  -H "Authorization: Bearer $CHATINVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-8812" \
  -d '{"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"}'

const res = await fetch("https://api.chat-invoice.co.il/v1/documents", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.CHATINVOICE_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "crm-8812",
  },
  body: JSON.stringify({
    "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"
  }),
});
const doc = await res.json();
if (!res.ok) throw new Error(doc.error.code + ": " + doc.error.message);
console.log(doc.number, doc.view_url, doc.pdf_url);

import os, requests

r = requests.post(
    "https://api.chat-invoice.co.il/v1/documents",
    headers={
        "Authorization": f"Bearer {os.environ['CHATINVOICE_API_KEY']}",
        "Idempotency-Key": "crm-8812",
    },
    json={
        "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"
    },
    timeout=90,
)
doc = r.json()
if not r.ok:
    raise RuntimeError(f"{doc['error']['code']}: {doc['error']['message']}")
print(doc["number"], doc["view_url"], doc["pdf_url"])

$ch = curl_init("https://api.chat-invoice.co.il/v1/documents");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("CHATINVOICE_API_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: crm-8812",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "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"
  ], JSON_UNESCAPED_UNICODE),
]);
$doc = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) { throw new Exception($doc["error"]["code"]); }
echo $doc["number"], " ", $doc["view_url"];

The 201 response carries the document number, the totals as computed, a view link and a PDF link:

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "public_id": "RFayPUSCNKnD",
  "type": "quote",
  "number": 1328,
  "status": "open",
  "date": "2026-09-07",
  "due_date": null,
  "external_ref": "crm-8812",
  "customer": {
    "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60",
    "name": "ישראל ישראלי בע\"מ",
    "tax_id": "515123456"
  },
  "totals": {
    "subtotal": 2500,
    "discount": 0,
    "vat": 450,
    "vat_rate": 18,
    "total": 2950,
    "paid": 0,
    "currency": "ILS"
  },
  "allocation_number": null,
  "allocation": {
    "status": "not_required",
    "number": null,
    "reason": null
  },
  "delivery": {
    "status": "disabled",
    "channel": null,
    "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"
}

A paid tax invoice receipt for an existing customer (customer.id), with a total check:

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

02Authentication & security

Every request carries Authorization: Bearer ci_live_…. The key identifies the business; all documents and customers are scoped to it.

The key is a secret: never in client-side code, a mobile app or git. There is no CORS — the API is server-to-server.

Revocation is immediate, from the same screen. Hold several keys (one per system) if you like.

Idempotency-Key is required on every issue. It is what prevents a duplicate invoice when a request times out and you retry: same key + same body → the same document (with Idempotent-Replayed: true). Same key + different body → 409.

Every response returns X-Request-Id — quote it to support.

03What a business may issue

The legal type of the business decides which documents are lawful. An exempt dealer (osek patur), an NPO or a public institution does not issue tax invoices — it issues a receipt for a payment and a proforma invoice as a payment request. Such a request gets 422 legal_type_forbidden and no number is consumed. GET /v1/document-types returns only what this business may issue.

typeHebrewEnglishpaymentsdiscountexempt dealer / NPO
quoteהצעת מחירQuotenot allowedyesyes
orderהזמנהOrdernot allowedyesyes
delivery_noteתעודת משלוחDelivery notenot allowedyesyes
return_noteהחזרה מלקוחReturn notenot allowedyesyes
proformaחשבונית עסקהProforma invoicenot allowedyesyes
tax_invoiceחשבונית מסTax invoicenot allowedyesno
tax_invoice_receiptחשבונית מס/קבלהTax invoice receiptrequiredyesno
receiptקבלהReceiptrequirednoyes
credit_noteחשבונית זיכויCredit notenot allowedyesno
donation_receiptקבלה על תרומהDonation receiptrequirednoyes

What you never send: document numbers, VAT rate, VAT exemption, allocation numbers, status, final totals. All of these come from the business settings and Israeli law — an unknown field is rejected with 400.

Date (date) — defaults to today. Never in the future and never earlier than the last document of the same type (the Israeli sequence rule). Error: 422 date_before_last_document with the earliest allowed date.

Customer — either customer.id of an existing customer (from GET /v1/customers) or customer.name + details. A name that already exists attaches to that card; new details only fill empty fields, never overwrite. A tax id that belongs to a differently-named customer → 409 customer_identity_conflict, so a document is never attached to the wrong customer.

Source document (based_on) — a receipt against a tax invoice closes it automatically; a credit note requires one.

04Amounts, VAT and payments

Send items (description, quantity, unit_price) and optionally a document discount. We compute subtotal, VAT and rounding — with the same engine as the chat and the app.

prices_include_vat says whether your unit prices are gross. Defaults to the business setting (see /v1/me). The VAT rate comes from the business settings (exempt dealers and Eilat businesses: 0).

expected_total is a safety net: if our total differs by more than 0.01 the document is not issued (422 total_mismatch with our figure).

Payments are required on receipt / tax invoice receipt / donation receipt and not allowed elsewhere. They must sum to the total.

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 Payreference

05Allocation number (חשבונית ישראל)

A tax invoice, tax invoice receipt or credit note above ₪5,000 net (before VAT) needs an allocation number from the Israel Tax Authority for the customer to reclaim VAT. When the business is connected (tax_authority_connected in /v1/me) we request the number automatically after issuing and bake it into the PDF.

This needs the customer's tax id — send customer.tax_id (or have it on the customer card).

The document is always issued. If the tax id is missing, the business is not connected, or the authority did not answer, the document goes out without an allocation number and allocation.status says exactly why: issued · not_required · skipped_customer_tax_id_missing · skipped_business_tax_id_missing · failed.

Later completion: the business owner asks in chat to complete the allocation for that document number.

06Delivery to the customer

If the business has auto-send enabled (Settings → Automation), every document issued through the API is sent to the customer on the configured channel — WhatsApp, email or both — exactly like a chat-issued document, including quiet hours (a document issued at night goes out in the morning). delivery.status reports: queued · deferred_quiet_hours (+scheduled_for) · no_recipient (no phone/email on the card) · disabled · suppressed · send_failed.

Prefer to send yourself? Pass "send": false and use view_url (hosted page) or pdf_url (file). The accountant copy follows the business settings regardless.

07Cancel & credit

An issued document is never deleted — its number stays in the book.

Quote, order, delivery note, return note, proforma — POST /v1/documents/{id}/cancel marks it cancelled.

Tax invoice, tax invoice receipt, receipt — no cancel. Issue a credit note (type: credit_note, based_on: the invoice id) with the same items. A cancel attempt returns 422 use_credit_note with a ready example.

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

08Limits, subscription, versioning

60 requests per minute and 300 documents per day per key (RateLimit-* headers; 429 with Retry-After). Need more? Talk to us.

The API is available to businesses with an active subscription. Otherwise you get 402 subscription_required with a payment link in details.payment_url.

A business that issues through external accounting software (iCount, Green Invoice, …) cannot use the API (403).

/v1 is stable. New response fields are not breaking — ignore unknown fields. Breaking changes get /v2. Changelog.

09Errors

Every error has the same shape: a stable code, a message, a hint on what to do, and a retryable flag:

{
  "error": {
    "code": "legal_type_forbidden",
    "message": "This business type may not issue the requested document type.",
    "message_he": "סוג העוסק אינו רשאי להפיק מסמך מסוג זה.",
    "hint": "GET /v1/document-types lists what this business may issue. An exempt dealer (osek patur) issues receipts / proforma invoices instead of tax invoices.",
    "retryable": false,
    "doc_url": "https://api.chat-invoice.co.il/docs/errors#legal_type_forbidden"
  },
  "request_id": "5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e"
}

Full catalog: /docs/errors · as JSON: GET /v1/errors.

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

---

# Reference

Reference — ChatInvoice API

Reference

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

GET /v1/meGET /v1/document-typesPOST /v1/documentsGET /v1/documentsGET /v1/documents/{id}POST /v1/documents/{id}/cancelGET /v1/customersGET /v1/errorsThe Document objectConventions

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

fieldtypenotes
typeenumrequiredquote order delivery_note return_note proforma tax_invoice tax_invoice_receipt receipt credit_note donation_receipt
datestringDocument 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_datestringPayment due date (tax_invoice / proforma only). Defaults to the business payment terms.^\d{4}-\d{2}-\d{2}$
customerobjectrequiredEither `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.idstringExisting customer id (from GET /v1/customers)uuid
customer.namestringlength 2–120
customer.tax_idstringח.פ / ע.מ / ת.ז — up to 9 digits, Israeli checksum validated. Required for a tax-authority allocation number.^\d{5,9}$
customer.legal_typeenumhevra_baam osek_murshe osek_patur amuta private
customer.emailstringlength 0–254 · email
customer.phonestring^\+?[0-9\-\s]{7,20}$
customer.addressstringlength 0–200
customer.citystringlength 0–80
customer.identity_confirmedbooleanSend `true` only after a 409 customer_identity_conflict, to open a separate card that shares the same tax_id (e.g. a branch).
itemsarray of objectrequired1–100 items
items[].descriptionstringrequiredlength 1–200
items[].quantitynumberrequired> 0 ≤ 1,000,000
items[].unit_pricenumberrequiredPer unit, in ILS. Net or gross according to `prices_include_vat`.≥ 0 ≤ 100,000,000
items[].skustringlength 0–64
prices_include_vatbooleanWhether `unit_price` already includes VAT. Defaults to the business setting.
discountobjectDocument-level discount. Not allowed on receipts.
discount.typeenumrequiredpercent amount
discount.valuenumberrequired> 0 ≤ 100,000,000
paymentsarray of objectRequired for receipt / tax_invoice_receipt / donation_receipt; forbidden otherwise. Must sum to the document total.1–20 items
payments[].methodenumrequiredcash check credit_card bank_transfer paypal bit apple_pay google_pay paybox
payments[].amountnumberrequired> 0 ≤ 100,000,000
payments[].datestringYYYY-MM-DD (Asia/Jerusalem)^\d{4}-\d{2}-\d{2}$
payments[].referencestringTransfer / transaction referencelength 0–64
payments[].check_numberstringlength 0–20
payments[].check_datestringYYYY-MM-DD (Asia/Jerusalem)^\d{4}-\d{2}-\d{2}$
payments[].bank_codeinteger≥ 1 ≤ 99
payments[].branchstringlength 0–10
payments[].accountstringlength 0–20
payments[].card_last_digitsstring^\d{4}$
payments[].card_typestringlength 0–20
based_onstringSource document id (credit_note: required, a tax_invoice / tax_invoice_receipt; receipt: a tax_invoice to close).uuid
titlestringShort header printed on the document (e.g. project name)length 0–120
notesstringlength 0–1000
expected_totalnumberOptional safety check: if our computed total differs by more than 0.01 the document is NOT issued (422 total_mismatch).≥ 0 ≤ 100,000,000
sendboolean`false` suppresses the business auto-send for this document.default true
external_refstringYour own reference (order id). Echoed back and searchable in GET /v1/documents.length 0–64

Rules by type

typeHebrewEnglishpaymentsdiscountexempt dealer / NPO
quoteהצעת מחירQuotenot allowedyesyes
orderהזמנהOrdernot allowedyesyes
delivery_noteתעודת משלוחDelivery notenot allowedyesyes
return_noteהחזרה מלקוחReturn notenot allowedyesyes
proformaחשבונית עסקהProforma invoicenot allowedyesyes
tax_invoiceחשבונית מסTax invoicenot allowedyesno
tax_invoice_receiptחשבונית מס/קבלהTax invoice receiptrequiredyesno
receiptקבלהReceiptrequirednoyes
credit_noteחשבונית זיכויCredit notenot allowedyesno
donation_receiptקבלה על תרומהDonation receiptrequirednoyes

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 Payreference

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.

querytypenotes

typeenumone of the document types

from / todatedocument date range (inclusive)

external_refstringyour reference as sent on creation

include_cancelledbooleandefault false

limit1–100default 50

cursorstringnext_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.

fieldtypenotes
reasonstringlength 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

fieldtypenotes
idstringuuid
public_idstring
typeenumquote order delivery_note return_note proforma tax_invoice tax_invoice_receipt receipt credit_note donation_receipt
numberinteger
statusenumopen closed cancelled
datestringdate
due_datestring | nulldate
external_refstring | null
customerobject
customer.idstring | null
customer.namestring | null
customer.tax_idstring | null
totalsobject
totals.subtotalnumber
totals.discountnumber
totals.vatnumber
totals.vat_ratenumber
totals.totalnumber
totals.paidnumber
totals.currencystring
allocation_numberstring | null
allocationobjectOnly on creation responses.
allocation.statusenumnot_required issued skipped_customer_tax_id_missing skipped_business_tax_id_missing failed
allocation.numberstring | null
allocation.reasonstring | null
deliveryobjectOnly on creation responses. Auto-send to the end customer per the business settings.
delivery.statusenumqueued deferred_quiet_hours disabled suppressed no_recipient send_failed
delivery.channelstring | null
delivery.scheduled_forstring | nulldate-time
view_urlstringuri
pdf_urlstringuri
based_onstring | nulluuid
cancelled_atstring | nulldate-time
created_atstringdate-time
itemsarray of objectOnly on GET /v1/documents/{id}.
items[].descriptionstring
items[].quantitynumber
items[].unit_pricenumber
items[].line_totalnumber
items[].skustring | null
paymentsarray of objectOnly on GET /v1/documents/{id}.
payments[].methodstring
payments[].amountnumber
payments[].datestringdate
payments[].referencestring | null

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

---

# Errors

Errors — ChatInvoice API

Errors

One shape for every failure. code is stable and safe to branch on; retryable: true means the same request (same Idempotency-Key) may be sent again; hint is written for whoever — or whatever — is integrating.

{
  "error": {
    "code": "date_before_last_document",
    "message": "Document date is earlier than the last document of the same type.",
    "message_he": "התאריך מוקדם מהמסמך האחרון מסוג זה.",
    "hint": "Israeli sequence rule: use details.last_document_date or later.",
    "retryable": false,
    "doc_url": "https://api.chat-invoice.co.il/docs/errors#date_before_last_document"
  },
  "request_id": "5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e"
}

httpmeaning

400Malformed request — fix the body
401Key missing / invalid / revoked
402Subscription not active
403Not available for this business or scope
404Not found in this business
409Conflict — idempotency or customer identity
422Valid request, but a business rule says no (nothing was issued)
429Rate or daily limit
502 / 503Our side — retryable

unauthorized401
Missing or invalid API key.מפתח API חסר או לא תקין.→ Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections → API.
key_revoked401
This API key was revoked.מפתח ה-API בוטל.→ Create a new key in the app.
subscription_required402
The business has no active paid subscription.לעסק אין מנוי פעיל.→ The API is available to paying subscribers. `details.payment_url` opens the subscription page.
business_archived403
The business is archived.העסק בארכיון.→ Contact support.
business_profile_incomplete403
The business profile is missing its legal type.פרופיל העסק חסר סוג-עוסק.→ Complete the business profile in the app (legal type / tax id).
external_provider_not_supported403
This business issues documents through an external accounting provider; the API supports native businesses only.העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.→ Not available for this business.
issuing_blocked_expenses_only403
The business is on an expenses-only track and cannot issue documents.המסלול של העסק כולל ניהול הוצאות בלבד.→ The accounting office must upgrade the track.
insufficient_scope403
The API key does not have the required scope.למפתח אין הרשאה לפעולה זו.→ Scopes: documents:write, documents:read, customers:read.
not_found404
Resource not found.לא נמצא.→ Ids are scoped to the business of the API key.
customer_not_found404
customer.id does not belong to this business.הלקוח לא נמצא בעסק.→ Use GET /v1/customers?q= to find the id, or send customer.name instead.
based_on_not_found404
based_on document not found in this business.מסמך המקור לא נמצא.→ Use the `id` returned when the source document was created, or GET /v1/documents.
invalid_json400
Request body is not valid JSON.גוף הבקשה אינו JSON תקין.→ Send `Content-Type: application/json`.
validation_error400
Request failed schema validation.הבקשה לא עברה ולידציה.→ See details.errors[] (path + message). Unknown fields are rejected — never send document numbers, VAT rate, totals or allocation numbers.
missing_idempotency_key400
Idempotency-Key header is required for POST /v1/documents.חסרה כותרת Idempotency-Key.→ Send a unique string per logical document (e.g. your order id + attempt). Retries with the same key return the same document instead of issuing twice.
invalid_customer_tax_id400
customer.tax_id failed the Israeli checksum.ח.פ/ע.מ/ת.ז של הלקוח לא תקין.→ Fix the number or omit it (a document above the allocation threshold will then be issued without an allocation number).
idempotency_key_reused409
Idempotency-Key was already used with a different request body.מפתח ה-Idempotency כבר שימש לבקשה אחרת.→ Use a new key for a new document.
request_in_progress409 · retryable
A request with this Idempotency-Key is still being processed.בקשה עם אותו מפתח עדיין בעיבוד.→ Retry the same request in a few seconds; you will get the stored result.
customer_identity_conflict409
customer.tax_id belongs to a differently-named customer of this business.הח.פ רשום על לקוח אחר בכרטסת.→ Either send customer.id = details.existing_customer_id, or set customer.identity_confirmed=true to open a separate card.
legal_type_forbidden422
This business type may not issue the requested document type.סוג העוסק אינו רשאי להפיק מסמך מסוג זה.→ GET /v1/document-types lists what this business may issue. An exempt dealer (osek patur) issues receipts / proforma invoices instead of tax invoices.
payments_required422
This document type requires payments.סוג מסמך זה דורש פירוט תשלומים.→ Add payments[] summing to the total, or use tax_invoice / proforma for an unpaid document.
payments_not_allowed422
This document type does not carry payments.סוג מסמך זה אינו כולל תשלומים.→ Remove payments[], or use tax_invoice_receipt / receipt.
payments_total_mismatch422
payments[] do not sum to the document total.סכום התשלומים אינו שווה לסה"כ המסמך.→ details.total is the computed total; make payments sum to it (±0.01).
discount_not_allowed422
Receipts do not carry a document discount.קבלה אינה כוללת הנחה.→ Remove discount.
based_on_required422
credit_note requires based_on (the invoice being credited).חשבונית זיכוי דורשת מסמך מקור.→ Send based_on = id of the tax_invoice / tax_invoice_receipt.
based_on_type_not_allowed422
based_on document type cannot be the source of this document type.סוג מסמך המקור אינו מתאים.→ See details.allowed_source_types.
based_on_cancelled422
based_on document is cancelled.מסמך המקור מבוטל.
total_mismatch422
Computed total differs from expected_total; nothing was issued.הסה"כ המחושב שונה מהצפוי — לא הופק.→ details.computed_total shows our figure (VAT from the business settings). Fix your figures or drop expected_total.
future_date422
Document date cannot be in the future.לא ניתן להפיק מסמך בתאריך עתידי.→ Use today (Israel time) or earlier.
date_before_last_document422
Document date is earlier than the last document of the same type.התאריך מוקדם מהמסמך האחרון מסוג זה.→ Israeli sequence rule: use details.last_document_date or later.
use_credit_note422
Accounting documents cannot be cancelled; issue a credit note (or a refund receipt) instead.מסמך חשבונאי לא מבוטל — מפיקים חשבונית זיכוי.→ POST /v1/documents with type=credit_note and based_on=this id (same items).
already_cancelled422
Document is already cancelled.המסמך כבר מבוטל.
linked_document_closed422
A delivery/return note that was already invoiced cannot be cancelled.תעודה שכבר חויבה לא ניתנת לביטול.→ Credit the invoice first.
rate_limited429 · retryable
Too many requests.יותר מדי בקשות.→ Respect Retry-After and X-RateLimit-* headers.
daily_limit_reached429
Daily document limit for this API key reached.הגעת למכסת המסמכים היומית של המפתח.→ Resets at midnight Israel time. Contact support to raise the limit.
document_generation_failed502 · retryable
The document could not be rendered; the sequence number was rolled back.הפקת המסמך נכשלה; המספר שוחרר.→ Safe to retry with the same Idempotency-Key.
engine_error502 · retryable
Document engine error.שגיאת מנוע.→ Retry with the same Idempotency-Key. If it persists contact support with request_id.
api_disabled503 · retryable
The API is temporarily disabled.ה-API מושבת זמנית.→ Retry later.
payload_too_large413
Request body exceeds 256KB.גוף הבקשה גדול מדי.→ Max 100 items, 1000-char notes.
internal_error500 · retryable
Unexpected error.שגיאה לא צפויה.→ Retry with the same Idempotency-Key; contact support with request_id.

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

---

# For AI agents

For AI agents — ChatInvoice API

Integration guide for AI agents

If you are an automated agent integrating a system with ChatInvoice, this page is the whole contract in the order you need it. Everything else is discoverable from the API itself.

01Discover before you act

GET /v1/me — read allowed_document_types, business.prices_include_vat, business.vat_rate, tax_authority_connected, auto_send, limits. Do not assume; read.

GET /v1/document-types — per type: requires_payments, allows_discount, based_on_types, based_on_required.

GET /v1/customers?q= — find an existing customer before creating one by name.

02Choose the document type

situationtypenotes

Price offer, nothing sold yetquotecancellable

Payment request before payment (e.g. bank transfer pending)proformaany legal type; not an accounting document

Sale completed, payment NOT yet received, business is not an exempt dealertax_invoicelater a receipt with based_on closes it

Sale completed AND paid, business is not an exempt dealertax_invoice_receiptpayments required, must equal total

Payment received, business IS an exempt dealer / NPOreceiptthe only accounting document they issue for income

Donation received (NPO)donation_receiptpayments required

Refund / correction of a tax invoicecredit_notebased_on required

Goods shipped / returneddelivery_note / return_noteno amounts due

If allowed_document_types does not contain the type you chose, choose again from the table — never override the business's legal type.

03Build the request

Send only the fields in the schema. Unknown fields fail with 400 validation_error.

Never send: a document number, a VAT rate, is_tax_exempt, an allocation number, a status, computed totals as fields. Never guess VAT — if you must verify a figure, use expected_total.

Prices: read business.prices_include_vat; set prices_include_vat explicitly if your prices differ from that default.

Payments: only on tax_invoice_receipt, receipt, donation_receipt; the sum must equal the total (compute it from the same items or use expected_total).

Date: omit it (today), or a past date not earlier than the last document of that type. Never a future date.

For an allocation number (invoice above ₪5,000 net, business connected): include customer.tax_id. The document is issued either way — read allocation.status.

Always set external_ref to your own id and Idempotency-Key to a value unique per logical document (e.g. <your-order-id>:invoice).

04Handle the response

201: persist id, number, view_url, pdf_url. Read delivery.status — if disabled/suppressed/no_recipient, the customer has NOT received anything; send view_url yourself if that is expected.

409 customer_identity_conflict: the tax id belongs to a differently-named customer. Prefer customer.id = details.existing_customer_id if it is the same entity; otherwise resend with customer.identity_confirmed: true.

422: a business rule. Nothing was issued. Fix per hint; e.g. legal_type_forbidden → pick from allowed_document_types; date_before_last_document → use details.last_document_date.

retryable: true (502/503/409 request_in_progress/429): retry with backoff using the same Idempotency-Key. Never change the key on retry.

402: stop and surface details.payment_url to the business owner.

05Do not

Do not cancel accounting documents — issue a credit_note with based_on.

Do not re-issue a document to “edit” it. Cancel/credit, then issue anew.

Do not create a new customer when GET /v1/customers?q= finds a match by tax id or exact name.

Do not exceed limits; honor RateLimit-* and Retry-After.

06Minimal happy path

GET  /v1/me                                   → allowed types, prices_include_vat, auto_send
GET  /v1/customers?q=515123456                → customer.id (or none)
POST /v1/documents  (Idempotency-Key: order-10021:invrec)
     { type: "tax_invoice_receipt", customer: {id}, items, payments, expected_total, external_ref }
201  → store id/number/view_url; check delivery.status and allocation.status

Machine-readable: openapi.json · llms-full.txt · GET /v1/errors.

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