# Materiais

> Como listar e atualizar preço, estoque e status de chapas, fitas de borda e componentes, e copiar materiais entre centrais.

URL canônica: https://apis.cortecloud.com.br/docs/guias/integracao-erp/materiais/

A sua integração mantém preço, estoque e status ativo/inativo dos [materiais](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#materiais) da central: chapas, fitas de borda e componentes. Os três tipos têm as mesmas rotas e o mesmo formato; muda só o caminho.

| Tipo | Caminho | Rotas no Swagger |
| --- | --- | --- |
| Chapas | `/materials/boards` | [Boards](https://apis.cortecloud.com.br/docs/swagger#/Boards) |
| Fitas de borda | `/materials/edges` | [Edges](https://apis.cortecloud.com.br/docs/swagger#/Edges) |
| Componentes | `/materials/components` | [Components](https://apis.cortecloud.com.br/docs/swagger#/Components) |

Os exemplos abaixo usam chapas.

## Código interno {#codigo-interno}

Toda rota de materiais localiza o item pelo `internal_code`, o [código interno](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#codigo-interno) do item no seu sistema. As rotas de atualização não criam itens nem alteram o código interno de um item existente: o cadastro do material e o seu código interno são feitos no Cortecloud. A única rota que cria itens é a [cópia entre centrais](https://apis.cortecloud.com.br/docs/guias/integracao-erp/materiais.md#copiar-materiais-entre-centrais), e só nas centrais de destino. Itens sem código interno não aparecem em nenhuma rota.

Antes de integrar, confirme com a central que os itens que o ERP vai atualizar estão cadastrados no Cortecloud com os mesmos códigos do ERP.

## Listar {#listar}

Rota: [`GET /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/listBoards) (e as equivalentes de [fitas](https://apis.cortecloud.com.br/docs/swagger#/Edges/listEdges) e [componentes](https://apis.cortecloud.com.br/docs/swagger#/Components/listComponents)).

Devolve `internal_code`, `active`, `price`, `stock` e `unit` de cada item, paginado por `limit` e `offset` (ver [paginação](https://apis.cortecloud.com.br/docs/comecando/erros-limites-paginacao.md#paginacao)). Para buscar um item só, use a [consulta por código](https://apis.cortecloud.com.br/docs/guias/integracao-erp/materiais.md#consultar-um-item). Limite: 1 requisição a cada 5 segundos.

## Consultar um item {#consultar-um-item}

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

Devolve o item com o código interno informado na URL, ou `404` se a central não tiver um item com esse código.

## Atualizar vários itens {#atualizar-varios-itens}

Rotas: [`PUT /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/updateBoards) ou [`PATCH /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/patchBoards). As duas fazem a mesma coisa.

É a forma indicada para sincronizar o ERP com o Cortecloud: uma chamada atualiza todos os itens enviados. Só os campos enviados mudam; os outros ficam como estão.

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

O corpo pode ser uma lista de itens, como acima, um objeto `{ "resource": [...] }` ou um item só.

- Cada item precisa ter `internal_code`. Se faltar em algum, a requisição inteira é recusada com `400` e nada é alterado.
- Itens cujo `internal_code` não existe na central são ignorados sem erro. A resposta lista só os códigos atualizados: compare com o que foi enviado para saber quais ficaram de fora.
- Limite: 1 requisição a cada 5 segundos.

Campos aceitos:

| Campo | Efeito |
| --- | --- |
| `price` | Preço do item. Valor negativo apaga o preço (fica nulo). |
| `stock` | Estoque. Valor negativo vira `0`. |
| `unit` | Unidade de arredondamento. Zero ou negativo apaga o valor (fica nulo). |
| `active` | `true` ativa o item na central; `false` desativa. |

## Atualizar um item {#atualizar-um-item}

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

Atualiza o item com o código interno da URL, com os mesmos campos da atualização em lote. Responde `404` se a central não tiver um item com esse código.

Se o corpo também trouxer `internal_code`, vale o do corpo: o item atualizado é o que tem esse código, e não o da URL. Para não atualizar o item errado, não envie `internal_code` no corpo desta rota.

## Copiar materiais entre centrais {#copiar-materiais-entre-centrais}

Rota: [`POST /materials/boards/cross-sync`](https://apis.cortecloud.com.br/docs/swagger#/Boards/crossSyncBoards) (e as equivalentes de [fitas](https://apis.cortecloud.com.br/docs/swagger#/Edges/crossSyncEdges) e [componentes](https://apis.cortecloud.com.br/docs/swagger#/Components/crossSyncComponents)).

Serve para empresas com várias centrais que vendem o mesmo catálogo: em vez de atualizar cada central, a integração atualiza uma e copia os materiais dela para as outras.

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

Cada central de destino passa a ter os mesmos materiais da central de origem: itens que o destino não tinha passam a existir nele, e os que ele já tinha recebem os dados da origem, como código interno e status ativo/inativo.

| Opção | `true` | `false` (padrão) |
| --- | --- | --- |
| `syncPrice` | Copia o preço. | O destino mantém o preço que tinha; itens novos no destino ficam com preço `0`. |
| `syncStock` | Copia o estoque. | O destino mantém o estoque que tinha; itens novos no destino ficam com estoque `0`. |
| `syncActive` | Desativa no destino os itens que não existem na origem. | Esses itens ficam como estão. |

Regras:

- A central de origem precisa ser a central da requisição (`x-company-internal-code`), e as de destino precisam estar ativas no Cortecloud e vinculadas à mesma api key. Se alguma não estiver, a resposta é `403` e nada é copiado.
- A cópia roda em segundo plano: a resposta `202` só confirma que ela foi agendada. Nenhuma rota informa quando a cópia termina; para conferir o resultado, liste os materiais com o código da central de destino em `x-company-internal-code`.
- Limite: 1 requisição a cada 5 segundos.