erp/.claude/skills/dolibarr-sandbox-write/SKILL.md

name, description, requires

name	description	requires
dolibarr-sandbox-write	WRITE operations against the Arcodange Dolibarr SANDBOX (erp-sandbox.arcodange.lab) — the rehearsal environment where an AI agent records thirdparties, invoices and payments before any change is promoted to prod. Create client/supplier fiches (auto-coded), update an existing fiche's dossier (allowlisted non-ledger fields with a before/after read-back diff), add contacts idempotently (dedupe by email then name), customer + supplier invoices with product/service lines and the supplier's own reference, validate them, and record règlements (payments). Every create is IDEMPOTENT (erp#44): before any POST it dedupes against the target (thirdparty by exact name, supplier invoice by socid+ref_supplier, customer invoice by socid+date+total+line fingerprint, payment by invoice+amount+ normalized transaction id; credit notes excepted, a follow-up), so replaying a manifest — even one that failed mid-run — is a no-op, never a duplicate. Also attaches source documents (the supplier's PDF) onto an invoice's GED (erp#43): upload via the Documents API, idempotent by (object, filename, sha256) — re-attach is a no-op, same name + different content aborts. Every write goes through dol-write.sh, which REFUSES any host that is not the sandbox — the structural guarantee (ADR-0003) that this skill can never mutate production. Use when the user asks to "create a thirdparty / supplier / client fiche", "compléter / mettre à jour la fiche client", "add a contact to a thirdparty", "saisir une facture", "record an invoice with lines", "enregistrer un règlement / paiement", "attacher la pièce / le justificatif / le PDF à la facture", or to rehearse a write before promoting it to prod. SKIP for production writes (prod stays read-only via the `dolibarr` skill's `ai_agent` key; promotion is a separate, human-gated replay). Depends on the write-scoped `ai_agent_sandbox` Dolibarr user + its API key.	bins auth bash curl python3 .env with DOLIBARR_SANDBOX_URL + DOLIBARR_SANDBOX_API_KEY (mode 600, gitignored)

dolibarr-sandbox-write

Write-capable companion to the read-only dolibarr* skills, scoped to the sandbox. It exists so an AI agent can rehearse bookkeeping writes against a faithful copy of prod (see ADR-0003 + the ops/sandbox/ seed tooling), then a human promotes the reviewed change to prod.

The safety model (read this first)

• Host guard. scripts/dol-write.sh reads DOLIBARR_SANDBOX_URL from .env and refuses to send any request unless it matches erp-sandbox.arcodange.lab. Point it at erp.arcodange.lab (prod) and it exits non-zero before the request. This is the structural reason the skill cannot write prod.
• Credential scope. The key is ai_agent_sandbox's — valid only on the sandbox host, with create+read rights on thirdparties / invoices / supplier invoices / products / contacts (+ societe client voir). Prod's ai_agent key is read-only and lives in a different skill's .env.
• Resettable. Anything written here is wiped by ops/sandbox/sandbox-lifecycle.sh refresh-from-prod, so mistakes cost a reset, not data.
• Promotion to prod is gated, not automatic. Rehearse here → review the change-set (promote-plan.sh) → replay it on prod (promote-apply.sh --target prod). The prod write key is supplied via the environment at apply time (DOLIBARR_PROD_WRITE_KEY), never stored in any .env, and dol-prod-write.sh refuses every prod write unless ARCO_PROMOTE_CONFIRM=I-UNDERSTAND-THIS-WRITES-PROD. See "Promote to prod" below.

Setup

Create .env (mode 600, gitignored) next to scripts/:

cd .claude/skills/dolibarr-sandbox-write
umask 077
{ echo "DOLIBARR_SANDBOX_URL=https://erp-sandbox.arcodange.lab"
  printf 'DOLIBARR_SANDBOX_API_KEY=%s\n' "$(cat /path/to/.ai_agent_sandbox.key)"; } > .env

The key is produced by the Playwright provisioner in the repo's test/ (provisionSandbox.ts → .ai_agent_sandbox.key). Verify: scripts/dol-write.sh GET /status should return HTTP 200 with "environment":"non-production".

Workflows

Each script reads a JSON object on stdin (or a file path — or inline JSON — as $1; thirdparty-update.sh also takes <socid> first) and emits ids as JSON.

1 · Thirdparty (fiche client/fournisseur) — scripts/thirdparty-create.sh

echo '{"name":"KissMetrics","role":"client","tva_intra":"US.."}' | scripts/thirdparty-create.sh
echo '{"name":"OVH","role":"supplier","siret":"..."}'            | scripts/thirdparty-create.sh

role: client | supplier | both. Codes auto-assign from the mask (CL{0000} / FO{0000}) via the -1 sentinel; pass client_code/supplier_code to override. Optional: country_id (default 1=FR), siret, tva_intra, address, zip, town, email, phone, idprof1.

Idempotent (erp#44): dedupe by exact name. Before any POST the name is looked up on the target with the same semantics as promote's #thirdparty:name= lookup: one match whose roles cover the requested role → {"id": <existing>, "deduped": true}, no write; 2+ matches abort (ambiguous — never guess); a match missing the requested role aborts too (refuse-never-repair: reusing a client fiche as a supplier would skip the code mask and hide a data problem). Otherwise it creates and emits {"id": <new>, "deduped": false}.

2 · Invoice (facture) — scripts/invoice-create.sh

echo '{"socid":42,"kind":"customer","validate":true,
       "lines":[{"desc":"Conseil","qty":2,"price_ht":500,"tva":20,"type":"service"},
                {"desc":"Licence","qty":1,"price_ht":100,"tva":20,"type":"product"}]}' \
  | scripts/invoice-create.sh
# supplier invoice carrying the supplier's own reference:
echo '{"socid":7,"kind":"supplier","ref_supplier":"INV-2026-042","validate":true,
       "lines":[{"desc":"Hosting","qty":1,"price_ht":80,"tva":20,"type":"service"}]}' \
  | scripts/invoice-create.sh

