Ús

# Llistar (amb paginació automàtica per cursor)
factuarea invoices list --json
factuarea contacts list --paginate --json

# Obtenir-ne un
factuarea invoices show <uuid> --json

factuarea invoices create -d '{"client_id":"…","series_id":"…","lines":[…]}'

factuarea invoices send <uuid>
factuarea invoices mark-paid <uuid>

# 1) Una lectura resol el compte sola
#    (GET /v1/me, després GET /v1/accounts/<el teu compte>/members)
factuarea account members list --json

# 2) Una escriptura l'ha d'anomenar. Sense el compte falla amb codi 2 i no envia
#    res; amb --account la petició va a POST /v1/accounts/<account>/webhooks
factuarea account webhooks create --url https://example.com/hooks --enabled-events account.member_added
factuarea account webhooks create --account <account> --url https://example.com/hooks --enabled-events account.member_added

# 3) Un compte gestionat és el recurs: sempre l'argument posicional
#    (GET /v1/accounts/<managed_account>); --account no l'omple
factuarea managed-accounts show <managed_account> --json

# 4) Una ruta arrel d'aprovisionament no porta compte (POST /v1/accounts)
factuarea managed-accounts create --external-ref cliente-0042 --plan emprendedor \
  --tax-id B12345674 --legal-name "Talleres García SL" --confirm create

factuarea managed-accounts list --json
factuarea managed-accounts show <managed_account>
factuarea managed-accounts plan preview <managed_account> --plan empresario
factuarea managed-accounts plan update <managed_account> --plan empresario --confirm <managed_account>
factuarea managed-accounts access-level update <managed_account> --level view
factuarea managed-accounts claim-tokens create <managed_account> --send-email --confirm <managed_account>
factuarea managed-accounts management end <managed_account> --confirm <managed_account>

factuarea account webhooks list --json
factuarea account webhooks create --account <account> --url https://example.com/hooks \
  --enabled-events account.member_added --account-relationship own
factuarea account webhooks deliveries list <webhook> --status failed --json
factuarea account webhooks deliveries retry --account <account> <webhook> <delivery>
factuarea account request-logs list --only_errors true --json
factuarea account request-logs show <request_id> --json

# Fitxar entrada i sortida (cada assentament encadena la seva empremta — RD-llei 8/2019)
factuarea time-entries clock-in  -d '{"employee_id":"…","source":"web"}'
factuarea time-entries clock-out -d '{"employee_id":"…","source":"web"}'

# Sol·licitar una absència i aprovar-la
factuarea absence-requests create \
  -d '{"employee_id":"…","absence_type_id":"…","start_date":"2026-08-01","end_date":"2026-08-05"}'
factuarea absence-requests approve <uuid>

# Presència de l'equip en viu
factuarea presence live --json

# Tancar el registre mensual inalterable i exportar-lo (ITSS RD-llei 8/2019)
factuarea monthly-time-record-closes create -d '{"year":2026,"month":7}'
factuarea monthly-time-record-closes export <uuid> --format rdley_8_2019 --json

# Què es pot automatitzar: activadors, operadors i accions registrades.
factuarea automations catalog show --json

# Els camps avaluables d'un activador concret.
factuarea automations catalog trigger-fields invoice.paid --json

factuarea automations rules create --skeleton

{
  "actions": [],
  "conditions": {
    "<key>": "<string>"
  },
  "description": "<string>",
  "name": "<string>",
  "scope": "<empresa|cartera>",
  "trigger_type": "<string>"
}

# Omple-la i envia-la sencera. L'`scope` es tria aquí i després no es pot canviar.
factuarea automations rules create --json -d '{
  "name": "Warn me on a large payment",
  "scope": "empresa",
  "trigger_type": "invoice.paid",
  "conditions": {"field": "total", "operator": "gte", "value": 1000},
  "actions": [
    {"type": "notify_in_app", "order": 0, "parameters": {
      "recipient_type": "role", "role": "admin", "category": "invoice",
      "title": "Large payment", "message": "An invoice over 1000 EUR has been paid"
    }}
  ]
}'

# Assaja-la contra un esdeveniment d'exemple: torna la traça per pas i no materialitza res.
factuarea automations rules dry-run <rule_id> --json \
  -d '{"event_type":"invoice.paid","event_payload":{"total":1200,"status":"paid"}}'

