CySo Invoicing

Create a job (a folder that groups a piece of work's invoices, quotations and receipts). Starts as open. Before calling: Check list_jobs for an existing job with a similar name; ask for the name. Confirm before creating. After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

create_job

Create a quotation for an EXISTING client (nothing is sent). Every item needs a price. The app's default deposit setting applies. Before calling: Re-fetch the client with list_customers and confirm WHICH client (use its id). Ask for the subject, then the items one by one (price from list_products or ask; quantity if missing), then "Any more items?". Ask about VAT, validity and notes only if needed. Show the full summary and ask "Is everything correct?". After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

create_quotation

Create a DRAFT service report (a record of work done at a client) for an EXISTING client — use list_customers. It gets its report number; nothing is sent. Lines are optional (a report can just describe the work); every line given needs a price. The client signs on site in the app, never here. Only works if the user has service reports switched on in the app. Before calling: Confirm the client (list_customers, use its id); ask for the subject and the work performed, the date, and any priced lines. Show the summary and ask "Is everything correct?". After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

create_service_report

Create a link the CLIENT can open to view/download the PDF of an invoice, quotation or receipt. The PDF is read from the user's own cloud storage each time it is opened (never stored by CySo); the link works for 7 days and the user can cancel it in the app. Set email_client=true to also e-mail the link to the client's address SAVED in the app (that also needs the key's send permission for that document type; you cannot choose the address). Otherwise give the link to the user so they can send it themselves. Before calling: Re-fetch the document; ask whether the user wants the link for themselves or e-mailed to the client's saved address. Ask for a yes. After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

create_share_link

Only for an account that keeps its data PRIVATE in the user's own storage, when a question failed because that storage could not be read or was too slow. After the user AGREES, keeps a temporary copy of the same data on CySo's server for 12 hours so questions work meanwhile; after 12 hours it is deleted. First call without confirmation_token: returns what will happen and a token. Call again with the token ONLY after the user says yes. Before calling: Only after a question failed because the user's own storage could not be read. Explain what it does and ask the user; call with the token only after they agree. After calling: Tell the user the copy is on until the time given and to open the app if needed, then retry their question. If unsure whether this is allowed, call get_capabilities. Do not assume.

enable_temporary_copy

Check what happened to a create/send/mark-paid/expense request made through this connector: waiting for approval in the app, approved and waiting for the app to run it, done (with the resulting number), rejected, or failed. Before calling: Use the action_id from the tool that made the request. After calling: Tell the user the outcome in one line (with the document number once done). If still waiting, say so — do not assume it happened. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_action_status

What this connection is allowed to do in CySo Invoicing right now, and how each action is approved (directly, by the user saying yes in this chat, or by the user tapping Approve in the app), what is switched off, and what is never possible. Call this whenever the user asks what you can do, or before offering an action you are not sure about. Before calling: Call it at the start of the conversation and before telling the user anything is not allowed. After calling: Say something is not allowed only if this says allowed:false. Offer what IS allowed instead. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_capabilities

Which CySo Invoicing account this connection belongs to: account id, company name, account e-mail, role, the API key's name and id, its permissions and the connection status. Call this whenever the user asks which account or key they are connected with. Always answer from this result — never from earlier conversations. Never returns keys or tokens. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_connection_info

One credit note in full: lines, VAT, amount, reason, the invoice it corrects, and for general credit where it was applied and what is left. Pass the credit note number or id. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_credit_note

The PDF of an invoice, quotation or receipt, read from the user's OWN connected cloud storage (Google Drive, Dropbox or OneDrive) where the app saved it, and attached here. PDFs are never generated by this connector: if the app has not saved that PDF to their storage, you are told so (they can open the document in the app to save it). Pass the document number or id. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_document_pdf

One invoice in full: line items, VAT, totals, payments and balance. Pass the invoice number (e.g. INV26001) or id. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_invoice

One job: status and every invoice, quotation and receipt attached to it, with totals. Pass the job name or id. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If it says not found, offer the closest names it gives. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_job

One quotation in full: line items, VAT and total. Pass the quotation number or id. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_quotation

One receipt in full: amount received, paid to date and balance left on its invoice at that payment, and whether it was a full or part payment. Pass the receipt number or id. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_receipt

One service report in full: work performed, line items, VAT, total, dates, status, whether the client signed it, and the linked invoice/receipt. Pass the report number (e.g. SR26001) or id. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_service_report

Business statistics, the same figures as the CySo Invoicing Dashboard: total invoiced, collected (paid), outstanding (unpaid), overdue, awaiting payment, quotation conversion and top clients, for a period. Drafts and cancelled (void) invoices are excluded; credit notes and part payments are applied. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_statistics

Active subscription alerts (upcoming renewal, subscription or trial ending, failed payment, just ended) and the recent notification history (also shown in the CySo Invoicing app and e-mailed by CySo's own daily check). Call this when the user asks whether anything needs attention on their subscription. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_subscription_alerts

The account's CySo Invoicing subscription from the billing system: plan, status, current period end, the day Pro actually stops (null while it renews), days remaining, next billing date and amount, currency, billing cycle, auto-renew, payment status and plan features. Unknown values are null — never guess them. No card details. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_subscription_info

Read-only help text for CySo Invoicing: which operations this connection may use, which of them need the user's approval, short how-to steps and example requests, and the plan's features. Contains CySo's own documentation only, no business data; changes nothing. Use it when the user asks what they can do or how to do something. Before calling: Call it when the user asks how to do something, or before a flow you are unsure of. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

get_user_guide

Create a DRAFT invoice from a client's UNBILLED items (all of them, or the item ids you give from list_charges) and mark them billed — the same as the client tab's "Create invoice". The invoice gets its number; nothing is sent. Before calling: Re-fetch the client's unbilled items with list_charges and confirm which ones. It takes the next invoice number for good — show the total and ask for a yes. After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

invoice_charges

Issue a CREDIT NOTE against an issued invoice — the legal way to correct it (the invoice itself is never changed). Credits the whole invoice, or only the line numbers you give (1 = first line, as in get_invoice). Needs a reason: cancelled, returned, overcharged, discount, error, goodwill, other. It gets its own number and cannot be changed once issued. Refused if it would credit more than is left on the invoice. Before calling: Re-fetch the invoice with get_invoice; ask the reason and whether it is the whole invoice or some lines; show the amount and ask "Is everything correct?". After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

issue_credit_note

A client's tab: billable items (labour, call-outs, materials) recorded to invoice later — description, date, quantity, price, line total, and whether each is still unbilled or already on an invoice. Filter by client and status. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_charges

List credit notes (number, date, client, the invoice it corrects or "general credit", amount, VAT, reason, status: draft, issued or void, and for general credit how much is still available), newest first. Filter by client, invoice or status. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_credit_notes

List or search clients: id, name, VAT number, whether an email is on file, and how much they owe. Contact details are not available to connectors. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If a result is marked match "close" or "possible", it is a suggestion: ask the user "Did you mean …?" and never pick it yourself. Once confirmed, keep using that id. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_customers

List recorded expenses (supplier, category, date, gross amount incl. VAT, VAT) — newest first — with the total for the selection. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_expenses

List invoices with number, client, dates, total, amount paid, balance still owed and status. Filter by status (draft, sent, paid, overdue, void, or unpaid = anything still owed), client, and issue-date range. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_invoices

List jobs (name, status: open, in_progress or done) with how many invoices, quotations and receipts are attached and their totals. Filter by status or name. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If a result is marked match "close" or "possible", it is a suggestion: ask the user "Did you mean …?" and never pick it yourself. Once confirmed, keep using that id. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_jobs

Search the product / parts catalogue: name, SKU, category, unit, sell price (before VAT), cost price, stock on hand and the low-stock level. Use it to price invoice and quotation lines exactly as the user does. low_stock=true lists only items at or below their low-stock level. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If a result is marked match "close" or "possible", it is a suggestion: ask the user "Did you mean …?" and never pick it yourself. Once confirmed, keep using that id. Prices are before VAT. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_products

List quotations with number, client, date, total and status (draft, sent, approved, rejected). Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_quotations

List payment receipts (number, date, client, invoice, amount received, whether it settled the invoice), newest first, with the total. Filter by client, invoice or date range. A receipt is created every time a payment is recorded on an invoice. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_receipts

List the repeating invoices (the originals a repeat is set on): client, how often (weekly, every 2 weeks, monthly, quarterly, every 6 months, yearly), state (active, paused until a date, or stopped) and the amount of the original. The exact next date is shown in the app. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_recurring_invoices

List service reports (number, client, service date, subject, total, status: draft, sent, paid, overdue or void, and the invoice made from it, if any), newest first. Filter by status, client and service-date range. A service report records work done at a client; it is not an invoice and is not counted as income. Before calling: Nothing — safe to call any time, without asking the user. After calling: Answer only from this result (see fetched_at). Fetch again before any change. If unsure whether this is allowed, call get_capabilities. Do not assume.

list_service_reports

Pause, resume, stop or change a REPEATING invoice (use list_recurring_invoices). pause needs until (YYYY-MM-DD, after today); change needs cycle (+ weekday for weekly/biweekly, day and month for yearly). Only FUTURE copies are affected; nothing already issued changes. To create a new repeating invoice, use create_invoice with repeat. Before calling: Re-fetch with list_recurring_invoices; confirm which repeating invoice and what should change (pause until, resume, stop, new cycle). Ask for a yes. After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

manage_recurring_invoice

Record a payment received on an issued invoice — this CREATES THE RECEIPT (its number is returned in get_action_status once the app has done it). Leave amount out for the full balance still owed; a smaller amount is a part payment. Cannot exceed the balance. Before calling: Re-fetch the invoice with get_invoice and tell the user what is still owed. Ask the amount (full balance or a part payment). Double-check: "Just to be sure: a payment of €X from <client> for invoice <no.>. Correct?". Flag a part payment; an overpayment is refused. After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

mark_invoice_paid

Mark a sent service report as PAID (the same as the app's "Mark paid" on the report). This records nothing as income and creates no receipt — for a payment against an invoice use mark_invoice_paid. Before calling: Re-fetch the report with get_service_report and confirm with the user it was paid. After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

mark_service_report_paid

Record the DEPOSIT the client agreed to on the quotation (the invoice's fixed deposit amount) as received — creates a deposit receipt, the same as the app's "Record deposit". For any other payment use mark_invoice_paid. Before calling: Re-fetch the invoice with get_invoice and show the agreed deposit. Double-check the amount and client with the user before recording. After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

record_deposit

Email an existing invoice (PDF attached) to the client's email address SAVED in the app. You cannot choose the address. A draft becomes sent. Before calling: Re-fetch the invoice with get_invoice; show the number, client and total; check the client has an email on file (list_customers hasEmail — the connector cannot choose or add one). Read the masked recipient in the summary to the user and ask whether it is right, then "Send it to the client now?". After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

send_invoice

E-mail a payment reminder (invoice PDF attached) for an OVERDUE invoice to the client's address SAVED in the app — the same as the app's "Send reminder". At most once every 7 days per invoice. You cannot choose the address. Before calling: Re-fetch the invoice with get_invoice (it must be overdue); show the number, client and amount owed. Ask before sending. After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

send_payment_reminder

Email an existing quotation (PDF attached) to the client's email address SAVED in the app. You cannot choose the address. Before calling: Re-fetch the quotation with get_quotation; show the number, client and total; check the client has an email on file. Ask "Send it to the client now?". After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

send_quotation

Email an existing receipt (PDF attached) to the client's email address SAVED in the app — the same as the app's "Email receipt" button. You cannot choose the address. Before calling: Re-fetch the receipt with get_receipt; show the number, client and amount; check the client has an email on file. Ask "Send it to the client now?". After calling: If the result says APPROVAL NEEDED, show the summary, ask "Is everything correct?" and call again with the confirmation_token only after a clear yes. When done, tell the user in one line what was done (and the total) and suggest the next step. If unsure whether this is allowed, call get_capabilities. Do not assume.

send_receipt