BB2 - Rest Self Service Dokumentation

[frederik.dengler]

In der Benutzerdokumentation für den “brickfox REST Self Service Connector” geht es darum, dass Hilfestellungen und Erklärungen dokumentiert sind um sich selbstständig an brickfox anbinden zu können.

Falls doch einmal Fragen auftreten, bitten wir drum diese im Forum zu stellen: https://forum.brickfox.io/forumdisplay.php?fid=7

Allgemein lässt sich eine Swagger Dokumentation hier aufrufen: https://rest-self-service.stage.bb2.brickfox.io/

Inhaltsverzeichnis
Es stehen folgende Endpunkte zur Verfügung:
/api/login_check - Authentifizierung
/api/request - Daten nach brickfox senden
/api/workflow/trigger - Workflow ausführen
/api/workflow/status - Workflow Status abrufen
/api/workflow/output - Workflow Output Daten abfragen

Authentifizierung
Zur Authentifizierung erhalten Sie einen Benutzernamen und Passwort von uns zur Verfügung gestellt.

Der Request wird dann folgendermaßen aufgebaut:

Code:

/api/login_check - POST
{
  "username": "demo",
  "password": "demo"
}

Beispiele

PHP-Code:

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json'
];
$body = '{
  "username": "demo",
  "password": "demo"
}';

$request = new Request('POST', 'https://rest-self-service.stage.bb2.brickfox.io/api/login\_check', $headers, $body);

$res = $client->sendAsync($request)->wait();

echo $res->getBody(); 


Response

Code:

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2OTQ2OTQ5MTcsImV4cCI6MTY5NDY5ODUxNywicm9sZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJuYW1lIjoic2Vzc21hbm5Ab3NnbWJoLmRlIn0.H\_UMm6kHLaRUt6ngbdUHPT\_lnhpk088mPmeU0SZGBPUxS75aXqir\_eDTQaZ\_uPycMx2Mv-H8TwU6URyl3kW3YDHRFb\_xkx-kmFcHn52ZrZgtlt3PIQx4K75rim\_l19vkA9LfyDmMBSxruxEN6DIW32XtMUpvHw9RyrunZBBREfjpM3ioX-EUwdUoRmaGz4s9Z6LUnd7YB9fzRl2FwznZ38Z04EaZ7-4jVRgx4SO\_sYx8OE6qo3w8J7v9NQOKDYCSIH6KXrPgXuu1vvTelm-Rph2ENKOpwBdG1oBYRF3fdUvCciTCWCHPRSJ7IJxnyjWwa4nUm09XH\_X2eWZ-Pxecgw"
}

Request
Um Daten nach brickfox zu schicken, müssen diese dem BB2 Datenmodel entsprechen, Doku siehe: https://docs.bb2.brickfox.io/ . In diesem Format können wir gewährleisten dass wir die entsprechenden Daten auch importieren können. Zusätzlich wird ein Workflow benötigt, der mit anzugeben ist, damit im Hintergrund asynchron die zur Verfügung gestellten Daten auch verarbeitet werden können.

Der Request wird dann folgendermaßen aufgebaut:

Code:

/api/request - POST - Authorization Bearer Token
{
  "context": {
    "customer": "demo",
    "outputFilePath": "/customer-shared-files/demo/shared/product-data.json",
    "outputType": "json",
    "extra": {
      "workflow": "/customer-shared-files/demo/workflows/production/demo-product-export-to-brickfox.json",
      "data": {
        "expectedClass": "Core\\Entity\\Product\\ProductEntity",
        "elements": [
          {
            "externalId": "1",
            "itemNumber": "SKU1",
            "status": true,
            "deleted": false,
            ...
          }
        ]
      }
    }
  }
}

Beispiele

