This documentation covers some
Table of Contents | ||
---|---|---|
|
How to use this documentation
This documentation provides a high level overview of some of the common use cases for the 3YOURMIND RESTful API, which are outlined in the table of contents below. Where relevant, these use cases include links to endpoints as described in the API documentation.
Table of Contents | ||
---|---|---|
|
Programmatically upload files and redirect your users to the 3YOURMIND frontend
If your application generates 3D data and you want to use the Order Management System, you may want to upload 3D models and redirect the user to the 3YOURMIND platform.
The workflow for this is:
Let your users click on a button like "Order with 3YOURMIND"
Upload a file with the Upload 3D File endpoint.
Redirect the user to the URL returned in the response (or open a browser with the URL)
Place Orders Programmatically
This is useful when the order is created in another system and should be placed in the 3YOURMIND system for tracking and processing.
You can place entire orders programmatically. There are 2 different workflows for creating orders:
Place order with User Panel API
This is the older legacy API. Use it if you want to offer your customers a UI for creating orders, that is very similar to the 3yourmind User Panel.
Place order with Service Panel API
This is the newer API, it is easier to work with. Use it if you want to interface with the 3yourmind API, from some other backend service, or if you already have your own UI for order creation.
Place order with User Panel API
Do all the steps in Upload a file [use-case]
For every line: Update the basket line to set an offer and post-processing.
(optional) Create Shipping and billing addresses.
(optional) Check the order total with the Get Basket Price endpoint.
Create order for basket. Depending on your Printing Service, you will have to choose:
way of delivery
and a Payment method.
Place order with Service Panel API
Choose user for which to create order (from all users of the service). Fetch users - GET
Assign the previous chosen user to the basket Update basket with user - PATCH
Get addresses of the user, choose address for this order Fetch addresses of user - GET
Choose payment method Fetch available payment methods - GET
Choose shipping method Fetch available shipping methods - GET
Choose material for this line Fetch available materials - GET
Update print price and material/offer and post processings for this line - PATCH
Wait until file upload has finished, periodically call this endpoint (each 1s): Fetch the file upload status - GET
Submit the final order, that links all previous steps together
See the following code, as an example of all the steps. It is written as JetBrains .http file format, even if you can not execute with your IDE, you can still read the code examples in it.
Code Block |
---|
###
< {%
client.global.set("token", "dd247ae0d9cddcefa32e3ef502c4798b6ae531d8");
client.global.set("service_id", "1");
%}
GET http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/internal-ordering/users/?search=Ortega
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
> {%
client.global.set("customer_id", response.body.results[0].id);
client.log(JSON.stringify(client.global["vars"]["customer_id"]))
%}
###
POST http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/baskets/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
> {%
client.global.set("basked_id", response.body.id);
client.log(JSON.stringify(client.global["vars"]["basked_id"]))
%}
###
PATCH http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/baskets/{{basked_id}}/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
{
"customer_id": {{customer_id}}
}
###
GET http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/internal-ordering/users/{{customer_id}}/addresses/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
> {%
client.global.set("customer_address_id", response.body[2].id);
client.log(JSON.stringify(client.global["vars"]["customer_address_id"]))
%}
###
GET http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/payment-methods/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
> {%
client.global.set("payment_method_id", response.body[0].id);
client.log(JSON.stringify(client.global["vars"]["payment_method_id"]))
%}
###
GET http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/shipping-methods/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
> {%
client.global.set("shipping_method_id", response.body[0].id);
client.log(JSON.stringify(client.global["vars"]["shipping_method_id"]))
%}
###
GET http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/offers/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
> {%
client.global.set("offer_id", response.body[0].id);
client.log(JSON.stringify(client.global["vars"]["offer_id"]))
%}
###
POST http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/baskets/{{basked_id}}/lines/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
> {%
client.global.set("line_id", response.body.id);
client.log(JSON.stringify(client.global["vars"]["line_id"]))
%}
###
PATCH http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/baskets/{{basked_id}}/lines/{{line_id}}/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
{
"offer_id": {{offer_id}},
"postProcessings": [],
"unitPrintPrice": "12.34"
}
###
POST http://multi.my.3yd/api/v2.0/files/
Content-Type: multipart/form-data; boundary=boundary
--boundaryd
Content-Disposition: form-data; name="file"; filename="test_areas (copy).stl"
Content-Type: model/x.stl-binary
< ./cube_10_inch.stl
--boundary
Content-Disposition: form-data; name="basket_id"
{{basked_id}}
--boundary
Content-Disposition: form-data; name="line_id"
{{line_id}}
--boundary
Content-Disposition: form-data; name="unit"
inch
###
GET http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/baskets/{{basked_id}}/lines/{{line_id}}/file-status/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
###
POST http://multi.my.3yd/api/v2.0/service-panel/services/{{service_id}}/internal-ordering/orders/
Accept: application/json
Content-Type: application/json
Authorization: Token {{token}}
{
"additionalInformation": {
"reference": "some test reference"
},
"basketId": {{basked_id}},
"billingAddressId": {{customer_address_id}},
"pickupLocationId": null,
"fees": [],
"shippingPrice": "12.34",
"shipping": {
"methodId": {{shipping_method_id}},
"addressId": {{customer_address_id}},
"deliveryInstructions": "string"
},
"payment": {
"methodId": {{payment_method_id}},
"authorizedAmount": "12.34",
"currency": "EUR",
"details": { }
},
"voucherCode": null,
"userId": {{customer_id}}
} |
example.http
Place Orders from a Catalog Item
Instead of uploading 3D files, you can order files from the catalog.
Instead of uploading the 3D Files, you can add items from the Catalog to the basket. The workflow to place an order from the Digial catalog is as follows:
Create a basket line with an
catalogItemId
in the payload.(optional) Update the basket line and overide the offer and post-processing.
(optional) Create Shipping and billing addresses.
(optional) Check the order total with the Get Basket Price endpoint.
Create / List Customers Programmatically
Either create a customer data set (by creating a user and disabling email sending for that user) or invite a new user to use the platform. All existing customers can also be obtained.
The Organization Users endpoints are for creating and updating User information. In order to use those endpoints, the user with the ApiToken needs to have the "Organization Admin" Role.
Further information about this use case can be found in the linked documentation: Organization Users
Get Prices for 3D Models
You can obtain prices for 3D models using the REST API. For this, please follow the steps outlined below:
Complete all the steps in Upload a file [use-case]
Get pricing information by reaching the below endpoints:
Materials using List materials
Services with List offers
Post-processings with Get an offer
Prices are calculated by the 3YOURMIND pricing engine which can be configured / scripted in the service panel.
More details for each use case listed below, can be found by clicking on the respective title. In some cases, these more detailed descriptions will include examples for how the API request can be formatted. Where relevant, the required endpoints will be listed in the use case description and the link to the endpoint description, as defined in the API documentation, will be included.
If there is a common use case which you think would be valuable to be included as part of this documentation, or if you have any questions about the scenarios outlined below, please feel free to reach out to the Technical Support Team with your queries or suggestions.
Authentication
An API token is required to use the REST API and this token is generated in the admin panel (www..your-domain.com/admin). In the admin panel, open the list of users and click ‘Create token’ next to the chosen user.
...
Please ensure that this user profile has the necessary permissions to complete the actions specified in the API request. More information on User Roles, can be found in the following documentation: Roles & User Rights.
Customers who do not have access to the admin panel need to contact the 3YOURMIND support team to obtain a token.
The API Token can be used as outlined in the API Documentation: Authentication.
API Use Cases
Create a Quote based on a RequestForQuote while choosing a custom price for the Quote-Lines
Creating a Quote from a Request, whilst specifying a new price for the newly created Quote.
Upload an Internal Attachment
Upload an attachment internally (e.g. to a Quote, Order, Request etc.).
Edit a Quote
Create a new Quote from an existing Quote with specified edits.
Edit the attribute of a Basket-Line
Examples of how to edit the attributes of the basket-lines, which are created when editing the existing Quote.
Upload a File into a Basket
Create a basket and upload a 3D file to this newly created basket.
Programmatically Upload Files and Redirect your Users to the 3YOURMIND Frontend
If your own application generates 3D data and you want to use the Order Management System, you can upload 3D models and redirect the user to the 3YOURMIND platform.
Place Orders Programmatically
This is useful when the order is created in another system and this order should be placed in the 3YOURMIND system for tracking and processing.
Place Orders from a Catalog Item
Add items from the Digital Catalog to a basket and place an order.
Create / List Customers Programmatically
Create users in the platform and specify their user settings, as well as generating a list of all users of the platform.
Get Prices for 3D Models
Upload 3D files to a basket and retrieve the prices for materials, services and post-processings generated by the 3YOURMIND pricing engine for these uploaded files.
Analyze and Optimize 3D Models
Upload 3D files to get printability information (wall thickness check, bounding box check, multi-shell check), geometric information (volume, area, dimensions, convex hull, concave hull, etc.) and the optimized 3D file (using our mesh healing algorithms).
After uploading a 3D file our backend optimizes and analyzes it. You can then retrieve its parameter and printability details.
...
Upload a 3D File, using option one in the linked API specification. You do not need to redirect the user to our frontend.
...
Wait until the file has been processed by repeatedly requesting Get File Optimization Status.
Use any of the other 3D Files endpoints to get information about:
...
Printability
...
3D model parameter, like volume and surface area
...
a basket for analysis and optimization and retrieve the files’s printability and geometric information, as well as the optimized 3D file.
Transfer Sales Transactions into Another System (ERP, CRM, etc.)
Transfer data from the 3YOURMIND platform to your own system (e.g. CRM, ERP, Accounting etc.) when a user places requests, quotes or orders.