kind: customer (/invoices) | supplier (/supplierinvoices). Lines carry desc, qty, price_ht, tva, type (product|service) and optional product_id (fk_product) to link a catalogue product. Totals + TVA are computed by Dolibarr. validate:true turns the draft (PROV…) into a final numbered invoice; omit it to leave a draft. Emits {id, ref, ref_supplier, total_ht, total_ttc, statut, deduped}.

Idempotent (erp#44). Before any POST the thirdparty's invoices of the same kind are listed and deduped:

• supplier with ref_supplier → by (socid, ref_supplier) — the supplier's own ref is the natural key. Same key with a different total aborts (a conflict to resolve, never a dedupe).
• customer (or supplier without ref_supplier) → by (socid, date, total_ttc ±0.02, line fingerprint) — the multiset of (desc, qty, subprice, tva_tx), desc HTML-unescaped/whitespace-collapsed since Dolibarr returns stored text HTML-encoded. Credit notes (type=2) are never candidates; 2+ matches abort.

A hit emits the existing invoice with "deduped": true — and if validate:true was asked while the match is still a draft (run 1 died between create and validate), it is validated now, so a replayed manifest converges instead of stalling on a half-done op. A listing failure other than 404 aborts (POSTing blind would mint duplicates — the exact erp#44 failure mode).

3 · Payment (règlement) — scripts/payment-record.sh

echo '{"invoice_id":19,"mode":"VIR","account_id":1,"transaction_id":"2159468139"}' | scripts/payment-record.sh
echo '{"invoice_id":13,"kind":"supplier","mode":"VIR","account_id":1,"amount":96,
       "transaction_id":"arcodange-1246-1-transaction-019f14c5-e254-7ac9-9e9f-307ed9-d55f44"}' \
  | scripts/payment-record.sh   # stores num 019f14c5-e254-7ac9-9e9f-307ed9-d55f44

The invoice must be validated first. mode: VIR|CB|CHQ|LIQ. Customer payments settle the full remaining amount and mark the invoice paid; supplier payments require an explicit amount. account_id is the bank account id — list them with scripts/bank-accounts.sh (ai_agent_sandbox now holds banque lire).

Always pass transaction_id — the originating bank transaction id (the Qonto/Wise tx id from the feed). It is the first-class way to tie a règlement to the real bank movement: stored on the payment's bank line (llx_bank.num_chq), so reconciliation matches by id rather than by fuzzy amount/date. (num is a back-compat alias for the same field.) Recording without it prints a warning — the payment still posts, but it won't auto-reconcile.

Canonical short form — the varchar(50) constraint. Dolibarr stores num_payment in varchar(50) columns (llx_paiement.num_paiement, llx_paiementfourn.num_paiement) while Qonto transaction ids run ~67 chars (<org>-<n>-<n>-transaction-<uuid>) — POSTing one raw fails with HTTP 400 "value too long for type character varying(50)". The script therefore normalizes before POST: everything through transaction- is stripped and the UUID suffix (globally unique, ~37 chars) is what gets stored. Wise ids (short numerics) pass through unchanged. An id still >50 chars after normalization is refused with an explicit error — never truncated silently. arcodange-bank-reco's bank-match normalizes feed ids the same way, so short-form nums keep reconciling by id (historical long-form nums too). Pass the raw feed id; the script does the rest.

Idempotent (erp#44), composing with the normalization above. Before any POST the invoice's payment list is fetched and deduped by (invoice, amount, normalized transaction_id): a row whose stored num — normalized the same way, so historical long-form Qonto nums still match — equals the normalized transaction_id is a replay. Supplier payments also require the amounts to agree (±0.005; same tx with a different amount aborts as a conflict); customer payments settle the full remaining, so the tx id alone is the key. A hit emits {"id": null, "bank_transaction_id": <existing line>, "transaction_id": <normalized>, "deduped": true} without posting (id is null by honesty — Dolibarr's payment list does not expose the paiement rowid; the bank line is the stable handle). Without a transaction_id there is no dedupe key — a replay WILL double-pay, one more reason it is always passed.

Emits {id, bank_transaction_id, transaction_id, deduped}. bank_transaction_id is the Dolibarr bank line (llx_bank.fk_bank_line) the payment created — the id the reconciliation (arcodange-bank-reco) keys on. transaction_id echoes the normalized num actually stored. Both ends are captured at write time.

4 · Credit note (avoir) — scripts/creditnote-create.sh

# customer avoir
echo '{"socid":42,"source_invoice":19,"validate":true,
       "lines":[{"desc":"Avoir partiel conseil","qty":1,"price_ht":100,"tva":20,"type":"service"}]}' \
  | scripts/creditnote-create.sh
# supplier avoir (avoir fournisseur)
echo '{"socid":12,"kind":"supplier","source_invoice":17,"ref_supplier":"AV-2026-77","validate":true,
       "lines":[{"desc":"Avoir hosting","qty":1,"price_ht":120,"tva":20,"type":"service"}]}' \
  | scripts/creditnote-create.sh

