Uso

# Listar (con paginación automática por cursor)
factuarea invoices list --json
factuarea contacts list --paginate --json

# Obtener uno
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 resuelve la cuenta sola
#    (GET /v1/me, luego GET /v1/accounts/<tu cuenta>/members)
factuarea account members list --json

# 2) Una escritura debe nombrarla. Sin la cuenta falla con código 2 y no envía
#    nada; con --account la petición 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) Una cuenta gestionada es el recurso: siempre el argumento posicional
#    (GET /v1/accounts/<managed_account>); --account no la rellena
factuarea managed-accounts show <managed_account> --json

# 4) Una ruta raíz de provisión no lleva cuenta (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

# Fichar entrada y salida (cada asiento encadena su huella — RD-ley 8/2019)
factuarea time-entries clock-in  -d '{"employee_id":"…","source":"web"}'
factuarea time-entries clock-out -d '{"employee_id":"…","source":"web"}'

# Solicitar una ausencia y aprobarla
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>

# Presencia del equipo en vivo
factuarea presence live --json

# Cerrar el registro mensual inalterable y exportarlo (ITSS RD-ley 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é se puede automatizar: disparadores, operadores y acciones registradas.
factuarea automations catalog show --json

# Los campos evaluables de un disparador concreto.
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>"
}

# Rellénala y mándala entera. El `scope` se elige aquí y luego no se puede cambiar.
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"
    }}
  ]
}'

# Ensáyala contra un evento de ejemplo: devuelve la traza por paso y no materializa nada.
factuarea automations rules dry-run <rule_id> --json \
  -d '{"event_type":"invoice.paid","event_payload":{"total":1200,"status":"paid"}}'

# Una regla nace en draft y no dispara nada hasta que la actives.
factuarea automations rules activate <rule_id>
factuarea automations rules pause <rule_id>

# Léela y edítala — cada edición sella una versión nueva.
factuarea automations rules show <rule_id> --json
factuarea automations rules update <rule_id> --json -d '{"name":"Warn me on a payment over 2000"}'

# Lístalas con filtros, recorriendo el cursor por ti.
factuarea automations rules list --paginate --json
factuarea automations rules list --status active --trigger_type invoice.paid --json

# Solo las reglas de cartera: las que vigilan los demás NIF de la cuenta.
factuarea automations rules list --scope cartera --json

# Las versiones selladas de la definición.
factuarea automations rules versions list <rule_id> --json
factuarea automations rules versions show <rule_id> 2 --json

# Qué ha disparado, y qué hizo cada paso.
factuarea automations runs list --paginate --json
factuarea automations runs list --automation_rule_id <rule_id> --status failed --json

# Qué hizo una regla de cartera sobre uno de los 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

# Consumo frente al presupuesto del plan para el periodo.
factuarea automations usage show --json

# Relanzar vuelve a ejecutar DE VERDAD el trabajo aparcado: envía correo y entrega webhooks.
factuarea automations runs replay <run_id> --confirm <run_id>
factuarea automations runs steps replay <run_id> 0 --confirm 0

# Borrar una regla la deja sin disparar para siempre; sus versiones y ejecuciones siguen auditables.
factuarea automations rules delete <rule_id> --confirm <rule_id>

# Un proyecto: su clave (una letra más hasta nueve letras o dígitos) prefija las claves de sus tareas (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 tarea. Con el cuerpo completo también puedes vincularla a un documento o a un
# contacto en la misma llamada con `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>"}
}'

# Con flags, cada campo personalizado es `<id del campo>=<valor>` y todos los valores viajan como texto.
factuarea tasks create --project-id <project_id> --title "Call the customer" \
  --custom-fields <field_id>=42 --custom-fields <other_field_id>=high

# Los comandos piden el UUID; resuelve antes una clave como WEB-1.
factuarea tasks find-by-key WEB-1 --json

# Cambiar su estado: a una columna del proyecto o a un estado virtual (`planned` es el backlog).
factuarea tasks status <task_id> --column-id <column_id>
factuarea tasks status <task_id> --status planned

# Buscar, recorriendo el cursor por ti.
factuarea tasks search --project_id <project_id> --status active --paginate --json

# Las etiquetas de tarea de la empresa.
factuarea task-labels list --json

# Imputar tiempo: un periodo cerrado (ISO 8601 con zona horaria)…
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 con el temporizador de quien tiene la key, que solo puede tener uno en marcha.
factuarea tasks timer start <task_id>
factuarea task-timers current --json      # `{"data": null}` si no hay ninguno en marcha
factuarea task-timers stop --json

# Previsualizar y después crear el borrador de factura de las horas facturables de un mes.
factuarea projects time-invoices preview <project_id> \
  -d '{"period":{"from":"2026-09-01","to":"2026-09-30"},"grouping":"per_task"}' --json

# Borrar una columna con tareas exige un destino para ellas. Es irreversible: sin terminal
# interactiva hay que confirmar con --confirm, y lo que se confirma es el ÚLTIMO argumento
# posicional (aquí, la columna borrada).
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

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

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

# Importar cuentas gestionadas en bloque (multipart). Cada fichero va con --file-<campo>:
# `accounts_file` es obligatorio, `customers_file` opcional. Las opciones viajan en -d
# como un objeto JSON plano cuyas claves son los nombres de campo del formulario: solo
# se aceptan `options[send_email]`, `options[apply_customers_to_own_company]` y
# `options[confirm_plan_changes]` (booleanas, `false` por defecto).
factuarea managed-accounts imports template -o plantilla.csv
factuarea managed-accounts imports preview \
  --file-accounts_file cuentas.csv --file-customers_file clientes.csv   # no escribe
factuarea managed-accounts imports create \
  --file-accounts_file cuentas.csv --file-customers_file clientes.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                    # todas las páginas: <ruta> — <título>
factuarea docs list /guides            # solo las que cuelgan de ese prefijo
factuarea docs grep "idempotency-key"  # secciones de documentación que coinciden
factuarea docs get /guides/idempotency # la página entera, en Markdown

factuarea api get /v1/companies/acme_co/stores