PHP-Code:

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2OTQ2MTY5OTUsImV4cCI6MTY5NDYyMDU5NSwicm9sZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJuYW1lIjoiZnJlZGVyaWsuZGVuZ2xlckBicmlja2ZveC5jb20ifQ.JFuJ8pCUECEMp9dMZ0xe-4lq0YODogfCyJidboDXhkhSkXSnB1GjzEA1pYGHE-w\_A2Hr-g6iBKz3r2PXAhU5twwqed4Hl\_FeGeKC-lNsfjObI\_d1FKQeY9sLL32e2CGhb7d3nYPdsGpVP3546AlPR7VNOFl-1ET8h1nRznxMt0vkVzLqLiCCpwJ5A2WDwa5BNPSpY10C7EG6siVv1H5yAzKngVFhHdRytVXhsj1caHsEgwRRQeA-CSyKKoDV7jB5SvVkzn5RgCrb4yB6oHZCMAZGcKWb1kc6LguyUsPJlsIz0hRe\_9tOOOUS0SNGkNJRYQF0PZTLmgcxIVNe0uKnVg'
];
$body = '{
  "context": {
    "customer": "demo",
    "outputFilePath": "/customer-shared-files/demo/shared/product-data.json",
    "outputType": "json",
    "extra": {
      "workflow": "/customer-shared-files/demo/workflows/production/demo-product-export-to-brickfox.json",
      "data": {
        "expectedClass": "Core\\Entity\\Product\\ProductEntity",
        "elements": [
          {
            "externalId": "1",
            "itemNumber": "SKU1",
            "status": true,
            "deleted": false,
            ...
          }
        ]
      }
    }
  }
}';
$request = new Request('POST', 'https://rest-self-service.stage.bb2.brickfox.io/api/request', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody(); 


Response

Code:

{
    "success": true,
    "response": {
        "success": true,
        "queueId": "57322ca8-d2ac-41e7-b470-361c7b86f17a"
    },
    "context": {
        ...
    }
}

Die entsprechende Queue ID aus der Response kann genutzt werden um den Workflow Status abzufragen oder später Daten abzuholen.

Workflow triggern
Um einen Workflow zu triggern, um beispielsweise Bestelldaten aus brickfox abzurufen, kann man auch workflows die bekannt sind triggern um im mit einem späteren Request diese Daten dann auch abzurufen.

Der Endpunkt kann aber auch dafür genutzt werden, um Prozesse manuell anzustoßen.

Der Request wird dann folgendermaßen aufgebaut:

Code:

/api/workflow/trigger - POST - Authorization Bearer Token
{
  "context": {
    "customer": "demo",
    "extra": {
      "workflow": "/customer-shared-files/demo/workflows/production/demo-product-update-export-to-brickfox.json"
    }
  }
}

Beispiele

PHP-Code:

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2OTQxNTU1MzUsImV4cCI6MTY5NDE1OTEzNSwicm9sZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJuYW1lIjoiZnJlZGVyaWsuZGVuZ2xlckBicmlja2ZveC5jb20ifQ.ZlmP2ei\_65JHJXHvjkDcSIFEdNmK55Y5avMxUqMqwgVYDRNWkxYIuCCtyzWZhJm40ZBZEC2O-NlNiku3i7HPxGV4d1DjN5SzQt4VVwwkf2jGIIj0rafM5avhib4ZzjC\_XeGdar5vStcodW70VMB6KHrJsCDR\_H2derPG6xrQDDtrmiHdCdRSXEq8JdRBvo9Xj4UXcmGkaXqVepMY8x\_HBqA8niC0CHZ161kIEsouVsgt-i4DrLeSKzMvdfSfgSCqOanAjprnfp5v26iVVyyzI636DKT23Gc\_oyV9gjAC4Pp9tjjhbCvpgE05h85LF8Bc7urmgF-\_FGuGTNiW9UIdrg'
];
$body = '{
  "context": {
    "customer": "demo",
    "extra": {
      "workflow": "/customer-shared-files/demo/workflows/production/demo-product-update-export-to-brickfox.json"
    }
  }
}';
$request = new Request('POST', 'https://rest-self-service.stage.bb2.brickfox.io/api/workflow/trigger', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody(); 


Response

Code:

{
    "success": true,
    "response": {
        "success": true,
        "queueId": "37ce910a-5680-44aa-b1d2-578f3a612e47",
        "entries": null
    },
    "context": {
        "customer": "demo",
        "extra": {
            "workflow": "/customer-shared-files/demo/workflows/production/demo-product-export-to-brickfox.json"
        }
    }
}

Die entsprechende Queue ID aus der Response kann genutzt werden um den Workflow Status abzufragen oder später Daten abzuholen.

Workflow Status Abfrage
Um einen Workflow Status abzufragen, kann folgender Endpunkt verwendet werden. Um beispielsweise zu überprüfen, ob der Prozess schon durchgelaufen ist, oder Probleme aufgetreten sind.

Der Request wird dann folgendermaßen aufgebaut:

Code:

/api/workflow/status - POST - Authorization Bearer Token
{
  "context": {
    "customer": "demo",
    "extra": {
        "queueId": "8b680242-5e58-4f1b-99bd-c2cac3d0dffc"
    }
  }
}

Beispiele

PHP-Code:

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2OTQ2OTQ5MTcsImV4cCI6MTY5NDY5ODUxNywicm9sZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJuYW1lIjoic2Vzc21hbm5Ab3NnbWJoLmRlIn0.H\_UMm6kHLaRUt6ngbdUHPT\_lnhpk088mPmeU0SZGBPUxS75aXqir\_eDTQaZ\_uPycMx2Mv-H8TwU6URyl3kW3YDHRFb\_xkx-kmFcHn52ZrZgtlt3PIQx4K75rim\_l19vkA9LfyDmMBSxruxEN6DIW32XtMUpvHw9RyrunZBBREfjpM3ioX-EUwdUoRmaGz4s9Z6LUnd7YB9fzRl2FwznZ38Z04EaZ7-4jVRgx4SO\_sYx8OE6qo3w8J7v9NQOKDYCSIH6KXrPgXuu1vvTelm-Rph2ENKOpwBdG1oBYRF3fdUvCciTCWCHPRSJ7IJxnyjWwa4nUm09XH\_X2eWZ-Pxecgw'
];
$body = '{
  "context": {
    "customer": "demo",
    "extra": {
      "queueId": "8b680242-5e58-4f1b-99bd-c2cac3d0dffc"
    }
  }
}';
$request = new Request('POST', 'https://rest-self-service.stage.bb2.brickfox.io/api/workflow/status', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody(); 


Response

Code:

{
    "success": true,
    "response": {
        "id": "8b680242-5e58-4f1b-99bd-c2cac3d0dffc",
        "entries": [
            {
                "queueId": "8b680242-5e58-4f1b-99bd-c2cac3d0dffc",
                "id": "ab5b33fb-bde9-4805-ad77-102b6fe78517",
                "service": "brickfox-product-connector-service",
                "route": "Transform-Product-Data-To-Brickfox",
                "description": "Transforming product data to brickfox product data",
                "order": 1,
                "customer": "demo",
                "context": {
                    "customer": "demo",
                    "inputFilePath": "/customer-shared-files/demo/shared/product-data-\*.json",
                    "outputFilePath": "/customer-shared-files/demo/shared/brickfox-product-data.xml",
                    "inputType": "json",
                    "outputType": "xml",
                    "extra": {
                        "handleType": "product-export"
                    }
                },
                "startDateTime": "2023-09-14 09:40:50",
                "endDateTime": "2023-09-14 09:40:51",
                "success": false,
                "finished": true
            },
            ...
        ],
        "finished": true
    },
    "context": {
        "customer": "demo",
        "extra": {
            "queueId": "8b680242-5e58-4f1b-99bd-c2cac3d0dffc"
        }
    }
}

Workflow Output Daten Abfrage
Sobald ein Workflow beispielsweise Bestellexport aus brickfox abgeschlossen ist, können die Daten auch abgerufen werden um diese im eigenen System z.B. weiterzuverarbeiten. Diese Daten kommen auch im BB2 Datenmodel Format an, siehe https://docs.bb2.brickfox.io/ .

Der Request wird dann folgendermaßen aufgebaut:

Code:

/api/workflow/output - POST - Authorization Bearer Token
{
  "context": {
    "customer": "demo",
    "inputFilePath": "/customer-shared-files/demo/shared/products-\*.json",
    "inputType": "json",
    "extra": {
        "queueId": "57322ca8-d2ac-41e7-b470-361c7b86f17a"
    }
  }
}

Beispiele

PHP-Code:

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2OTQ2MTQ3OTgsImV4cCI6MTY5NDYxODM5OCwicm9sZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJuYW1lIjoiZnJlZGVyaWsuZGVuZ2xlckBicmlja2ZveC5jb20ifQ.iwuTxCuNpa\_WcLpKR8PncmHYah-MvYE9vLk9wmbUvH8owwfBA5TaWQAknea3\_tGb6-qxwD6E2I4Ks7KvuQWgwmJ2XUNjQrGY-lDfTN12d0C0wE6ltUu1QtNbResV1XGk1kZfn6\_KlCM1zvXs\_s2zhg5qdKzfaf7AFVQRf3rpjIUwMF-9-wIQKL\_\_AJS5uvYe-Fg6gFj6FgHSnZSpnkGoSeKvxcg9h3T-COnQJHfeXFSfHOwRgeVjchY9Qo9Hf2AlKgt84pts9rBsn\_Bp854oJTCtR3U0cUI1C71SM1lPjAZPHaDHYKeJ4xPRaCuFTM82OvD4PvCWZwyhKoRhwXsGSA'
];
$body = '{
  "context": {
    "customer": "Demo",
    "inputFilePath": "/customer-shared-files/demo/shared/products-\*.json",
    "inputType": "json",
    "extra": {
      "queueId": "be151210d10a450a96bd379dcadd86e5"
    }
  }
}';
$request = new Request('POST', 'https://rest-self-service.stage.bb2.brickfox.io/api/workflow/output', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody(); 


Response

Code:

{
    "success": true,
    "response": [
        {
            "expectedClass": "Core\\Entity\\Product\\ProductEntity",
            "elements": [
                {
                    "externalId": "1",
                    "itemNumber": "SKU1",
                    "status": true,
                    "deleted": false,
                    ...
                }
            ]
        }
    ],
    "context": {
        "customer": "demo",
        "inputFilePath": "/customer-shared-files/demo/shared/products-\*.json",
        "inputType": "json",
        "extra": {
            "queueId": "57322ca8-d2ac-41e7-b470-361c7b86f17a"
        }
    }
}