Date d'échéance du contrat (Contracts)

Plusieurs filtres agissent conjointement. Une valeur invalide génère un code HTTP 400 INVALID_FILTER_VALUE, par exemple ?interval=5 (depuis la v2.122.10). Depuis la v2.122.12, les espaces en bordure ne sont pas pris en compte ; une valeur vide signifie « non défini ».

Chaque contrat comporte ces champs. Les noms des statuts et des articles sont en allemand.

Données imbriquées

En plus de data, chaque réponse contient contracts_statuses[] avec les statuts contractuels de la boutique, qui portent une désignation en allemand (status_id, status_name, status_label, status_active, status_is_default).

• POST crée un enregistrement et nécessite les identifiants « contracts_customers_id » et « contracts_products_id » d’un client ou d’un article existant. Si l’identifiant « contracts_id » transmis existe déjà, l’enregistrement échoue.
• PUT modifie et nécessite l’ contracts_id d’un contrat existant. Seuls les champs envoyés sont mis à jour.
• Les champs de la structure de données peuvent être modifiés, à l’exception des noms et des textes (contracts_status_name, customer_name, customer_email, product_name, product_model, contracts_domain_name, …_text). Si l’on renvoie une exportation, l’importation signale ces champs comme inconnus (UNKNOWN_FIELD), de même que les listes status_history[] et orders[] ainsi que les identifiants contracts_products_attributes_id et contracts_products_id dans attributes[] et contracts_domains_id dans domains[]. L'importation les ignore et remplit les autres champs ; supprimez ces champs avant de renvoyer la requête, la réponse ne contiendra alors aucun avertissement. Les champs de date sous la forme YYYY-MM-DD, les champs des périodes de facturation (…_period_date_…) sous la forme YYYY-MM-DD HH:MM:SS; null ou vides les laisse vides.
• contracts_interval N'accepte que 1, 2, 3, 4, 6 ou 12; sinon, l'enregistrement échoue.
• attributes[] products_options, , , et utilisent la clé sans . Dans le cas de , une liste transmise remplace toutes les entrées existantes. products_options_values options_values_price detail_id domains[] contracts_domains_… contracts_domains_id PUT
• status En tant qu’objet {"status_id": …, "comments": "…", "customer_notified": 0}, cette commande définit le statut et ajoute une entrée dans l’historique des statuts. v2.122.13 Si status_id n’est pas un statut de contrat de la boutique (section « Statuts de contrat » ci-dessous), n’est pas un nombre entier ou est manquant, l’importation enregistre l’enregistrement sans le statut et génère l’avertissement CONTRACT_STATUS_UNKNOWN; l’enregistrement est considéré comme créé ou modifié.
• contracts_status_id La modification directe du contrat définit le statut sans enregistrement dans l’historique des statuts. v2.122.13 Une valeur qui n’est pas un statut de contrat n’est pas enregistrée, contrairement aux autres champs, avec le même avertissement. Pour un changement de statut avec historique, utilisez status ou le sous-point de terminaison /status.
• ⚠️ Un statut « contracts_cancellation_date_effective » défini peut avoir un effet lors de la prochaine exécution de la résiliation automatique du contrat.

Exemple

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 avec la portée contracts:write. Le champ status_id est obligatoire, ainsi que, au choix, comments et customer_notified. Sans status_id, la réponse est HTTP 400 MISSING_FIELD; pour une valeur status_id qui n’est pas un statut de contrat de la boutique ou un nombre entier, la réponse est HTTP 400 INVALID_STATUS avec les identifiants valides indiqués dans error.valid_status_ids (depuis la v2.122.13, section « Statut du contrat ») et, pour un contrat inconnu, HTTP 404 NOT_FOUND. Dans les trois cas, le contrat reste inchangé.

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,
  …
}

Si le contrat comporte une date de résiliation effective, la réponse contient en outre warning: la résiliation automatique du contrat peut ultérieurement remplacer ce statut.

Pour status_id, status.status_id et contracts_status_id, tous les statuts de contrat de la boutique sont valables : les statuts du tableau status avec type = 'contracts', à partir desquels le backend effectue également ses lectures, dans toutes les langues, y compris ceux qui sont désactivés (status_active = 0) ; cela masque simplement la sélection dans le backend. Les statuts de commande (/order_statuses) ne sont pas des statuts contractuels. Les identifiants applicables varient d’une boutique à l’autre : consultez-les sur contracts_statuses[], sur GET /Export/JSON/contracts ou sur error.valid_status_ids. contracts_statuses[] ne mentionne que les statuts avec une désignation en allemand ; un statut sans désignation en allemand est néanmoins valable.

L’identifiant est un nombre entier, sous forme de chiffre ou de suite de chiffres (54, "54"; les espaces en marge ne comptent pas). true, [65], "54abc", "1e3", 54.9 ou 54.0 ne sont pas des identifiants.

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]
  }
}

Dans l’importation de contrats, l’enregistrement continue à être compté comme inserted ou updated. L’avertissement figure dans warnings[] de la réponse et dans l’entrée de l’enregistrement dans 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"
  }
]

Le contrat, ses attributs et ses domaines, l’historique de son statut ainsi que ses liens vers les factures et les projets sont supprimés. Les factures et les projets eux-mêmes sont conservés.

# 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 contrat inconnu génère une erreur HTTP 404 lors d’un appel individuel : NOT_FOUND. En traitement par lots, les ID supprimés se trouvent dans deleted_ids, tandis que ceux introuvables apparaissent dans errors[].
• Un corps de requête sans data[].contracts_id, par exemple {"ids": [1, 2]}, ne supprime rien et renvoie un code HTTP 400 MISSING_DATA.