Integration guide for AI agents

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

01Discover before you act

1. GET /v1/me — read allowed_document_types, business.prices_include_vat, business.vat_rate, tax_authority_connected, auto_send, limits. Do not assume; read.
2. GET /v1/document-types — per type: requires_payments, allows_discount, based_on_types, based_on_required.
3. GET /v1/customers?q= — find an existing customer before creating one by name.

02Choose the document type

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

03Build the request

• Send only the fields in the schema. Unknown fields fail with 400 validation_error.
• Never send: a document number, a VAT rate, is_tax_exempt, an allocation number, a status, computed totals as fields. Never guess VAT — if you must verify a figure, use expected_total.
• Prices: read business.prices_include_vat; set prices_include_vat explicitly if your prices differ from that default.
• Payments: only on tax_invoice_receipt, receipt, donation_receipt; the sum must equal the total (compute it from the same items or use expected_total).
• Date: omit it (today), or a past date not earlier than the last document of that type. Never a future date.
• For an allocation number (invoice above ₪5,000 net, business connected): include customer.tax_id. The document is issued either way — read allocation.status.
• Always set external_ref to your own id and Idempotency-Key to a value unique per logical document (e.g. <your-order-id>:invoice).

04Handle the response

• 201: persist id, number, view_url, pdf_url. Read delivery.status — if disabled/suppressed/no_recipient, the customer has NOT received anything; send view_url yourself if that is expected.
• 409 customer_identity_conflict: the tax id belongs to a differently-named customer. Prefer customer.id = details.existing_customer_id if it is the same entity; otherwise resend with customer.identity_confirmed: true.
• 422: a business rule. Nothing was issued. Fix per hint; e.g. legal_type_forbidden → pick from allowed_document_types; date_before_last_document → use details.last_document_date.
• retryable: true (502/503/409 request_in_progress/429): retry with backoff using the same Idempotency-Key. Never change the key on retry.
• 402: stop and surface details.payment_url to the business owner.

05Do not

• Do not cancel accounting documents — issue a credit_note with based_on.
• Do not re-issue a document to “edit” it. Cancel/credit, then issue anew.
• Do not create a new customer when GET /v1/customers?q= finds a match by tax id or exact name.
• Do not exceed limits; honor RateLimit-* and Retry-After.

06Minimal happy path

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

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