API TUTORIAL – CREATE CONSTRUCTIBLES

Intro

This document provides a step-by-step guide on how to create an assembly using the produuz.it API V2. The assembly creation involves several steps, including project and batch creation, finding an assembly design, and making a call to the assemblies endpoint with the required UUIDs. The workflow for modules is similar.

INFO

The base URL for the produuz.it API V2 is: https://back.produuz.it/api/v2/

Step 1: Project Creation/Retrieval

ALL RETRIEVAL

If you don't have the project uuid, find it from your own data. You can fetch all the projects and look for it:

Endpoint: /api/v2/company/projects/

Method: GET.
Request Body: Empty.
Response: Paginated list of project objects, in results.

Example Response Payload

json

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "ifc_parsing_setup": "b3f44b0e-2e75-45ad-8a5d-148f70883fe1",
      "btl_parsing_setup": null,
      "uuid": "0549be70-e2f5-4227-86a1-bfdb229e5460",
      "created": "2023-10-19T09:04:07.222371Z",
      "modified": "2023-10-19T09:04:07.222393Z",
      "name": "TEST_HOUSE",
      "client_name": "connectinq",
      "project_number": "test_1",
      "super_project": "Test_Street",
      "phases": ["Phase_1"],
      "meta": {},
      "delivery_date": null,
      "start_date": null,
      "archived": false
    },
    {
      //... other project
    },
    {
      //... other project
    }
  ]
}

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "ifc_parsing_setup": "b3f44b0e-2e75-45ad-8a5d-148f70883fe1",
      "btl_parsing_setup": null,
      "uuid": "0549be70-e2f5-4227-86a1-bfdb229e5460",
      "created": "2023-10-19T09:04:07.222371Z",
      "modified": "2023-10-19T09:04:07.222393Z",
      "name": "TEST_HOUSE",
      "client_name": "connectinq",
      "project_number": "test_1",
      "super_project": "Test_Street",
      "phases": ["Phase_1"],
      "meta": {},
      "delivery_date": null,
      "start_date": null,
      "archived": false
    },
    {
      //... other project
    },
    {
      //... other project
    }
  ]
}

FILTERED RETRIEVAL

You can also filter them with query parameters:

Endpoint: /api/v2/company/projects/?name=my_project

This also returns a list, even if only one project matches the query.

CREATION

If the project does not exist, you should create it. To create a project:

Endpoint: /api/v2/company/projects/

Method: POST.
Request Body: JSON object with project details.
Response: Project details including the project UUID.

Example Request Payload

json

{
  "name": "TEST_HOUSE",
  "super_project": "Test_Street",
  "client_name": "connectinq",
  "project_number": "test_1",
  "delivery_date": null,
  "start_date": null,
  "standard_library": false
}

{
  "name": "TEST_HOUSE",
  "super_project": "Test_Street",
  "client_name": "connectinq",
  "project_number": "test_1",
  "delivery_date": null,
  "start_date": null,
  "standard_library": false
}

Example Response Payload

json

{
  "ifc_parsing_setup": "b3f44b0e-2e75-45ad-8a5d-148f70883fe1",
  "btl_parsing_setup": null,
  "uuid": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "created": "2023-10-19T09:04:07.222371Z",
  "modified": "2023-10-19T09:04:07.222393Z",
  "name": "TEST_HOUSE",
  "client_name": "connectinq",
  "project_number": "test_1",
  "super_project": "Test_Street",
  "phases": ["Phase_1"],
  "meta": {},
  "delivery_date": null,
  "start_date": null,
  "archived": false
}

{
  "ifc_parsing_setup": "b3f44b0e-2e75-45ad-8a5d-148f70883fe1",
  "btl_parsing_setup": null,
  "uuid": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "created": "2023-10-19T09:04:07.222371Z",
  "modified": "2023-10-19T09:04:07.222393Z",
  "name": "TEST_HOUSE",
  "client_name": "connectinq",
  "project_number": "test_1",
  "super_project": "Test_Street",
  "phases": ["Phase_1"],
  "meta": {},
  "delivery_date": null,
  "start_date": null,
  "archived": false
}

