Create services

Your integration can create a service at the service center with the parts already defined in your system. Cortecloud registers the carpenter, fills in the parts, sends the service to optimization and generates the quote, as with a service created in the app.

Route: POST /services. Requires service-center authentication (HMAC); with Basic authentication, it responds with 401.

Body

{
  "serviceInternalCode": "PED-123",
  "productionInternalCode": "LINHA-1",
  "carpenterEmail": "carpenter@example.com",
  "carpenterName": "John Carpenter",
  "carpenterInternalCode": "CLI-9",
  "parts": [
    {
      "quantity": 1,
      "c": 500,
      "l": 500,
      "function": "Lateral",
      "complement": "Balcao A",
      "client": "Ana",
      "furniture": "Kitchen",
      "material": { "internalCode": "MDF18BR" },
      "c1": { "internalCode": "FT04BR" },
      "c2": null,
      "l1": null,
      "l2": null,
      "machining": {
        "x": 500,
        "y": 500,
        "z": 18,
        "startSide": 0,
        "horizontalDrills": [],
        "verticalDrills": [
          { "corner": 0, "bolthole": false, "x": 25, "y": 37, "depth": 12, "diameter": 15, "face": "i" }
        ],
        "furrowMachining": null,
        "furrowMachiningPair": null
      }
    }
  ]
}

Field	Rule
serviceInternalCode	The service's internal code, usually the order number in the ERP. Optional, up to 255 characters. Comes back in webhooks as service_internal_code.
productionInternalCode	Internal code of the production line. Required.
carpenterEmail, carpenterName	Carpenter's email and name. Required.
carpenterInternalCode	Carpenter's (customer's) code in your system. Required.
parts	The service's parts, from 1 to 500.

Before creating the service, the route registers the carpenter in Cortecloud, if they don't exist yet, and links them to the service center with carpenterInternalCode, as in embedded login. If the carpenter already has an active link with the service center, that link's internal code is kept. If carpenterEmail already belongs to a user with another profile (for example, a salesperson), they become a carpenter and lose the previous profile.

Parts

parts follows the structure of the JSON file import: the same fields, measurements in millimeters and the same machining object, described in Machining. The differences are in the materials and in validation:

Field	In the import	Here
material	Board name in your system.	The part's board: { "internalCode": "..." }, with the board's internal code at the service center. Required.
client, furniture	Do not exist: the carpenter picks the customer during the import.	The carpenter's customer and the part's room (for example, "Kitchen"), up to 255 characters each. Optional: parts with the same pair go to the same customer of the service, and parts without them go to a customer with no name.
c1, c2, l1, l2	Edge band name.	{ "internalCode": "..." } with the edge band's internal code at the service center. Side without edge band: null or absent.
quantity, c, l	A part with a missing, zero or negative value is discarded.	A missing, zero or negative value responds with 400. c and l go up to 9999.99.

Board and edge band internal codes, function and complement take up to 255 characters; beyond that, the route responds with 400.

Since materials arrive by internal code, the import's material linking step does not exist.

The same rules as the import apply:

• An empty function becomes "Peça".
• Machining is only applied if the production line has a machining machine (see When the production line does not machine).
• Each part uses at most two different edge bands. If the service center does not accept two edge bands per part, the sides with the second edge band are left without edge band.

There is no field for part rotation: the part may rotate in the cutting plan when the board has no grain.

Response and follow-up

The 202 response carries the service id:

{ "id": 98765 }

The 202 confirms the body format and the carpenter registration. Materials, production line and parts are validated later, asynchronously: a nonexistent board code, for example, does not change the response. The result arrives by webhook:

• service.created: the service was created and its parts were saved (status 1);
• service.creation_failed: creation failed, and errors lists the reasons.

service.created goes out after the service is sent to optimization. When the quote is ready, service.quoted arrives. If sending is rejected, for example because a part is larger than the board, service.creation_failed arrives with the reasons. To receive all three, request a destination for each type (see How to enable).

While Cortecloud fills in the parts, the service is locked for editing in the apps.

Part ids

The quote and the parts are in GET /services/{id}. parts[].id is each part's id in Cortecloud: use it to match the parts with your system, for example with the machining DrillCode.

What the carpenter sees

The service belongs to the service center and is associated with the carpenter. It shows up in the carpenter's Cortecloud starting at the approved status (6), as read-only.

Errors

Status	When
400	Body out of format: missing required field, invalid email, empty parts or more than 500 parts, part without material, non-positive quantity or measurement, machining out of the import format.
401	Basic authentication. The route requires HMAC.

Errors in materials, production line or parts, including a part larger than the board, arrive in service.creation_failed, not in the response.

Retry after a timeout

serviceInternalCode is not checked for duplicates. If the response is lost and your integration repeats the call, Cortecloud may create the service twice.