Duodeal API Reference

Duodeal API — reference

🔄 Are these skills current? They are a copy taken from the public repo — there is no git remote behind them and nothing refreshes them on its own, so an install silently stays on the version of the day it was made. Read the line Skills Duodeal : mises à jour le … in DUODEAL-CONTEXT.md (project root): absent, or more than 7 days old → offer the refresh in one sentence before working. Procedure: ../duodeal-onboarding/references/updating-skills.md. Ask once per session; if the user declines, work with what is installed and drop it.

Operational reference for the Duodeal REST API, compiled from the official OpenAPI spec (~80 operations) + the rules learned in the field. What follows describes the server: the official Duodeal MCP connector covers only a subset of it.

Before naming any tool, check it against references/connector-tools.md — that file is authoritative on tool names and argument names. There is no generic api_call tool: an endpoint with no connector tool is reached by a direct REST call with X-API-KEY only if a key is already configured in the environment, otherwise through the Duodeal interface — and you say which route you took.

Fundamentals

• Base URL: https://api.duodeal.app/api (override: env DUODEAL_BASE_URL)
• Auth: header X-API-KEY: <uuid> — the RAW UUID, never a Bearer prefix
• Content-Type: application/json for every POST/PUT
• IDs: integers for resources; UUID v7 for public links (deal uid, quotation uuid, pins)
• Connection: know which tenant you are acting on before the first write, and state it out loud (connector: get_current_user returns the acting user + its company, then get_company(id) for the company detail). Never display or log a key

Payload conventions (valid everywhere)

• Nested refs: {"entity": {"id": N}} — never entity_id
• ISO dates YYYY-MM-DD; JSON booleans; prices as raw numbers
• VAT rate = decimal 0–1 (0.20 = 20%, 0.055 = 5.5%) — out of range → 400
• HTML accepted in description, title, HtmlSimple/RichText custom fields (server-sanitized)
• ⚠️ Never send a partial object where the server replaces the whole one: customFields on PUT /quotations/{id} replaces the entire dict, same trap with blocks (V2) and with a block's data (merge is shallow at root). Rule: read, merge in memory, send complete (connector: get_quotation / get_quotation_block before update_quotation / update_quotation_block; for a long text value use the targeted replace_quotation_custom_field / replace_quotation_block_text instead of resending everything). Nothing re-reads for you.

Inventory (overview)

The Connector tools column lists the tools that really exist. When a cell says none, the operation is impossible through the connector: say it, then take the exit given in the cell.

Tool names, argument names and the workaround for every impossible operation: read references/connector-tools.md — it also lists the tools people expect but that do not exist (api_call, get_links, clone_deal, clone_quotation, ensure_template, create_tax, create_unity, create_user, send_quotation, most delete_*). If a tool is not in that file, it does not exist: do not guess a name. Field-by-field detail (Req/Opt/Resp/traps per endpoint): read references/endpoints.md. Recurring errors, deletion rules, media, logos: read references/gotchas.md.

Filters and search

• Filters (REST): filters[<field>][<op>]=<value> — op ∈ eq|neq|contains|startsWith|endsWith|gt|gte|lt|lte|like|in. Relational fields (customerCompany.name) and custom fields (customFields.<key>) are supported. The connector has no generic filters argument: it exposes named ones (search, customer_id, status_id, owner_id, date_from/date_to, min_amount/max_amount, sort_by/sort_order) — for anything they do not cover, go through REST or filter the result yourself.
• Full-text search: ?search= on Deals & Quotations (weighted PostgreSQL FR/EN: name/number on top, then contact/customer) — connector: the search argument of list_deals / list_quotations.
• Pagination: page + itemsPerPage on REST, page + limit on the connector (default 10). Responses are sometimes [...], sometimes {data: [...], meta: {currentPage, perPage, pages, total}} — read meta.total / meta.pages and loop over page yourself: there is no "fetch everything" flag, and a truncated list read as complete is how a deal goes missing.

Public endpoints (no key)

GET /deals/uuid/{uuid}, GET /deals/custom-fields/{uuid}, GET /deals/pdf/{uuid}, GET /quotations/uuid/{quoteUuid}, GET /quotations/custom-fields/{quoteUuid}, GET /pins/quotation/{quotationUuid}.

Link vocabulary (never confuse these)

When a quote is delivered: always give both links (customer + edit). There is no get_links tool — build them by hand: get_deal(id) gives the deal uid (customer link) and the deal id, get_quotation(id) gives the quotation id (edit link). A share link can only be read from shareLinks in get_quotation: the connector cannot create one, so if none exists, deliver the customer link and say why.

Reflexes

1. Get the tenant's own ids before writing a single line: ids vary per tenant, never reuse those of another account (connector: list_taxes / list_unities; every line, including title and subtotal, needs a tax_id).
2. Never create a duplicate setup record: list first, match, create only what is missing (connector: list_price_categories → create_price_category). Taxes, unities, deal/quotation statuses and templates have no create tool at all — create them in the Duodeal interface (Settings), re-list to pick up the new ids, and tell the user that step was theirs.
3. A deal with no quotation does not appear in the list: make sure a quotation exists right after creating the deal (REST POST /deals carries createQuotation: true; the connector has no such argument, so follow create_deal with create_quotation(deal_id=…)).
4. A bare POST /quotations → 500: the first quotation is born with the deal. For a 2nd quotation on the same deal there is no clone tool: create_quotation(deal_id=…) then rebuild it (add_quotation_lines, add_quotation_block + update_quotation_block per block), or clone in the app and read the result back with get_quotation.
5. Writes: test/demo account only, never a real client tenant without an explicit request.
6. On an unexplained error: read the tool's own error message first, then references/gotchas.md. A 403 on a resource you know exists means the wrong tenant, not a rate limit — re-check with get_current_user.
7. When an operation has no connector tool (set a quotation primary, flag a template, builderVersion, deal language/currency, delete a media, send the quote by email, hard delete): say it plainly, then take the exit — a direct REST call with X-API-KEY only if a key is already configured in the environment, otherwise hand the step to the user in the Duodeal interface, click by click, and record it as still to do. Never ask for a key in the chat, and never deliver a quote as finished when a step you could not do is still pending.