# Una regla neix en draft i no dispara res fins que l'actives.
factuarea automations rules activate <rule_id>
factuarea automations rules pause <rule_id>

# Llegeix-la i edita-la — cada edició segella una versió nova.
factuarea automations rules show <rule_id> --json
factuarea automations rules update <rule_id> --json -d '{"name":"Warn me on a payment over 2000"}'

# Llista-les amb filtres, recorrent el cursor per tu.
factuarea automations rules list --paginate --json
factuarea automations rules list --status active --trigger_type invoice.paid --json

# Només les regles de cartera: les que vigilen els altres NIF del compte.
factuarea automations rules list --scope cartera --json

# Les versions segellades de la definició.
factuarea automations rules versions list <rule_id> --json
factuarea automations rules versions show <rule_id> 2 --json

# Què ha disparat, i què va fer cada pas.
factuarea automations runs list --paginate --json
factuarea automations runs list --automation_rule_id <rule_id> --status failed --json

# Què va fer una regla de cartera sobre un dels NIF que vigila.
factuarea automations runs list --subject_company_id <company_id> --json
factuarea automations runs show <run_id> --json
factuarea automations runs steps list <run_id> --json

# Consum davant del pressupost del pla per al període.
factuarea automations usage show --json

# Rellançar torna a executar DE DEBÒ la feina aparcada: envia correu i entrega webhooks.
factuarea automations runs replay <run_id> --confirm <run_id>
factuarea automations runs steps replay <run_id> 0 --confirm 0

# Esborrar una regla la deixa sense disparar per sempre; les seves versions i execucions segueixen auditables.
factuarea automations rules delete <rule_id> --confirm <rule_id>

# Un projecte: la seva clau (una lletra més fins a nou lletres o dígits) prefixa les claus de les seves tasques (WEB-1, WEB-2…)
factuarea projects list --json
factuarea projects create --name "Web redesign" --key WEB --json
factuarea projects columns list <project_id> --json

# Crear una tasca. Amb el cos complet també pots vincular-la a un document o a un
# contacte a la mateixa crida amb `entity_link` (invoice, quote, contact, product…).
factuarea tasks create --json -d '{
  "project_id": "<project_id>",
  "title": "Prepare the quote",
  "priority": "high",
  "due_on": "2026-10-15",
  "entity_link": {"type": "quote", "id": "<quote_id>"}
}'

# Amb flags, cada camp personalitzat és `<id del camp>=<valor>` i tots els valors viatgen com a text.
factuarea tasks create --project-id <project_id> --title "Call the customer" \
  --custom-fields <field_id>=42 --custom-fields <other_field_id>=high

# Les comandes demanen l'UUID; resol abans una clau com WEB-1.
factuarea tasks find-by-key WEB-1 --json

# Canviar-ne l'estat: a una columna del projecte o a un estat virtual (`planned` és el backlog).
factuarea tasks status <task_id> --column-id <column_id>
factuarea tasks status <task_id> --status planned

# Cercar, recorrent el cursor per tu.
factuarea tasks search --project_id <project_id> --status active --paginate --json

# Les etiquetes de tasca de l'empresa.
factuarea task-labels list --json

# Imputar temps: un període tancat (ISO 8601 amb zona horària)…
factuarea tasks time-entries list <task_id> --paginate --json
factuarea tasks time-entries create <task_id> \
  --started-at 2026-09-28T09:00:00+02:00 --ended-at 2026-09-28T10:30:00+02:00 \
  --description "Quote review"

# …o amb el temporitzador de qui té la key, que en pot tenir només un en marxa.
factuarea tasks timer start <task_id>
factuarea task-timers current --json      # `{"data": null}` si no n'hi ha cap en marxa
factuarea task-timers stop --json

# Previsualitzar i després crear l'esborrany de factura de les hores facturables d'un mes.
factuarea projects time-invoices preview <project_id> \
  -d '{"period":{"from":"2026-09-01","to":"2026-09-30"},"grouping":"per_task"}' --json