An invoice of type=2 referencing source_invoice (fk_facture_source); amounts come out negative. kind:"supplier" targets /supplierinvoices (carry ref_supplier); default customer targets /invoices. validate:true numbers it (AVC… for customer, AVF… for supplier). Emits {id, ref, ref_supplier, total_ht, total_ttc, fk_facture_source, statut}.

5 · Thirdparty dossier update — scripts/thirdparty-update.sh

scripts/thirdparty-update.sh 1 '{"email":"[email protected]","note_public":"…"}'
scripts/thirdparty-update.sh 1 fiche.json      # or a file; or "-" for stdin
echo '{"socid":1,"fields":{"zip":"33713"}}' | scripts/thirdparty-update.sh   # promote form

Updates an existing fiche's dossier — allowlisted fields only: name, name_alias, address, zip, town, state_id, region_id, country_id, country_code, email, url, phone, typent_id, effectif_id, note_public, note_private, idprof1…idprof6, tva_intra. That is the ledger grammar's "thirdparty complete" — identity / address / typology / notes / national ids. Anything else (code_client, client/fournisseur roles, remises, payment conditions…) is refused before any request, exit non-zero, offender named. Read-back contract: GET before → PUT → GET after; emits {"id":N,"changed":{field:{"before":…,"after":…}}} restricted to the requested fields that actually changed, and exits non-zero if a requested field did not take. Re-applying the same update yields "changed": {} — idempotency you can see.

6 · Contact — scripts/contact-create.sh

echo '{"socid":1,"lastname":"Rootering","firstname":"Hendrik","poste":"COO",
       "email":"[email protected]"}' | scripts/contact-create.sh

