Vertrags-Endpunkt (Contracts)

v2.7.0 · CRUD · Verträge & Abos

Contracts

Verträge und Abonnements mit Attributen, Domains, Status-History und Bestellverknüpfungen verwalten. Unterstützt dediziertes Status-Update per Sub-Endpoint.

GET    /Export/JSON/contracts
POST   /Import/JSON/contracts
PUT    /Import/JSON/contracts
PUT    /Import/JSON/contracts/{id}/status
DELETE /Delete/JSON/contracts/{id}

Endpoints

MethodeEndpointScopeBeschreibung
GET/Export/JSON/contractscontracts:readAlle Verträge auflisten (mit Filtern)
GET/Export/JSON/contracts/{id}contracts:readEinzelnen Vertrag abrufen
POST/Import/JSON/contractscontracts:writeNeuen Vertrag anlegen
PUT/Import/JSON/contractscontracts:writeBestehenden Vertrag aktualisieren
PUT/Import/JSON/contracts/{id}/statuscontracts:writeNur Status ändern (eigener Scope)
DELETE/Delete/JSON/contracts/{id}contracts:deleteEinzeln per ID löschen (kaskadierend)
DELETE/Delete/JSON/contractscontracts:deleteBulk-Löschung per JSON-Body

Query-Filter (GET)

ParameterBeschreibungBeispiel
?status=Vertragsstatus (1–7)?status=1 (Aktiv)
?customer_id=Kunden-ID?customer_id=42
?product_id=Produkt-ID?product_id=100
?interval=Intervall (1=Jährlich, 12=Monatlich, …)?interval=12
?date_from=Startdatum (YYYY-MM-DD)?date_from=2025-01-01
?date_to=Enddatum (YYYY-MM-DD)?date_to=2025-12-31

Datenstruktur

Hauptfelder

FeldTypBeschreibung
contracts_idINTPrimärschlüssel
customers_idINTKunden-ID
products_idINTProdukt-ID
contracts_statusINTStatus (1=Aktiv, 2=Pausiert, 3=Gekündigt, …)
contracts_intervalINTIntervall (1=Jährlich, 2=Halbjährlich, 4=Vierteljährlich, 12=Monatlich)
contracts_priceDECIMALNettobetrag
contracts_date_addedDATETIMEErstellungsdatum
contracts_date_startDATEVertragsbeginn
contracts_date_endDATEVertragsende (NULL = unbefristet)
current_period_date_beginDATEBeginn der aktuellen Abrechnungsperiode
current_period_date_endDATEEnde der aktuellen Abrechnungsperiode

Verschachtelte Relationen

RelationBeschreibung
attributes[]Vertragsattribute (Key-Value-Paare)
domains[]Zugeordnete Domains
status_history[]Statusänderungen mit Datum und Kommentar
orders[]Verknüpfte Bestellungen

OAuth2 Scopes

ScopeBerechtigung
contracts:readVerträge lesen/exportieren
contracts:writeVerträge erstellen und aktualisieren
contracts:deleteVerträge löschen
contracts:writeNur Status eines Vertrags ändern

Beispiele

Export (GET)

curl -s "https://shop.de/xpanel/xoport/Export/JSON/contracts?status=1&interval=12" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[0]'

# Response:
{
  "contracts_id": 1,
  "customers_id": 42,
  "products_id": 100,
  "contracts_status": 1,
  "contracts_status_text": "Aktiv",
  "contracts_interval": 12,
  "contracts_interval_text": "Monatlich",
  "contracts_price": "29.90",
  "attributes": [
    {"id": 1, "key": "Lizenztyp", "value": "Enterprise"}
  ],
  "domains": [
    {"id": 1, "domain": "kunde.de", "active": 1}
  ],
  "status_history": [...],
  "orders": [...]
}

Import (POST)

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": [{
      "customers_id": 42,
      "products_id": 100,
      "contracts_status": 1,
      "contracts_interval": 12,
      "contracts_price": "29.90",
      "attributes": [
        {"key": "Lizenztyp", "value": "Enterprise"}
      ],
      "domains": [
        {"domain": "kunde.de"}
      ]
    }]
  }'

Status-Update (PUT)

# Eigener Endpoint mit separatem Scope
curl -s -X PUT "https://shop.de/xpanel/xoport/Import/JSON/contracts/1/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contracts_status": 3, "comment": "Kündigung per API"}'

Kaskadierendes Löschen (DELETE)

# Löscht Vertrag inkl. Attribute, Domains, Status-History
curl -s -X DELETE "https://shop.de/xpanel/xoport/Delete/JSON/contracts/1" \
  -H "Authorization: Bearer $TOKEN"

# Bulk-Löschung:
curl -s -X DELETE "https://shop.de/xpanel/xoport/Delete/JSON/contracts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": [1, 2, 3]}'