Punto finale per progetti e attività

NOVITÀ v2.35.0 · xoCRM

Endpoint Progetti

Gestisci i progetti e le attività di xoCRM tramite l'API JSON: esporta, crea, aggiorna ed elimina — incluse descrizioni multilingue, responsabili di progetto, assegnazioni agli incaricati e cronologia degli stati.

Endpoint

MetodoEndpointAmbitoDescrizione
GET/Export/JSON/projectsprojects:readTutti i progetti (opzionale ?include_tasks=1)
GET/Export/JSON/project/{id}projects:readSingolo progetto
POST/Import/JSON/projectsprojects:writeCrea nuovi progetti
PUT/Import/JSON/projectsprojects:writeAggiorna progetti (project_id obbligatorio)
DELETE/Delete/JSON/project/{id}projects:deleteElimina progetto (in modo a cascata, comprese le attività)
GET/Export/JSON/project_tasksproject_tasks:readTutte le attività (filtri vedi sotto)
GET/Export/JSON/project_task/{id}project_tasks:readSingola attività
POST/Import/JSON/project_tasksproject_tasks:writeCrea nuove attività (project_id obbligatorio)
PUT/Import/JSON/project_tasksproject_tasks:writeAggiorna attività (task_id obbligatorio)
DELETE/Delete/JSON/project_task/{id}project_tasks:deleteElimina attività (il progetto rimane inalterato)

Filtro (Esportazione)

Progetti

  • ?status={id} — Stato del progetto
  • ?customer_id={id} — cliente associato
  • ?category_id={id} — Categoria del progetto
  • ?leader_admin_id={id} — Responsabile del progetto
  • ?is_private=0|1 — progetti privati
  • ?date_from / ?date_to — Data di creazione
  • ?last_modified={ts} — modificato il
  • ?include_tasks=1 — attività incorporate

Attività

  • ?project_id={id} — Attività di un progetto
  • ?status={id} — Stato delle attività
  • ?priority=1-5 — Priorità
  • ?admin_id={id} — Responsabile assegnato
  • ?customer_id={id} / ?category_id={id}
  • ?due_from / ?due_to — Intervallo di scadenza
  • ?progress_min / ?progress_max — Stato di avanzamento (0-100)
  • ?last_modified={ts} — modificato il

?language=de|en determina la lingua dei nomi degli stati e delle categorie. I meta-blocchi project_statuses[] e task_statuses[] forniscono tutti i valori di stato disponibili.

Struttura del payload (progetto)

{
  "type": "projects",
  "data": [
    {
      "name": "Website-Relaunch",
      "description": "<p>Beschreibung (Default-Sprache)</p>",
      "descriptions": [
        { "language_id": 1, "project_name": "Website Relaunch", "project_description": "<p>EN</p>" }
      ],
      "customer_scope": "specific",
      "customer_ids": [4711],
      "date_start": "2026-07-01",
      "date_end": "2026-09-30",
      "is_private": false,
      "leader_admin_ids": [1],
      "category_ids": [2],
      "relationships": [ { "target_type": "orders_id", "target_id": 12345 }, { "target_type": "contracts_id", "target_id": 318 } ],
      "admin_id": 1,
      "status_comment": "Projekt via API angelegt"
    }
  ]
}

Struttura del payload (attività)

{
  "type": "project_tasks",
  "data": [
    {
      "project_id": 126,
      "name": "Konzept erstellen",
      "priority": 4,
      "progress_percent": 0,
      "date_start": "2026-07-01",
      "due_date": "2026-07-15",
      "hours_planned": 8.5,
      "hours_actual": null,
      "status_id": 60,
      "assigned_admin_ids": [1],
      "admin_id": 1,
      "status_comment": "Aufgabe via API angelegt"
    }
  ]
}

Collegamenti con ordini, ticket e contratti v2.122.11

relationships[] collega un progetto a ordini (orders_id), ticket (ticket_id) e, a partire dalla v2.122.11, anche a contratti (contracts_id), come nel backend. Se la chiave è presente nel record, PUT sostituisce tutti i collegamenti del progetto.

{
  "type": "projects",
  "data": [{
    "project_id": 126,
    "relationships": [
      {"target_type": "orders_id",    "target_id": 12345},
      {"target_type": "ticket_id",    "target_id": 8812},
      {"target_type": "contracts_id", "target_id": 318}
    ],
    "admin_id": 1
  }]
}
Versionifino alla v2.122.10dalla v2.122.11
La chiave manca oppure nulli collegamenti rimangono invariaticome prima
[]PUT elimina tutti i collegamenti del progettocome prima
La voce con contracts_idrecord fallisce (“Relazioni non valide”)Il collegamento viene scritto
target_type sconosciuto, target_id ≤ 0 oppure l'inserimento non è un oggettoIl record non viene salvatoIl record non è valido, il messaggio indica orders_id|ticket_id|contracts_id; nessuna parte di questo record viene scritta
relationships non è un elenco, ma ad esempio un testoPOST crea il progetto senza collegamenti, PUT cancella silenziosamente tuttiIl record non viene salvato (“Invalid relationships (must be a list …)”), non viene modificato nulla
L’ordine, il ticket o il contratto non esisteIl collegamento viene comunque salvatoquesto collegamento non viene creato, mentre il resto del record sì; warnings[] segnala PROJECT_RELATIONSHIP
Esportazioneanche le voci senza tipo, a causa delle quali un’esportazione rinviata è fallitasolo voci dei tre tipi
"warnings": [{"type": "PROJECT_RELATIONSHIP", "field": "relationships", "entity": "projects",
  "message": "relationships: not found: contracts_id 999 — these links were not written.", "first_occurrence": "record 1"}]
Esportazione restituita: poiché PUT sostituisce tutti i collegamenti e l’importazione scrive solo le destinazioni esistenti, un’esportazione restituita perde i propri collegamenti a ordini, ticket e contratti cancellati. Questi non puntavano comunque a nulla; l’avviso li menziona.

Note

  • NOVITÀ v2.36.0: i progetti e le attività contengono nell’esportazione status_history[] — tutte le voci di stato, inclusi comments (verbali delle riunioni), progress_percent, status_name e user_name.
  • admin_id = amministratore responsabile (viene salvato comecreated_by/modified_by e nella cronologia degli stati come user_id; se non specificato = 0/sistema).
  • status_id viene convalidato rispetto alla gestione degli stati (tipo projects o tasks); se non specificato, viene applicato lo stato predefinito. Una modifica dello stato tramite PUT genera automaticamente una voce nella cronologia degli stati con status_comment — a partire dalla v2.40.0, status_comment scrive una voce anche senza modifica dello stato (note di lavoro/verbali); per le attività, progress_percent viene inserito nella voce come avanzamento.
  • descriptions[] è multilingue; con PUT si applica la semantica di unione — vengono sovrascritte solo le lingue/i campi forniti.
  • leader_admin_ids, relationships (progetti) e assigned_admin_ids (attività) vengono sostituiti solo se la chiave è contenuta nel payload (replace-on-present).
  • Un POST con un ID già assegnato restituisce «Already exists» — in tal caso utilizzare PUT (e viceversa «Not found» con PUT su ID sconosciuti).
  • Attenzione: DELETE /project/{id} elimina in modo a cascata tutte le attività del progetto. Gli ordini, i ticket e i contratti collegati vengono solo scollegati, non eliminati. La risposta contiene deleted_tasks.