openapi: 3.1.0
info:
  title: ChatInvoice Public API
  version: '1.0'
  summary: >-
    Issue legally valid Israeli accounting documents (quotes, invoices, receipts, credit notes) for a ChatInvoice
    business from any external system.
  description: >-
    Base URL: `https://api.chat-invoice.co.il/v1`. Server-to-server only (no CORS). All money in ILS with 2 decimals;
    all dates `YYYY-MM-DD` in Asia/Jerusalem.


    The API sits in front of the same document engine the ChatInvoice chat and app use: sequence numbers, VAT (from the
    business settings), totals, the date↔number rule and the signed PDF are all computed by the engine — never by the
    caller.


    Guides: https://api.chat-invoice.co.il/docs (English) · https://api.chat-invoice.co.il/docs/he (Hebrew) · AI agents:
    https://api.chat-invoice.co.il/docs/agents
  contact:
    name: ChatInvoice support
    url: https://chat-invoice.co.il
    email: support@chat-invoice.co.il
servers:
  - url: https://api.chat-invoice.co.il/v1
security:
  - bearerAuth: []
tags:
  - name: Business
  - name: Documents
  - name: Customers
paths:
  /me:
    get:
      tags:
        - Business
      operationId: getMe
      summary: Who am I — business profile, allowed document types, limits
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                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'
        '401':
          description: '`unauthorized`, `key_revoked`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Missing or invalid API key.
                  message_he: מפתח API חסר או לא תקין.
                  hint: >-
                    Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections →
                    API.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#unauthorized
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '402':
          description: '`subscription_required`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: subscription_required
                  message: The business has no active paid subscription.
                  message_he: לעסק אין מנוי פעיל.
                  hint: The API is available to paying subscribers. `details.payment_url` opens the subscription page.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#subscription_required
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '403':
          description: '`external_provider_not_supported`, `business_archived`, `insufficient_scope`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: external_provider_not_supported
                  message: >-
                    This business issues documents through an external accounting provider; the API supports native
                    businesses only.
                  message_he: העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.
                  hint: Not available for this business.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#external_provider_not_supported
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '429':
          description: '`rate_limited`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: Too many requests.
                  message_he: יותר מדי בקשות.
                  hint: Respect Retry-After and X-RateLimit-* headers.
                  retryable: true
                  doc_url: https://api.chat-invoice.co.il/docs/errors#rate_limited
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
  /document-types:
    get:
      tags:
        - Business
      operationId: listDocumentTypes
      summary: Document types this business may issue
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                data:
                  - type: tax_invoice_receipt
                    name: Tax invoice receipt
                    name_he: חשבונית מס/קבלה
                    requires_payments: true
                    allows_discount: true
                    based_on_types:
                      - quote
                      - order
                      - delivery_note
                      - proforma
                    based_on_required: false
        '401':
          description: '`unauthorized`, `key_revoked`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Missing or invalid API key.
                  message_he: מפתח API חסר או לא תקין.
                  hint: >-
                    Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections →
                    API.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#unauthorized
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '402':
          description: '`subscription_required`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: subscription_required
                  message: The business has no active paid subscription.
                  message_he: לעסק אין מנוי פעיל.
                  hint: The API is available to paying subscribers. `details.payment_url` opens the subscription page.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#subscription_required
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '403':
          description: '`external_provider_not_supported`, `business_archived`, `insufficient_scope`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: external_provider_not_supported
                  message: >-
                    This business issues documents through an external accounting provider; the API supports native
                    businesses only.
                  message_he: העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.
                  hint: Not available for this business.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#external_provider_not_supported
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '429':
          description: '`rate_limited`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: Too many requests.
                  message_he: יותר מדי בקשות.
                  hint: Respect Retry-After and X-RateLimit-* headers.
                  retryable: true
                  doc_url: https://api.chat-invoice.co.il/docs/errors#rate_limited
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
  /errors:
    get:
      tags:
        - Business
      operationId: listErrors
      summary: Machine-readable error catalog
      security: []
      responses:
        '200':
          description: OK
  /documents:
    post:
      tags:
        - Documents
      operationId: createDocument
      summary: Issue a document
      description: >-
        Requires the `Idempotency-Key` header. Retrying with the same key returns the same document instead of issuing
        twice.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            maxLength: 128
          description: >-
            Unique per logical document (e.g. your order id). Same key + same body → replay (header
            `Idempotent-Replayed: true`). Same key + different body → 409.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
            examples:
              quote:
                summary: Quote (new customer)
                value:
                  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
              tax_invoice_receipt:
                summary: Tax invoice receipt (paid)
                value:
                  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
              credit_note:
                summary: Credit note against an invoice
                value:
                  type: credit_note
                  based_on: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  customer:
                    id: 3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60
                  items:
                    - description: זיכוי — שירות חודשי ספטמבר
                      quantity: 1
                      unit_price: 590
      responses:
        '201':
          description: Issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
              example:
                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'
        '400':
          description: '`invalid_json`, `validation_error`, `missing_idempotency_key`, `invalid_customer_tax_id`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: invalid_json
                  message: Request body is not valid JSON.
                  message_he: גוף הבקשה אינו JSON תקין.
                  hint: 'Send `Content-Type: application/json`.'
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#invalid_json
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '401':
          description: '`unauthorized`, `key_revoked`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Missing or invalid API key.
                  message_he: מפתח API חסר או לא תקין.
                  hint: >-
                    Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections →
                    API.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#unauthorized
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '402':
          description: '`subscription_required`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: subscription_required
                  message: The business has no active paid subscription.
                  message_he: לעסק אין מנוי פעיל.
                  hint: The API is available to paying subscribers. `details.payment_url` opens the subscription page.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#subscription_required
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '403':
          description: >-
            `external_provider_not_supported`, `business_archived`, `insufficient_scope`,
            `issuing_blocked_expenses_only`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: external_provider_not_supported
                  message: >-
                    This business issues documents through an external accounting provider; the API supports native
                    businesses only.
                  message_he: העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.
                  hint: Not available for this business.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#external_provider_not_supported
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '404':
          description: '`customer_not_found`, `based_on_not_found`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: customer_not_found
                  message: customer.id does not belong to this business.
                  message_he: הלקוח לא נמצא בעסק.
                  hint: Use GET /v1/customers?q= to find the id, or send customer.name instead.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#customer_not_found
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '409':
          description: '`idempotency_key_reused`, `request_in_progress`, `customer_identity_conflict`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: idempotency_key_reused
                  message: Idempotency-Key was already used with a different request body.
                  message_he: מפתח ה-Idempotency כבר שימש לבקשה אחרת.
                  hint: Use a new key for a new document.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#idempotency_key_reused
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '413':
          description: '`payload_too_large`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: payload_too_large
                  message: Request body exceeds 256KB.
                  message_he: גוף הבקשה גדול מדי.
                  hint: Max 100 items, 1000-char notes.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#payload_too_large
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '422':
          description: >-
            `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`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                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
        '429':
          description: '`rate_limited`, `daily_limit_reached`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: Too many requests.
                  message_he: יותר מדי בקשות.
                  hint: Respect Retry-After and X-RateLimit-* headers.
                  retryable: true
                  doc_url: https://api.chat-invoice.co.il/docs/errors#rate_limited
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '502':
          description: '`document_generation_failed`, `engine_error`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: document_generation_failed
                  message: The document could not be rendered; the sequence number was rolled back.
                  message_he: הפקת המסמך נכשלה; המספר שוחרר.
                  hint: Safe to retry with the same Idempotency-Key.
                  retryable: true
                  doc_url: https://api.chat-invoice.co.il/docs/errors#document_generation_failed
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
    get:
      tags:
        - Documents
      operationId: listDocuments
      summary: List documents
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - quote
              - order
              - delivery_note
              - return_note
              - proforma
              - tax_invoice
              - tax_invoice_receipt
              - receipt
              - credit_note
              - donation_receipt
        - name: from
          in: query
          schema:
            type: string
            format: date
          description: doc date ≥
        - name: to
          in: query
          schema:
            type: string
            format: date
          description: doc date ≤
        - name: external_ref
          in: query
          schema:
            type: string
          description: Your reference as sent on creation
        - name: include_cancelled
          in: query
          schema:
            type: boolean
            default: false
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          schema:
            type: string
          description: '`next_cursor` from the previous page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
                  next_cursor:
                    type:
                      - string
                      - 'null'
        '401':
          description: '`unauthorized`, `key_revoked`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Missing or invalid API key.
                  message_he: מפתח API חסר או לא תקין.
                  hint: >-
                    Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections →
                    API.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#unauthorized
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '402':
          description: '`subscription_required`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: subscription_required
                  message: The business has no active paid subscription.
                  message_he: לעסק אין מנוי פעיל.
                  hint: The API is available to paying subscribers. `details.payment_url` opens the subscription page.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#subscription_required
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '403':
          description: '`external_provider_not_supported`, `business_archived`, `insufficient_scope`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: external_provider_not_supported
                  message: >-
                    This business issues documents through an external accounting provider; the API supports native
                    businesses only.
                  message_he: העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.
                  hint: Not available for this business.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#external_provider_not_supported
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '429':
          description: '`rate_limited`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: Too many requests.
                  message_he: יותר מדי בקשות.
                  hint: Respect Retry-After and X-RateLimit-* headers.
                  retryable: true
                  doc_url: https://api.chat-invoice.co.il/docs/errors#rate_limited
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
  /documents/{id}:
    get:
      tags:
        - Documents
      operationId: getDocument
      summary: Get one document with items and payments
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          description: '`unauthorized`, `key_revoked`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Missing or invalid API key.
                  message_he: מפתח API חסר או לא תקין.
                  hint: >-
                    Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections →
                    API.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#unauthorized
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '402':
          description: '`subscription_required`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: subscription_required
                  message: The business has no active paid subscription.
                  message_he: לעסק אין מנוי פעיל.
                  hint: The API is available to paying subscribers. `details.payment_url` opens the subscription page.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#subscription_required
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '403':
          description: '`external_provider_not_supported`, `business_archived`, `insufficient_scope`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: external_provider_not_supported
                  message: >-
                    This business issues documents through an external accounting provider; the API supports native
                    businesses only.
                  message_he: העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.
                  hint: Not available for this business.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#external_provider_not_supported
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '404':
          description: '`not_found`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Resource not found.
                  message_he: לא נמצא.
                  hint: Ids are scoped to the business of the API key.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#not_found
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '429':
          description: '`rate_limited`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: Too many requests.
                  message_he: יותר מדי בקשות.
                  hint: Respect Retry-After and X-RateLimit-* headers.
                  retryable: true
                  doc_url: https://api.chat-invoice.co.il/docs/errors#rate_limited
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
  /documents/{id}/cancel:
    post:
      tags:
        - Documents
      operationId: cancelDocument
      summary: Cancel a non-accounting document
      description: >-
        Quotes, orders, delivery/return notes and proforma invoices only. Accounting documents are reversed with a
        `credit_note` (422 `use_credit_note`).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelDocumentRequest'
      responses:
        '200':
          description: Cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          description: '`unauthorized`, `key_revoked`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Missing or invalid API key.
                  message_he: מפתח API חסר או לא תקין.
                  hint: >-
                    Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections →
                    API.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#unauthorized
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '402':
          description: '`subscription_required`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: subscription_required
                  message: The business has no active paid subscription.
                  message_he: לעסק אין מנוי פעיל.
                  hint: The API is available to paying subscribers. `details.payment_url` opens the subscription page.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#subscription_required
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '403':
          description: '`external_provider_not_supported`, `business_archived`, `insufficient_scope`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: external_provider_not_supported
                  message: >-
                    This business issues documents through an external accounting provider; the API supports native
                    businesses only.
                  message_he: העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.
                  hint: Not available for this business.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#external_provider_not_supported
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '404':
          description: '`not_found`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Resource not found.
                  message_he: לא נמצא.
                  hint: Ids are scoped to the business of the API key.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#not_found
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '422':
          description: '`already_cancelled`, `use_credit_note`, `linked_document_closed`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: already_cancelled
                  message: Document is already cancelled.
                  message_he: המסמך כבר מבוטל.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#already_cancelled
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '429':
          description: '`rate_limited`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: Too many requests.
                  message_he: יותר מדי בקשות.
                  hint: Respect Retry-After and X-RateLimit-* headers.
                  retryable: true
                  doc_url: https://api.chat-invoice.co.il/docs/errors#rate_limited
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
  /customers:
    get:
      tags:
        - Customers
      operationId: searchCustomers
      summary: Search customers by name or tax id
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 50
            default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                data:
                  - id: 3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60
                    name: ישראל ישראלי בע"מ
                    tax_id: '515123456'
                    legal_type: hevra_baam
                    email: billing@example.co.il
                    phone: '0501234567'
                    city: תל אביב
        '401':
          description: '`unauthorized`, `key_revoked`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Missing or invalid API key.
                  message_he: מפתח API חסר או לא תקין.
                  hint: >-
                    Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections →
                    API.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#unauthorized
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '402':
          description: '`subscription_required`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: subscription_required
                  message: The business has no active paid subscription.
                  message_he: לעסק אין מנוי פעיל.
                  hint: The API is available to paying subscribers. `details.payment_url` opens the subscription page.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#subscription_required
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '403':
          description: '`external_provider_not_supported`, `business_archived`, `insufficient_scope`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: external_provider_not_supported
                  message: >-
                    This business issues documents through an external accounting provider; the API supports native
                    businesses only.
                  message_he: העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.
                  hint: Not available for this business.
                  retryable: false
                  doc_url: https://api.chat-invoice.co.il/docs/errors#external_provider_not_supported
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
        '429':
          description: '`rate_limited`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: Too many requests.
                  message_he: יותר מדי בקשות.
                  hint: Respect Retry-After and X-RateLimit-* headers.
                  retryable: true
                  doc_url: https://api.chat-invoice.co.il/docs/errors#rate_limited
                request_id: 5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ci_live_…
      description: >-
        API key created by the business owner in the ChatInvoice app (Settings → Connections → API). Keep it
        server-side.
  schemas:
    CreateDocumentRequest:
      type: object
      additionalProperties: false
      required:
        - type
        - customer
        - items
      properties:
        type:
          type: string
          enum:
            - quote
            - order
            - delivery_note
            - return_note
            - proforma
            - tax_invoice
            - tax_invoice_receipt
            - receipt
            - credit_note
            - donation_receipt
        date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: >-
            Document date. Defaults to today (Israel). Cannot be in the future or earlier than the last document of the
            same type.
        due_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Payment due date (tax_invoice / proforma only). Defaults to the business payment terms.
        customer:
          type: object
          additionalProperties: false
          description: >-
            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.
          properties:
            id:
              type: string
              format: uuid
              description: Existing customer id (from GET /v1/customers)
            name:
              type: string
              minLength: 2
              maxLength: 120
            tax_id:
              type: string
              pattern: ^\d{5,9}$
              description: >-
                ח.פ / ע.מ / ת.ז — up to 9 digits, Israeli checksum validated. Required for a tax-authority allocation
                number.
            legal_type:
              type: string
              enum:
                - hevra_baam
                - osek_murshe
                - osek_patur
                - amuta
                - private
            email:
              type: string
              format: email
              maxLength: 254
            phone:
              type: string
              pattern: ^\+?[0-9\-\s]{7,20}$
            address:
              type: string
              maxLength: 200
            city:
              type: string
              maxLength: 80
            identity_confirmed:
              type: boolean
              description: >-
                Send `true` only after a 409 customer_identity_conflict, to open a separate card that shares the same
                tax_id (e.g. a branch).
          anyOf:
            - required:
                - id
            - required:
                - name
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: object
            additionalProperties: false
            required:
              - description
              - quantity
              - unit_price
            properties:
              description:
                type: string
                minLength: 1
                maxLength: 200
              quantity:
                type: number
                exclusiveMinimum: 0
                maximum: 1000000
                multipleOf: 0.0001
              unit_price:
                type: number
                minimum: 0
                maximum: 100000000
                multipleOf: 0.01
                description: Per unit, in ILS. Net or gross according to `prices_include_vat`.
              sku:
                type: string
                maxLength: 64
        prices_include_vat:
          type: boolean
          description: Whether `unit_price` already includes VAT. Defaults to the business setting.
        discount:
          type: object
          additionalProperties: false
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - percent
                - amount
            value:
              type: number
              exclusiveMinimum: 0
              maximum: 100000000
          description: Document-level discount. Not allowed on receipts.
        payments:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: object
            additionalProperties: false
            required:
              - method
              - amount
            properties:
              method:
                type: string
                enum:
                  - cash
                  - check
                  - credit_card
                  - bank_transfer
                  - paypal
                  - bit
                  - apple_pay
                  - google_pay
                  - paybox
              amount:
                type: number
                minimum: 0
                maximum: 100000000
                multipleOf: 0.01
                exclusiveMinimum: 0
              date:
                type: string
                pattern: ^\d{4}-\d{2}-\d{2}$
                description: YYYY-MM-DD (Asia/Jerusalem)
              reference:
                type: string
                maxLength: 64
                description: Transfer / transaction reference
              check_number:
                type: string
                maxLength: 20
              check_date:
                type: string
                pattern: ^\d{4}-\d{2}-\d{2}$
                description: YYYY-MM-DD (Asia/Jerusalem)
              bank_code:
                type: integer
                minimum: 1
                maximum: 99
              branch:
                type: string
                maxLength: 10
              account:
                type: string
                maxLength: 20
              card_last_digits:
                type: string
                pattern: ^\d{4}$
              card_type:
                type: string
                maxLength: 20
          description: >-
            Required for receipt / tax_invoice_receipt / donation_receipt; forbidden otherwise. Must sum to the document
            total.
        based_on:
          type: string
          format: uuid
          description: >-
            Source document id (credit_note: required, a tax_invoice / tax_invoice_receipt; receipt: a tax_invoice to
            close).
        title:
          type: string
          maxLength: 120
          description: Short header printed on the document (e.g. project name)
        notes:
          type: string
          maxLength: 1000
        expected_total:
          type: number
          minimum: 0
          maximum: 100000000
          multipleOf: 0.01
          description: >-
            Optional safety check: if our computed total differs by more than 0.01 the document is NOT issued (422
            total_mismatch).
        send:
          type: boolean
          default: true
          description: '`false` suppresses the business auto-send for this document.'
        external_ref:
          type: string
          maxLength: 64
          description: Your own reference (order id). Echoed back and searchable in GET /v1/documents.
    CancelDocumentRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          maxLength: 200
    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
        public_id:
          type: string
        type:
          type: string
          enum:
            - quote
            - order
            - delivery_note
            - return_note
            - proforma
            - tax_invoice
            - tax_invoice_receipt
            - receipt
            - credit_note
            - donation_receipt
        number:
          type: integer
        status:
          type: string
          enum:
            - open
            - closed
            - cancelled
        date:
          type: string
          format: date
        due_date:
          type:
            - string
            - 'null'
          format: date
        external_ref:
          type:
            - string
            - 'null'
        customer:
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
            name:
              type:
                - string
                - 'null'
            tax_id:
              type:
                - string
                - 'null'
        totals:
          type: object
          properties:
            subtotal:
              type: number
            discount:
              type: number
            vat:
              type: number
            vat_rate:
              type: number
            total:
              type: number
            paid:
              type: number
            currency:
              type: string
              const: ILS
        allocation_number:
          type:
            - string
            - 'null'
        allocation:
          type: object
          description: Only on creation responses.
          properties:
            status:
              type: string
              enum:
                - not_required
                - issued
                - skipped_customer_tax_id_missing
                - skipped_business_tax_id_missing
                - failed
            number:
              type:
                - string
                - 'null'
            reason:
              type:
                - string
                - 'null'
        delivery:
          type: object
          description: Only on creation responses. Auto-send to the end customer per the business settings.
          properties:
            status:
              type: string
              enum:
                - queued
                - deferred_quiet_hours
                - disabled
                - suppressed
                - no_recipient
                - send_failed
            channel:
              type:
                - string
                - 'null'
            scheduled_for:
              type:
                - string
                - 'null'
              format: date-time
        view_url:
          type: string
          format: uri
        pdf_url:
          type: string
          format: uri
        based_on:
          type:
            - string
            - 'null'
          format: uuid
        cancelled_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        items:
          type: array
          description: Only on GET /v1/documents/{id}.
          items:
            type: object
            properties:
              description:
                type: string
              quantity:
                type: number
              unit_price:
                type: number
              line_total:
                type: number
              sku:
                type:
                  - string
                  - 'null'
        payments:
          type: array
          description: Only on GET /v1/documents/{id}.
          items:
            type: object
            properties:
              method:
                type: string
              amount:
                type: number
              date:
                type: string
                format: date
              reference:
                type:
                  - string
                  - 'null'
    Error:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          type: object
          required:
            - code
            - message
            - retryable
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - key_revoked
                - subscription_required
                - business_archived
                - business_profile_incomplete
                - external_provider_not_supported
                - issuing_blocked_expenses_only
                - insufficient_scope
                - not_found
                - customer_not_found
                - based_on_not_found
                - invalid_json
                - validation_error
                - missing_idempotency_key
                - invalid_customer_tax_id
                - idempotency_key_reused
                - request_in_progress
                - customer_identity_conflict
                - 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
                - use_credit_note
                - already_cancelled
                - linked_document_closed
                - rate_limited
                - daily_limit_reached
                - document_generation_failed
                - engine_error
                - api_disabled
                - payload_too_large
                - internal_error
            message:
              type: string
            message_he:
              type: string
            hint:
              type: string
            retryable:
              type: boolean
            doc_url:
              type: string
              format: uri
            details:
              type: object
              additionalProperties: true
        request_id:
          type: string