Einrichtung

Bei der Einrichtung können unterschiedliche URLs hinterlegt werden, an welche die Daten übergeben bzw. von welchen die Daten angefordert werden sollen.

Sollte eine bestimmte URL nicht festgelegt sein, wird die Fallback URL verwendet.

Datenaustausch

Für den Datenaustausch werden die in den Contracts vorgegebene Formate 1:1 verwendet. Die Nutzlast wird hierbei als JSON kodiert und an die jeweils hinterlegte URL gesendet. Alle Antworten mit den Statuscodes 2xx werden als erfolgreich gewertet. Wird im Contract ein Rückgabewert erwartet, so sind diese Daten als JSON im Body zurückzugeben.

Beispiel

Als Beispiel einmal die OrderRequester Schnittstelle. Diese wird verwendet, damit ein System Bestellungen abrufen kann.

export interface OrderRequester {
    processOrdersRequest(request: HttpRequest): Promise<QueryOrdersRequest>;
    provideOrders(result: QueryOrdersResult): Promise<HttpResponse>;
}

Zuerst wird processOrdersRequest aufgerufen, welche im Normalfall die SodaSync unbekannten Daten in ein QueryOrdersRequest Model umwandelt. Mit diesem Model wird dann das System aufgerufen, von welchem die Bestellungen abgeholt werden sollen. Dieses System gibt die Daten als QueryOrdersResult zurück.

Anschließend wird provideOrders aufgerufen, um die Daten entsprechend dem anfragenden System aufbereitet zu übergeben.

Wenn du nun das anfragende System anbinden möchtest, musst du Daten im folgenden Format als HTTP Request senden:

POST https://app.soda-sync.com/api/v1/inbound/X/Y/Z/orders-request/orders-provide
Content-Type: application/json

{
  "pageToken": "optional, token der nächsten seite"
  "pageSize": 10,
  "filters": [
    {"field": "id", "operation": "eq", "value": "123"}
  ]
}

Als Antwort werden dann Daten wie im Folgenden zurückgegeben (in diesem Fall Dummy Daten):

{
  "pageSize": 10,
  "nextPageToken": "mR3vpaxIpkJk",
  "data": [
    {
      "id": "55373c7b-b52a-4ac6-ba85-2cba86409e3f",
      "items": [
        {
          "sku": "SZUP",
          "name": "Generic Granite Fish",
          "description": "Andy shoes are designed to keeping in mind durability as well as trends, the most stylish range of shoes & sandals",
          "amount": 2,
          "id": "4f5c3d0a-b0f3-4dd7-9398-f117b5272df9",
          "singleNetPrice": {
            "value": 47300,
            "currencyCode": "HUF",
            "divisor": 100
          },
          "singleGrossPrice": {
            "value": 47300,
            "currencyCode": "HUF",
            "divisor": 100
          },
          "taxRate": 0,
          "attributeValues": {
            "unmapped-random-attribute": "6jEUiq"
          }
        }
      ],
      "orderDate": "2022-11-27T13:27:34.143Z",
      "orderNumber": "1111",
      "shipments": [
        {
          "id": "10216ede-d1e4-4876-b461-4d22b06e6563",
          "method": "Triple-buffered",
          "date": "2023-05-22T22:26:00.384Z",
          "sourceCountryCode": "AL",
          "netPrice": {
            "value": 93700,
            "currencyCode": "HUF",
            "divisor": 100
          },
          "grossPrice": {
            "value": 93700,
            "currencyCode": "HUF",
            "divisor": 100
          },
          "taxRate": 0,
          "attributeValues": {
            "unmapped-random-attribute": "TXKW7t"
          }
        }
      ],
      "status": "OPEN",
      "paymentStatus": "OPEN",
      "transactions": [
        {
          "id": "ecfc9e4f-dce9-4e68-89ea-fbb6c070cb10",
          "method": "american_express",
          "type": "PAYMENT",
          "amount": {
            "value": 96500,
            "currencyCode": "HUF",
            "divisor": 100
          },
          "date": "2023-04-05T18:49:17.797Z",
          "attributeValues": {
            "unmapped-random-attribute": "vUq7Ab"
          }
        }
      ],
      "customer": {
        "vatId": "HU5556751148",
        "mailAddress": "Brooke_Heidenreich56@example.net",
        "phoneNumber": "428-802-6358 x810",
        "attributeValues": {
          "unmapped-random-attribute": "ebshjT"
        }
      },
      "deliveryAddress": {
        "company": "Senger, Stamm and Hamill",
        "firstName": "Alejandra",
        "surname": "Jenkins",
        "line2": "Apt. 417",
        "street": "Toby Terrace",
        "houseNumber": "9101",
        "zipCode": "64733",
        "city": "Leathaborough",
        "countryCode": "AQ",
        "state": "Alaska",
        "attributeValues": {
          "unmapped-random-attribute": "LQkyG9"
        }
      },
      "invoiceAddress": {
        "company": "Hessel, Hartmann and Raynor",
        "firstName": "Kathleen",
        "surname": "Effertz",
        "line2": "Suite 517",
        "street": "Crona Station",
        "houseNumber": "5255",
        "zipCode": "74772-5075",
        "city": "Metzberg",
        "countryCode": "HM",
        "state": "Ohio",
        "attributeValues": {
          "unmapped-random-attribute": "AfpNDg"
        }
      },
      "attributeValues": {
        "unmapped-random-attribute": "dFgXX7"
      }
    }
  ]
}

Implementierst du die hingegen die Gegenseite des Contracts, erhältst du eine POST Request mit dem ersten Datenauszug oben und musst die Antwort wie im zweiten Format liefern.

Zusätzlich zu dem Body werden auch noch zwei Header gesendet:

• X-Soda-Sync-Interface: Hier drin steht der Name der Schnittstelle, bzw. des AppFeature (siehe SDK)
• X-Soda-Sync-Step: Hier drin steht der aktuelle Schritt in der Abarbeitung. In der Regel handelt es sich hierbei um den Namen der Methode in der Schnittstelle.