Idempotent from day one (the erp#44 pattern): before any POST it lists the thirdparty's contacts and dedupes by case-insensitive email, then by (lastname, firstname); a match emits {"id": <existing>, "deduped": true} and exits 0 without writing. Otherwise POST /contacts → {"id": <new>, "deduped": false}. Required: socid, lastname. Optional: firstname, poste (job title), email, phone (stored as phone_pro), phone_mobile, phone_perso, address, zip, town, country_id, note_public, note_private. Unknown fields are refused, never dropped.

7 · Attach a source document (GED) — scripts/document-attach.sh

echo '{"modulepart":"facture_fournisseur","ref":"FAF2026013",
       "file":"pdfs/F1045_ARCODANGE_2026-06-30.pdf"}' | scripts/document-attach.sh
echo '{"modulepart":"facture","object_id":19,"file":"/abs/path/piece.pdf",
       "filename":"stored-name.pdf"}' | scripts/document-attach.sh

Uploads the source piece (the supplier's own PDF, a contract…) onto an invoice's GED directory via POST /documents/upload (base64 content, overwriteifexists always 0). modulepart: facture/invoice (customer) or facture_fournisseur/invoice_supplier/supplier_invoice (supplier). Address the invoice by object_id or by Dolibarr ref (both = cross-checked; a ref-only lookup matching 0 or 2+ aborts). filename defaults to the file's basename. Emits {object_id, ref, modulepart, filename, sha256, size, deduped}.

Idempotent by (object, filename, sha256) — our own check, never Dolibarr's overwrite flag. Before any POST the object's GED is listed (GET /documents?modulepart=…&id=…, where 404 on a proven-existing object means "no documents yet") and a same-named entry is downloaded back and sha256-compared: identical → {"deduped": true}, no upload; different content ABORTS — silently replacing a stored piece would rewrite evidence (refuse-never-repair). After an upload the file is re-listed, downloaded back and sha256-verified (read-back proof the GED holds exactly the bytes sent).

Promote to prod (rehearse → review → replay)

The ADR-0003 capstone: take a change rehearsed in the sandbox and apply the same operations to prod, with a human in the loop. The unit is a manifest — a JSON array of write ops using symbolic refs (@name) instead of ids, so it is portable from sandbox to prod (an invoice references @tp1, the thirdparty created earlier in the run). See examples/promote-manifest.json. Op kinds: thirdparty, thirdparty_update (input: socid + fields), contact, invoice, creditnote, payment, attach — each mapping to its workflow script above. An attach op's relative file path resolves against the manifest's directory (the manifest is the portable unit: a replay pack carries its pdfs/ beside it), and promote-plan prints the file's sha256 — or a loud MISSING warning — at review time so the content is pinned before any apply.

scripts/promote-plan.sh  change.json                      # 1. human-readable review
scripts/promote-apply.sh change.json --target sandbox     # 2. rehearse the replay (safe)
# 3. promote — writes PROD; the key is env-only and the confirm flag is mandatory:
DOLIBARR_PROD_WRITE_KEY="<prod write key>" \
ARCO_PROMOTE_CONFIRM=I-UNDERSTAND-THIS-WRITES-PROD \
  scripts/promote-apply.sh change.json --target prod

promote-apply resolves each @ref to the id actually created during the run, so dependent ops wire up on the target. --target sandbox writes via dol-write.sh; --target prod writes via dol-prod-write.sh, which reads DOLIBARR_PROD_WRITE_KEY from the environment only (never a stored .env) and refuses any write unless ARCO_PROMOTE_CONFIRM is set exactly. Pair it with dolibarr-data-snapshot (prod before/after) to confirm only the intended records changed.

Replay is safe (erp#44). Every op script dedupes before POSTing, so a manifest that failed mid-run — the 2026-07-11 rehearsal's manifest B, whose op 1 had already created the DARNIS invoice — can simply be re-applied: already-done ops answer deduped=true, the rest execute. promote-apply marks each op created or deduped=true inline and totals them in the summary line (OK — promote complete (1 created, 2 deduped)), so an all-deduped second run is visible proof of a no-op. Live acceptance: tests/replay-idempotency.sh double-applies a self-contained manifest (thirdparty + supplier invoice + payment + GED attach) on the sandbox and asserts run 2 dedupes all ops with zero new rows and zero new GED files.

A manifest value can reference another entity two ways, both resolved against the target so the same file is portable sandbox↔prod:

• @ref — an entity created earlier in this manifest (resolves to the id just created on the target). For new records.
• #entity:field=value — a pre-existing entity, looked up on the target by business key, e.g. #thirdparty:name=KissMetrics or #thirdparty:code=CL0007. Supports thirdparty (name/code/supplier_code) and invoice/supplierinvoice (ref/ref_supplier). A lookup matching nothing or more than one record aborts the run — it never guesses, so it can't write to the wrong entity.

So a real change like "invoice the existing client KissMetrics and record its payment" is {"socid":"#thirdparty:name=KissMetrics", ...} — it resolves to the sandbox KissMetrics on --target sandbox and the prod one on --target prod.

Gotchas

• Validate before paying. A draft (statut=0, ref PROV…) cannot be paid.
• Codes. The thirdparty code module is mod_codeclient_elephant (auto). The REST create needs code_client/code_fournisseur = "-1" to trigger it — the script does this; without it the API errors ErrorCustomerCodeRequired.
• Dates are sent as Unix epochs; pass date:"YYYY-MM-DD" or omit for today.
• Qonto tx ids don't fit varchar(50). payment-record.sh strips the <org>-<n>-<n>-transaction- prefix and stores the UUID suffix (see workflow 3); ids still >50 chars after that are refused. Offline proof: tests/run-tests.sh (stubbed dol-write.sh via the DOL_WRITE hook — writes nothing anywhere).
• banque lire (rights id 111) is granted → scripts/bank-accounts.sh lists accounts (id/label/bank) so a payment can pick its account_id. It's in the provisioner's WRITE_IDS, so a fresh provisionSandbox.ts run includes it.
• user lire (rights id 251) is granted → the checkpoint armed probe (GET /users/info in status/relink-env) answers 200 instead of 403. Also in the provisioner's WRITE_IDS.
• Avoirs (credit notes) → creditnote-create.sh (customer invoice type=2 referencing source_invoice; amounts negative, ref AVC…). Supplier avoirs are a follow-up.
• Dossier updates are allowlisted by design. The ledger grammar's "thirdparty complete" completes a fiche with identity/address/typology/notes/idprof1-6/ tva_intra — never with ledger-side state. thirdparty-update.sh refuses anything else (code_client, roles, payment conditions…) before any request: a typo'd field must fail loudly, not silently mutate the ledger. Offline proof in tests/run-tests.sh.
• Every create dedupes before POSTing (erp#44) — thirdparty by exact name (ambiguous or role-mismatch aborts), supplier invoice by (socid, ref_supplier) (total mismatch aborts), customer invoice by (socid, date, total, line fingerprint), payment by (invoice, amount, normalized tx id), contact by (socid, email) then (socid, lastname+firstname), GED attach by (object, filename, sha256) — each answering {"deduped": true} instead of minting a duplicate, so replaying a manifest is always safe. Two holes: a payment without a transaction_id has no dedupe key and WILL double-pay on a replay, and creditnote-create.sh does not dedupe yet (supplier-avoir parity follow-up) — do not replay a manifest containing a creditnote op past a mid-run failure. Offline proof: tests/run-tests.sh; live double-apply proof: tests/replay-idempotency.sh.
• GED attach paths carry a get_exdir prefix for supplier invoices. A supplier-invoice document lives at fournisseur/facture/<x>/<y>/<REF>/<file> (the <x>/<y> split derives from the object id), so /documents/download needs 0/3/FAF2026014/file.pdf, not FAF2026014/file.pdf. document-attach.sh derives the module-relative path from the listing's fullname (substring after the last /facture/) — never reconstructs it. Customer invoices have no prefix (facture/<REF>/<file>). Upload answers the bare filename as a JSON string; the script verifies it and then read-back-verifies the sha256.
• A dedupe lookup that fails (non-404) aborts the op — the scripts refuse to POST blind, because assuming "no match" on a 403/timeout is precisely how duplicates get minted (cf. the voir_tous ACL trap in the dolibarr skill: missing permissions masquerade as empty lists).
• poste, not soc2. The job-title field on a Dolibarr contact is poste; soc2 (seen in WIP operator payloads) is not a Dolibarr field and the API would drop it silently — contact-create.sh refuses it with a pointer to poste.
• CLI: all of these are also arcodange sandbox {thirdparty|invoice|payment|creditnote|attach|write} (JSON on stdin) — arcodange sandbox help for the list.