# Materials

> How to list and update price, stock and status of boards, edge banding and hardware components, and copy materials between service centers.

Canonical URL: https://apis.cortecloud.com.br/docs/en/guias/integracao-erp/materiais/

Your integration maintains price, stock and active/inactive status of the service center's [materials](https://apis.cortecloud.com.br/docs/en/comecando/conceitos.md#materiais): boards, edge banding and hardware components. The three types have the same routes and the same format; only the path changes.

| Type | Path | Routes in Swagger |
| --- | --- | --- |
| Boards | `/materials/boards` | [Boards](https://apis.cortecloud.com.br/docs/swagger#/Boards) |
| Edge banding | `/materials/edges` | [Edges](https://apis.cortecloud.com.br/docs/swagger#/Edges) |
| Hardware components | `/materials/components` | [Components](https://apis.cortecloud.com.br/docs/swagger#/Components) |

The examples below use boards.

## Internal code {#codigo-interno}

Every materials route looks up the item by `internal_code`, the item's [internal code](https://apis.cortecloud.com.br/docs/en/comecando/conceitos.md#codigo-interno) in your system. The update routes do not create items or change the internal code of an existing item: the material and its internal code are registered in Cortecloud. The only route that creates items is the [copy between service centers](https://apis.cortecloud.com.br/docs/en/guias/integracao-erp/materiais.md#copiar-materiais-entre-centrais), and only in the target service centers. Items without an internal code do not appear in any route.

Before integrating, confirm with the service center that the items the ERP will update are registered in Cortecloud with the same codes as in the ERP.

## List {#listar}

Route: [`GET /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/listBoards) (and the equivalents for [edge banding](https://apis.cortecloud.com.br/docs/swagger#/Edges/listEdges) and [hardware components](https://apis.cortecloud.com.br/docs/swagger#/Components/listComponents)).

Returns `internal_code`, `active`, `price`, `stock` and `unit` for each item, paginated by `limit` and `offset` (see [pagination](https://apis.cortecloud.com.br/docs/en/comecando/erros-limites-paginacao.md#paginacao)). To fetch a single item, use the [query by code](https://apis.cortecloud.com.br/docs/en/guias/integracao-erp/materiais.md#consultar-um-item). Limit: 1 request every 5 seconds.

## Get an item {#consultar-um-item}

Route: [`GET /materials/boards/{internalCode}`](https://apis.cortecloud.com.br/docs/swagger#/Boards/getBoard).

Returns the item with the internal code given in the URL, or `404` if the service center has no item with that code.

## Update several items {#atualizar-varios-itens}

Routes: [`PUT /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/updateBoards) or [`PATCH /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/patchBoards). Both do the same thing.

This is the recommended way to synchronize the ERP with Cortecloud: one call updates all the items sent. Only the fields sent change; the others stay as they are.

```json
[
  { "internal_code": "MDF-BR-18", "price": 289.9, "stock": 42 },
  { "internal_code": "MDF-CZ-15", "active": false }
]
```

The body can be a list of items, as above, an object `{ "resource": [...] }` or a single item.

- Each item must have `internal_code`. If it is missing from any of them, the whole request is refused with `400` and nothing is changed.
- Items whose `internal_code` does not exist at the service center are ignored without error. The response lists only the updated codes: compare it with what was sent to find out which ones were left out.
- Limit: 1 request every 5 seconds.

Accepted fields:

| Field | Effect |
| --- | --- |
| `price` | Item price. A negative value clears the price (it becomes null). |
| `stock` | Stock. A negative value becomes `0`. |
| `unit` | Rounding unit. Zero or a negative value clears it (it becomes null). |
| `active` | `true` activates the item at the service center; `false` deactivates it. |

## Update one item {#atualizar-um-item}

Routes: [`PUT /materials/boards/{internalCode}`](https://apis.cortecloud.com.br/docs/swagger#/Boards/updateBoard) or [`PATCH /materials/boards/{internalCode}`](https://apis.cortecloud.com.br/docs/swagger#/Boards/patchBoard).

Updates the item with the internal code in the URL, with the same fields as the batch update. Responds with `404` if the service center has no item with that code.

If the body also includes `internal_code`, the one in the body prevails: the updated item is the one with that code, not the one in the URL. To avoid updating the wrong item, do not send `internal_code` in the body of this route.

## Copy materials between service centers {#copiar-materiais-entre-centrais}

Route: [`POST /materials/boards/cross-sync`](https://apis.cortecloud.com.br/docs/swagger#/Boards/crossSyncBoards) (and the equivalents for [edge banding](https://apis.cortecloud.com.br/docs/swagger#/Edges/crossSyncEdges) and [hardware components](https://apis.cortecloud.com.br/docs/swagger#/Components/crossSyncComponents)).

It is meant for companies with several service centers that sell the same catalog: instead of updating each service center, the integration updates one and copies its materials to the others.

```json
{
  "sourceCompanyInternalCode": "CENTRAL-SP",
  "targetCompanyInternalCodes": ["CENTRAL-RJ", "CENTRAL-MG"],
  "syncPrice": true,
  "syncStock": false,
  "syncActive": false
}
```

Each target service center ends up with the same materials as the source service center: items the target did not have are created in it, and those it already had receive the source's data, such as internal code and active/inactive status.

| Option | `true` | `false` (default) |
| --- | --- | --- |
| `syncPrice` | Copies the price. | The target keeps the price it had; items new to the target get price `0`. |
| `syncStock` | Copies the stock. | The target keeps the stock it had; items new to the target get stock `0`. |
| `syncActive` | Deactivates in the target the items that do not exist in the source. | Those items stay as they are. |

Rules:

- The source service center must be the request's service center (`x-company-internal-code`), and the targets must be active on Cortecloud and linked to the same api key. If any of them is not, the response is `403` and nothing is copied.
- The copy runs in the background: the `202` response only confirms that it was scheduled. No route reports when the copy finishes; to check the result, list the materials with the target service center's code in `x-company-internal-code`.
- Limit: 1 request every 5 seconds.