Data di scadenza del contratto (Contratti)

Più filtri agiscono in combinazione. Un valore non valido genera un errore HTTP 400 INVALID_FILTER_VALUE, ad esempio ?interval=5 (a partire dalla v2.122.10). A partire dalla v2.122.12, gli spazi vuoti ai margini non vengono conteggiati; un valore vuoto significa «non impostato».

Ogni contratto presenta questi campi. I nomi dello stato e dell’articolo sono in tedesco.

Dati annidati

Oltre a data, in ogni risposta è presente contracts_statuses[] con gli stati contrattuali del negozio, che hanno una denominazione in tedesco (status_id, status_name, status_label, status_active, status_is_default).

• POST crea un nuovo record e richiede contracts_customers_id e contracts_products_id di un cliente o di un articolo esistente. Se viene inviato un contracts_id già esistente, il record non viene creato.
• PUT modifica e richiede l'contracts_id di un contratto esistente. Vengono modificati solo i campi inviati.
• Sono modificabili i campi della struttura dati ad eccezione dei nomi e dei testi (contracts_status_name, customer_name, customer_email, product_name, product_model, contracts_domain_name, …_text). Se si invia un’esportazione, l’importazione li segnala come campi sconosciuti (UNKNOWN_FIELD), così come gli elenchi status_history[] e orders[] nonché gli identificatori contracts_products_attributes_id e contracts_products_id in attributes[] e contracts_domains_id in domains[]. L’importazione li ignora e compila i campi rimanenti; rimuovete questi campi prima di inviare nuovamente i dati, in modo che la risposta non contenga avvisi. I campi data come YYYY-MM-DD, i campi relativi ai periodi di fatturazione (…_period_date_…) come YYYY-MM-DD HH:MM:SS; null o lasciandoli vuoti li azzerano.
• contracts_interval accetta solo 1, 2, 3, 4, 6 o 12; in caso contrario, il record viene rifiutato.
• attributes[] products_options, , e , accettano la chiave senza . Nel caso di , un elenco inviato insieme alla richiesta sostituisce tutte le voci precedenti. products_options_values options_values_price detail_id domains[] contracts_domains_… contracts_domains_id PUT
• status Come oggetto, {"status_id": …, "comments": "…", "customer_notified": 0} imposta lo stato e registra una voce nella cronologia degli stati. v2.122.13 Se status_id non è uno stato contrattuale del negozio (sezione «Stato contrattuale» in basso), non è un numero intero o manca, l’importazione salva il record senza lo stato e segnala l’avviso CONTRACT_STATUS_UNKNOWN; il record viene considerato creato o modificato.
• contracts_status_id L’impostazione diretta sullo stato del contratto imposta lo stato senza inserire alcuna voce nella cronologia degli stati. v2.122.13 Un valore che non è uno stato contrattuale non viene salvato, mentre i campi rimanenti sì, con lo stesso avviso. Per una modifica dello stato con cronologia, utilizzare status o il sotto-endpoint /status.
• ⚠️ Un valore impostato su « contracts_cancellation_date_effective » può avere effetto alla successiva esecuzione della risoluzione automatica del contratto.

Esempio

curl -s -X POST "https://shop.de/xpanel/xoport/Import/JSON/contracts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contracts",
    "data": [{
      "contracts_customers_id": 42,
      "contracts_products_id": 100,
      "contracts_interval": 12,
      "contracts_price": "29.90",
      "contracts_date": "2026-11-01",
      "attributes": [
        {"products_options": "Lizenztyp", "products_options_values": "Enterprise"}
      ],
      "domains": [
        {"contracts_domains_domain_name": "kunde.de"}
      ],
      "status": {"status_id": 1, "comments": "Angelegt per API"}
    }]
  }'

PUT /Import/JSON/contracts/{id}/status con l’ambito contracts:write. È obbligatorio specificare status_id, oltre a comments e customer_notified(facoltativi). Senza status_id si ottiene un errore HTTP 400 MISSING_FIELD; per un status_id che non corrisponda a uno stato contrattuale del negozio o a un numero intero, si ottiene un errore HTTP 400 INVALID_STATUS con gli ID validi riportati in error.valid_status_ids (a partire dalla v2.122.13, sezione «Stato del contratto») e, per un contratto sconosciuto, HTTP 404 NOT_FOUND. In tutti e tre i casi il contratto rimane invariato.

curl -s -X PUT "https://shop.de/xpanel/xoport/Import/JSON/contracts/1/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status_id": 3, "comments": "Kündigung per API", "customer_notified": 0}'

# Antwort
{
  "success": true,
  "type": "contracts_status",
  "contracts_id": 1,
  "previous_status_id": 1,
  "new_status_id": 3,
  …
}

Se il contratto ha una data di risoluzione valida, la risposta riporta inoltre warning: la risoluzione automatica del contratto può sovrascrivere lo stato in un secondo momento.

Per status_id, status.status_id e contracts_status_id è valido qualsiasi stato del contratto del negozio: gli stati della tabella status con type = 'contracts', da cui attinge anche il backend, in ogni lingua, compresi quelli disattivati (status_active = 0); questi ultimi nascondono solo la selezione nel backend. Gli stati dell’ordine (/order_statuses) non sono stati contrattuali. Gli ID validi variano a seconda del negozio: consultateli su contracts_statuses[], su GET /Export/JSON/contracts o su error.valid_status_ids. contracts_statuses[] elenca solo gli stati con denominazione in tedesco; uno stato senza denominazione in tedesco è comunque valido.

L’ID è un numero intero, espresso come cifra singola o sequenza di cifre (54, "54"; gli spazi in margine non contano). true, [65], "54abc", "1e3", 54.9 o 54.0 non sono ID.

HTTP 400
{
  "success": false,
  "api_version": "2.122.13",
  "error": {
    "code": "INVALID_STATUS",
    "message": "status_id 1 is not a contract status. Valid: 7, 3, 12 (…)",
    "valid_status_ids": [7, 3, 12]
  }
}

Nell’importazione del contratto, il record continua a essere conteggiato come inserted o updated. L’avviso è presente in warnings[] nella risposta e nella voce del record in records[]:

"warnings": [
  {
    "type": "CONTRACT_STATUS_UNKNOWN",
    "field": "status.status_id",
    "entity": "contracts",
    "contracts_id": 42,
    "message": "Contract 42: status.status_id ignored — status.status_id 1 is not a contract status. Valid: 7, 3, 12 (…)",
    "first_occurrence": "record 1"
  }
]

Vengono eliminati il contratto, i suoi attributi e domini, la cronologia dello stato e i collegamenti a fatture e progetti. Le fatture e i progetti stessi rimangono.

# Ein Vertrag
curl -s -X DELETE "https://shop.de/xpanel/xoport/Delete/JSON/contract/1" \
  -H "Authorization: Bearer $TOKEN"

# Mehrere Verträge
curl -s -X DELETE "https://shop.de/xpanel/xoport/Delete/JSON/contracts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": [{"contracts_id": 1}, {"contracts_id": 2}]}'

• Un contratto sconosciuto genera un errore HTTP 404 NOT_FOUND se richiamato singolarmente. In caso di elaborazione in batch, gli ID cancellati si trovano in deleted_ids, quelli non trovati in errors[].
• Un URL troncato senza data[].contracts_id, ad esempio {"ids": [1, 2]}, non cancella nulla e restituisce un errore HTTP 400 MISSING_DATA.