(may contain more data in some cases)

In the "uuid" param of the response you have your new project UUID.

Note that you get a list of available "phases" in the project, in the project's order. project_phases gives the same phases with their uuid and order.

If you are looking for standard libraries (only for later assembly_design retrieval), use the endpoint /api/v2/company/standard_libraries/ instead. The workflow is the same.

Step 2: Batch Creation/Retrieval

Some facts about produuz.it batches:

An assembly/module always needs a batch. If the company wants to work without batches, placeholder batches are created.
The phase is a string. The default Phase_1 can be used for simplicity. If you send a phase name the project does not have yet, the phase is added at the end of the project's phases.
Each batch also returns phase_uuid, the id of its phase. It stays the same when the phase is renamed, so use it if you store phases on your side. When you create or update a batch you can send either phase (a name) or phase_uuid (one of the project's phases). If you send both, phase_uuid is used.
The production line is set to the batch, not to the assembly/module itself. So at least one batch per desired production line will be needed in a project. (Ex: BATCH_PL1, BATCH_PL2, BATCH_PL3,…).

The company is free to organize phases and batches as it likes.

RETRIEVAL

To retrieve batches, use the following endpoint:

Endpoint: /api/v2/constructibles/batches/?project=<project_uuid>

Method: GET.
Request Body: Empty.
Response: Paginated list of batches including uuids.

CREATION

To create a batch object, use the following endpoint:

Endpoint: /api/v2/constructibles/batches/

Method: POST.
Request Body: JSON object with batch details including the project UUID.
Response: Batch details including the batch UUID.

Example Request Payload

json

{
  "project": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "phase": "Phase_1",
  "name": "Batch_1"
}

{
  "project": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "phase": "Phase_1",
  "name": "Batch_1"
}

Example Response Payload

json

{
  "project": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "production_line": null,
  "uuid": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "created": "2023-10-19T09:24:12.082495Z",
  "modified": "2023-10-19T09:24:12.082514Z",
  "name": "Batch_1",
  "phase": "Phase_1",
  "phase_uuid": "5f0c2a8e-3b7d-4c1a-9e2f-6a4b8d1c0e73",
  "priority": 0,
  "show_in_viewer": true,
  "start_date": null,
  "delivery_date": null,
  "pl_ordering": 0,
  "company_calculated_time": 0,
  "use_ct_schedule": false,
  "task_subset": ""
}

{
  "project": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "production_line": null,
  "uuid": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "created": "2023-10-19T09:24:12.082495Z",
  "modified": "2023-10-19T09:24:12.082514Z",
  "name": "Batch_1",
  "phase": "Phase_1",
  "phase_uuid": "5f0c2a8e-3b7d-4c1a-9e2f-6a4b8d1c0e73",
  "priority": 0,
  "show_in_viewer": true,
  "start_date": null,
  "delivery_date": null,
  "pl_ordering": 0,
  "company_calculated_time": 0,
  "use_ct_schedule": false,
  "task_subset": ""
}

UPDATING

Any of the fields of the batch object can be passed in the POST create request. They can also be updated later with a PUT request that holds only the fields to change (PUT is always a partial update). For example, to set a new production line on the batch:

Endpoint: /api/v2/constructibles/batches/94d9c646-8e2d-4ac0-b073-aff1aed2b3d7/

Method: PUT.
Request Body: partial JSON object.
Response: Full batch.

Example Request Payload

json

{
    "production_line": "b6e25a9c-bf2f-4838-ac1d-a204932a698e"
}

{
    "production_line": "b6e25a9c-bf2f-4838-ac1d-a204932a698e"
}

You can also pass the production line in the creation POST request.

Step 3: Assembly Design Retrieval

Find an assembly design to reference, either from the current project or from another project. A standard library is also a project, so for standard panels pass the standard library uuid as the project uuid.

Endpoint: /api/v2/constructibles/assembly_designs/?project=<project_uuid_or_stdlib_uuid>

Method: GET to retrieve assembly designs.

Query Parameters: Project UUID if filtering by project.
Response: Paginated list of assembly designs with UUIDs.

If needed, you can also add the name query filter to get a shorter list:

Endpoint: /api/v2/constructibles/assembly_designs/?project=<project_uuid>&name=<design_name>

Step 4: Assembly Creation

You are ready to create an assembly once you have:

design : Assembly design UUID.
batch : Batch UUID.

Also you may want to add:

client_order_id : Order ID coming from external management system.
scheduled_prod_date : Scheduled date for the production.
priority : Integer that represents the priority of the assembly in the batch, or in the day for companies that manage production by date.

Make a call to the assemblies endpoint with the data:

Endpoint: /api/v2/constructibles/assemblies/

Method: POST.
Request Body: JSON object with at least basic data.
Response: The full assembly JSON object.

Example Request Payload

json

{
  "batch": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "design": "b715f3b3-7007-47d2-872b-20eb46d383a7",
  "scheduled_prod_date": "2023-10-19",
  "client_order_id": "or863-12"
}

{
  "batch": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "design": "b715f3b3-7007-47d2-872b-20eb46d383a7",
  "scheduled_prod_date": "2023-10-19",
  "client_order_id": "or863-12"
}

Example Response Payload

json

{
  "batch": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "module": null,
  "design": "b715f3b3-7007-47d2-872b-20eb46d383a7",
  "uuid": "8f43556f-ee33-4aaf-b0b8-028f3d3d46dd",
  "created": "2023-06-03T22:58:49.281997Z",
  "modified": "2023-06-05T08:02:21.160681Z",
  "status": "waiting",
  "stations_status": {},
  "meta": {},
  "priority": 48,
  "scheduled_prod_date": "2023-10-19",
  "client_order_id": "or863-12",
  "parent_assembly": null
}

{
  "batch": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "module": null,
  "design": "b715f3b3-7007-47d2-872b-20eb46d383a7",
  "uuid": "8f43556f-ee33-4aaf-b0b8-028f3d3d46dd",
  "created": "2023-06-03T22:58:49.281997Z",
  "modified": "2023-06-05T08:02:21.160681Z",
  "status": "waiting",
  "stations_status": {},
  "meta": {},
  "priority": 48,
  "scheduled_prod_date": "2023-10-19",
  "client_order_id": "or863-12",
  "parent_assembly": null
}

Bulk Create

Several constructibles can be created in a single request:

Endpoint: /api/v2/constructibles/actuals/bulk_create/

Method: POST.
Request Body: One creation payload, or a list of them.
Response: One result per payload (a list when you sent a list).

The payload format is chosen with the schema query parameter, which is required. An unknown or missing schema answers 404 with {"status": "unknown_schema"}.

Custom schema 1 (hm_sap)

This schema creates the constructible and gets or creates its related objects (project, standard library, design, batch). The production line must already exist. It expects the following props:

project : Project number. Will pick this project, or create if does not exist.
projectname : Will be used only if project creation is needed.
super_project (optional): Used only if project creation is needed. Defaults to FROM_API.
stdlib_number: Standard library number. Will pick this stdlib to fetch the design. Don't pass this param, or pass it as null if the design is project specific.
article : Assembly/Module design name. Will be used to get the design from the project. Will be created if needed for later file uploads through the web interface.
ordernr : Used to fill the client_order_id in our system (a client order ID that comes from an external management system).
meta : Used to fill the client_meta in our system. This meta is shown in the design detail and can be used for customizations.
scheduled_prod_date : The expected production date. Used together with production_line_client_id; a time part, if any, is dropped.
production_line_client_id (optional): The Client ID of the production line in produuz.it. When provided, the system matches the order to the production line that has this Client ID configured. If no matching line is found, the request is rejected with an error. When this field is used, operations is not needed for line matching.
operations (legacy): This is a list of objects. Used to match a production line by workcenter name. If production_line_client_id is provided, this field is ignored for line matching. Each operation contains:
- workcenter : Name of the production line in produuz.it.
- date : Used as the "scheduled_prod_date" of the constructible, the expected production date from the client. Only the operation whose workcenter matches the line is read.

The constructible goes into a batch named after the production line, created in the project if it does not exist yet. A client_order_id (ordernr) that already exists is rejected.

Recommended approach

Use production_line_client_id instead of operations for line matching. Set the Client ID on each production line in the produuz.it settings, and pass it in the payload. This avoids having to match by exact production line name.

Endpoint: /api/v2/constructibles/actuals/bulk_create/?schema=hm_sap

Example Request Payload (using production_line_client_id)

json

[
  {
    "ordernr": "123",
    "article": "MW-D11-R",
    "project": "23-555",
    "projectname": "Example_Name",
    "stdlib_number": "std123456",
    "production_line_client_id": "50000012",
    "scheduled_prod_date": "2023-10-08T14:32:17.232Z",
    "meta": {
      "project": "23-555",
      "wbs": ""
    }
  }
]

[
  {
    "ordernr": "123",
    "article": "MW-D11-R",
    "project": "23-555",
    "projectname": "Example_Name",
    "stdlib_number": "std123456",
    "production_line_client_id": "50000012",
    "scheduled_prod_date": "2023-10-08T14:32:17.232Z",
    "meta": {
      "project": "23-555",
      "wbs": ""
    }
  }
]

Example Request Payload (legacy, using operations)

json

[
  {
    "ordernr": "123",
    "article": "MW-D11-R",
    "project": "23-555",
    "projectname": "Example_Name",
    "stdlib_number": "std123456",
    "meta": {
      "project": "23-555",
      "wbs": ""
    },
    "operations": [
      {
        "workcenter": "WAND",
        "date": "2023-10-08T14:32:17.232Z"
      }
    ]
  }
]

[
  {
    "ordernr": "123",
    "article": "MW-D11-R",
    "project": "23-555",
    "projectname": "Example_Name",
    "stdlib_number": "std123456",
    "meta": {
      "project": "23-555",
      "wbs": ""
    },
    "operations": [
      {
        "workcenter": "WAND",
        "date": "2023-10-08T14:32:17.232Z"
      }
    ]
  }
]

Example Response Payload

json

[
  {
    "client_order_id": "3321",
    "result": "created",
    "uuid": "the-uuid-v4",
    "level": "assembly",
    "created_project": false,
    "created_stdlib": false,
    "created_design": false,
    "created_batch": true
  },
  {
    "client_order_id": "3322",
    "result": "failed",
    "detail": "Something went wrong here"
  }
  // { ...third object }
]

[
  {
    "client_order_id": "3321",
    "result": "created",
    "uuid": "the-uuid-v4",
    "level": "assembly",
    "created_project": false,
    "created_stdlib": false,
    "created_design": false,
    "created_batch": true
  },
  {
    "client_order_id": "3322",
    "result": "failed",
    "detail": "Something went wrong here"
  }
  // { ...third object }
]

The response is 200 when every payload was created, and 400 as soon as one failed. The payloads that succeeded are still created, so read result on each entry before retrying.

API TUTORIAL – CREATE CONSTRUCTIBLES ​

Intro ​

Step 1: Project Creation/Retrieval ​

ALL RETRIEVAL ​

FILTERED RETRIEVAL ​

CREATION ​

Step 2: Batch Creation/Retrieval ​

RETRIEVAL ​

CREATION ​

UPDATING ​

Step 3: Assembly Design Retrieval ​

Step 4: Assembly Creation ​

Bulk Create ​

Custom schema 1 (hm_sap) ​

API TUTORIAL – CREATE CONSTRUCTIBLES

Intro

Step 1: Project Creation/Retrieval

ALL RETRIEVAL

FILTERED RETRIEVAL

CREATION

Step 2: Batch Creation/Retrieval

RETRIEVAL

CREATION

UPDATING

Step 3: Assembly Design Retrieval

Step 4: Assembly Creation

Bulk Create

Custom schema 1 (hm_sap)