Temps imputat a tasques

El temps imputat a una tasca mesura el treball dedicat a ella, perquè vegis on van les hores i les puguis facturar. Les imputes a mà, com un període tancat, o amb un temporitzador que corre fins que l'aturis, i un projecte converteix les seves hores facturables en un esborrany de factura.

Imputar temps a mà

POST /v1/tasks/{task}/time-entries imputa un període tancat de treball:

curl -X POST https://api.factuarea.com/v1/tasks/$TASK_ID/time-entries \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2026-09-28T09:00:00+02:00",
    "ended_at": "2026-09-28T11:00:00+02:00",
    "description": "Payment gateway integration",
    "billable": true
  }'

• started_at i ended_at són ISO 8601 amb zona horària. El període ha d'acabar després de començar, durar com a màxim 24 hores i no començar amb més d'un dia d'avanç; si no, la crida retorna 422 invalid_time_entry_period. Una imputació amb inici i fi iguals és vàlida i dura zero segons.
• description és opcional, de fins a 1000 caràcters. billable val true per defecte.
• L'autoria és sempre de qui té la credencial.
• Les imputacions es poden solapar: és treball que atribueixes a tasques, no un fitxatge.

La imputació es retorna amb el seu duration_seconds, is_running i, un cop facturada, l'invoice_id i l'invoiced_at de la factura que la inclou.

El temporitzador

En lloc d'escriure un període, arrenca un temporitzador quan comences i atura'l quan acabes:

# Arrencar-lo en una tasca (sense cos)
curl -X POST https://api.factuarea.com/v1/tasks/$TASK_ID/timer/start \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

# Què està corrent ara? `data` és null si no hi ha res
curl https://api.factuarea.com/v1/task-timers/current \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

# Aturar-lo, a la tasca on corri
curl -X POST https://api.factuarea.com/v1/task-timers/stop \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

• Un temporitzador per usuari i empresa. Arrencar-ne un altre mentre un corre, en qualsevol tasca, retorna 409 task_timer_already_running i deixa intacte el que estava en marxa. Un usuari amb un temporitzador en una altra empresa en pot arrencar un aquí.
• Un temporitzador en marxa és una imputació amb ended_at: null i is_running: true.
• Aturar-lo fixa la fi en l'instant actual i retorna la imputació tancada. Sense temporitzador en marxa retorna 422 task_timer_not_running.
• Un temporitzador que porta més de 24 hores corrent es tanca exactament a les 24 hores del seu inici, així que un d'oblidat mai no bloqueja el següent.
• El temporitzador pertany a qui té la credencial, així que GET /v1/task-timers/current mostra el seu i mai el d'una altra persona.

Editar i esborrar imputacions

PUT /v1/tasks/{task}/time-entries/{time_entry} és parcial i canvia started_at, ended_at, description i billable. En una imputació en marxa només pots canviar la descripció i la marca de facturable: atura el temporitzador per tancar-la.

Quan una imputació s'inclou en una factura queda bloquejada: editar-la o esborrar-la retorna 422 task_time_entry_invoiced fins que s'esborri l'esborrany de factura. DELETE .../time-entries/{time_entry} és permanent i necessita el scope tasks:delete i una Idempotency-Key; esborrar una imputació en marxa cancel·la el temporitzador.

GET /v1/tasks/{task}/time-entries llista les imputacions d'una tasca, de la més recent a la més antiga i amb paginació per cursor.

Resum de temps d'un projecte

GET /v1/projects/{project}/time-summary respon quant de temps ha consumit un projecte, opcionalment entre from i to (dates a la zona horària de l'empresa):

{
  "data": {
    "object": "project_time_summary",
    "project_id": "0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "total_seconds": 36900,
    "billable_seconds": 33300,
    "invoiced_seconds": 9900,
    "pending_seconds": 23400,
    "by_task": [
      {
        "task_id": "0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12",
        "key": "DEV-12",
        "title": "Integrate the payment gateway in the checkout",
        "total_seconds": 22500,
        "billable_seconds": 22500,
        "invoiced_seconds": 9900,
        "pending_seconds": 12600
      }
    ],
    "by_user": [
      {
        "user_id": "0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01",
        "name": "Ana Pérez",
        "total_seconds": 22500,
        "billable_seconds": 22500
      }
    ]
  }
}

pending_seconds és el que encara pots facturar: el temps facturable que encara no s'ha facturat. Els temporitzadors en marxa queden fora de tots els totals.

Facturar les hores

Un projecte converteix les seves hores facturables en un esborrany de factura per al seu contacte de facturació. Han d'estar definits al projecte, amb PUT /v1/projects/{project} o a l'app:

• un contacte de facturació (billing_contact_id) que pugui rebre factures de venda;
• un preu: una tarifa per hora (billing_hourly_rate) o un producte de facturació (billing_product_id), el preu del qual per a aquest contacte es fa servir quan no hi ha tarifa.

Sense ells, la crida retorna 422 task_time_not_invoiceable i indica què hi falta.

Tria les hores amb entry_ids (fins a 500 imputacions) o amb un period (from i to, inclusius, per la data d'inici de les imputacions) —mai les dues coses— i una grouping: per_task dona una línia per tasca, per_entry una línia per imputació i single_line una sola línia amb el total. Només compleixen els requisits les imputacions del projecte tancades, facturables i encara sense facturar.

Primer, la vista prèvia. Aplica les mateixes comprovacions i no crea res:

curl -X POST https://api.factuarea.com/v1/projects/$PROJECT_ID/time-invoices/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "period": { "from": "2026-09-01", "to": "2026-09-30" }, "grouping": "per_task" }'

La vista prèvia llista el client, les línies (quantitat en hores, unitat HUR, preu i import abans d'impostos), els totals en segons i en hores, les imputacions que es facturarien i els warnings. Després crea la factura amb el mateix cos:

curl -X POST https://api.factuarea.com/v1/projects/$PROJECT_ID/time-invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "period": { "from": "2026-09-01", "to": "2026-09-30" }, "grouping": "per_task" }'

{
  "data": {
    "id": "0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d01",
    "object": "task_time_invoice",
    "project_id": "0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01",
    "invoice_id": "0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d10",
    "grouping": "per_task",
    "status": "draft"
  }
}

• Exigeix invoices:write, no un scope de projectes: l'operació crea una factura. Una credencial amb només projects:write rep 403 insufficient_scope. La vista prèvia és una lectura i necessita projects:read.
• La factura és un esborrany. Mai no s'emet, s'envia ni es registra davant de l'AEAT per si sola; l'acabes amb l'API de factures. S'hi apliquen les regles normals de les factures: si el pla ha esgotat les seves factures, la crida retorna 402 limit_exceeded i no es crea res.
• Tot o res. En una transacció es crea la factura i es marquen les imputacions com a facturades. Si falla qualsevol pas, no queda cap imputació marcada.
• Els reintents són segurs. Repetir la petició amb la mateixa Idempotency-Key, o amb el mateix batch_id, retorna la mateixa factura. Dues peticions alhora sobre les mateixes imputacions produeixen una sola factura; l'altra rep task_time_entry_invoiced.
• Esborrar l'esborrany allibera les hores. Tornen a ser pendents. Emetre, enviar, cobrar o anul·lar la factura no les allibera.

Esdeveniments

Les imputacions emeten task_time_entry.created (també en arrencar un temporitzador), task_time_entry.updated (també en aturar-lo), task_time_entry.deleted i task_time_entry.invoiced, un per cada imputació d'un lot facturat. Consulta Esdeveniments de tasques.

Propers passos