{
  "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.\n\nThe 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.\n\nGuides: 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"
          }
        }
      }
    }
  }
}