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), customer + supplier invoices with product/service lines and the supplier's own reference, validate them, and record règlements (payments). 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", "saisir une facture", "record an invoice with lines", "enregistrer un règlement / paiement", 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), and for credit notes/avoirs (a planned follow-up). 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 NOT in this skill. Rehearse here → capture a reviewable diff with the read-only dolibarr-data-snapshot skill (before/after) → a human approves → the same operations are replayed against prod under a separate, human-held prod-write credential. Never wire a prod-write key into this skill.

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

All three read a JSON object on stdin (or a file path as $1) and emit ids.

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. Emits the new id.

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}.

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

echo '{"invoice_id":19,"mode":"VIR","account_id":1}'                  | scripts/payment-record.sh
echo '{"invoice_id":13,"kind":"supplier","mode":"VIR","account_id":1,"amount":96}' \
  | scripts/payment-record.sh

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 (the read-only dolibarr-payments-state skill lists them; ai_agent_sandbox does not yet have banque lire, so pass the id). Emits the new payment id.

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

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

A customer invoice of type=2 referencing source_invoice (fk_facture_source); amounts come out negative (a credit). validate:true turns the draft into a numbered AVC… avoir. Emits {id, ref, total_ht, total_ttc, fk_facture_source, statut}.

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.
• banque lire isn't granted yet → GET /bankaccounts returns empty. Add it to the provisioner's rights set if account discovery from this skill is needed.
• Avoirs (credit notes) → creditnote-create.sh (customer invoice type=2 referencing source_invoice; amounts negative, ref AVC…). Supplier avoirs are a follow-up.
• CLI: all of these are also arcodange sandbox {thirdparty|invoice|payment|creditnote|write} (JSON on stdin) — arcodange sandbox help for the list.