# Esborrar una columna amb tasques exigeix una destinació per a elles. És irreversible: sense
# terminal interactiu cal confirmar amb --confirm, i el que es confirma és l'ÚLTIM argument
# posicional (aquí, la columna esborrada).
factuarea projects columns delete <project_id> <column_id> \
  --move_to_column_id <other_column_id> --confirm <column_id>

# Create a template in the company library: only --name is required.
factuarea pdf-templates create --company "$COMPANY_ID" \
  --name "Factura clásica" --base-preset classic --json

# Template lists paginate by page: one request per call, without --paginate.
factuarea pdf-templates list --company "$COMPANY_ID" --page 1 --per_page 20 --json

# Rename it, with the ETag of the last read as the If-Match precondition.
ETAG=$(factuarea pdf-templates find --company "$COMPANY_ID" "$TEMPLATE_ID" \
  --show-etag --json 2>&1 >/dev/null | sed -n 's/^etag: //p')
factuarea pdf-templates update --company "$COMPANY_ID" "$TEMPLATE_ID" \
  --name "Factura clásica 2026" --if-match "$ETAG" --json

# Pin that template on an invoice: expected_version is the selection_version
# of get-presentation…
factuarea invoices get-presentation --company "$COMPANY_ID" "$INVOICE_ID" --json
factuarea invoices assign-presentation --company "$COMPANY_ID" "$INVOICE_ID" \
  --template-id "$TEMPLATE_ID" --expected-version 1 --json

# …or hand the choice back to the defaults: template_id is required and accepts null.
factuarea invoices assign-presentation --company "$COMPANY_ID" "$INVOICE_ID" \
  --null-template-id --expected-version 2 --json

# Exact PDF of the invoice: prepare it from the id of its presentation, render it
# and download it.
factuarea pdf-artifacts prepare --company "$COMPANY_ID" --document-type invoice \
  --document-id "$INVOICE_ID" --presentation-id "$PRESENTATION_ID" \
  --purpose complete --format a4 --variant official --json
factuarea pdf-artifacts render --company "$COMPANY_ID" "$ARTIFACT_ID" --mode async --json
factuarea pdf-artifacts download --company "$COMPANY_ID" "$ARTIFACT_ID" -o invoice.pdf --show-etag

# Clear the description (null). --name is not passed, so the name is kept.
factuarea pdf-templates update --company "$COMPANY_ID" "$TEMPLATE_ID" \
  --null-description --if-match "$ETAG" --json

# Descarregar un PDF
factuarea invoices pdf <uuid> -o invoice.pdf

# Pujar un certificat (multipart)
factuarea verifactu certificates upload \
  -d '{"certificate_password":"…"}' --file-certificate_file cert.p12

# Importar comptes gestionats en bloc (multipart). Cada fitxer va amb --file-<camp>:
# `accounts_file` és obligatori, `customers_file` opcional. Les opcions viatgen a -d
# com un objecte JSON pla les claus del qual són els noms de camp del formulari: només
# s'accepten `options[send_email]`, `options[apply_customers_to_own_company]` i
# `options[confirm_plan_changes]` (booleanes, `false` per defecte).
factuarea managed-accounts imports template -o plantilla.csv
factuarea managed-accounts imports preview \
  --file-accounts_file comptes.csv --file-customers_file clients.csv   # no escriu
factuarea managed-accounts imports create \
  --file-accounts_file comptes.csv --file-customers_file clients.csv \
  -d '{"options[send_email]":true}' --confirm create                   # irreversible

# Keep the ETag of the copy you download…
factuarea invoices pdf --company "$COMPANY_ID" "$INVOICE_ID" -o invoice.pdf --show-etag

# …and download it again only if it changed: a 304 leaves invoice.pdf untouched.
factuarea invoices pdf --company "$COMPANY_ID" "$INVOICE_ID" -o invoice.pdf \
  --if-none-match "$PDF_ETAG"

factuarea api get /v1/me --json
factuarea api post /v1/companies/acme_co/invoices -d '{…}'

factuarea commands --json

factuarea docs search invoice

factuarea docs list                    # totes les pàgines: <ruta> — <títol>
factuarea docs list /guides            # només les que pengen d'aquest prefix
factuarea docs grep "idempotency-key"  # seccions de documentació que coincideixen
factuarea docs get /guides/idempotency # la pàgina sencera, en Markdown

factuarea api get /v1/companies/acme_co/stores