# Materiales

> Cómo listar y actualizar precio, stock y estado de tableros, tapacantos y componentes, y copiar materiales entre centrales.

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

Su integración mantiene el precio, el stock y el estado activo/inactivo de los [materiales](https://apis.cortecloud.com.br/docs/es/comecando/conceitos.md#materiais) de la central: tableros, tapacantos y componentes. Los tres tipos tienen las mismas rutas y el mismo formato; solo cambia el path.

| Tipo | Path | Rutas en Swagger |
| --- | --- | --- |
| Tableros | `/materials/boards` | [Boards](https://apis.cortecloud.com.br/docs/swagger#/Boards) |
| Tapacantos | `/materials/edges` | [Edges](https://apis.cortecloud.com.br/docs/swagger#/Edges) |
| Componentes | `/materials/components` | [Components](https://apis.cortecloud.com.br/docs/swagger#/Components) |

Los ejemplos a continuación usan tableros.

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

Cada ruta de materiales localiza el ítem por el `internal_code`, el [código interno](https://apis.cortecloud.com.br/docs/es/comecando/conceitos.md#codigo-interno) del ítem en su sistema. Las rutas de actualización no crean ítems ni modifican el código interno de un ítem existente: el registro del material y su código interno se hacen en Cortecloud. La única ruta que crea ítems es la [copia entre centrales](https://apis.cortecloud.com.br/docs/es/guias/integracao-erp/materiais.md#copiar-materiais-entre-centrais), y solo en las centrales de destino. Los ítems sin código interno no aparecen en ninguna ruta.

Antes de integrar, confirme con la central que los ítems que el ERP va a actualizar están registrados en Cortecloud con los mismos códigos del ERP.

## Listar {#listar}

Ruta: [`GET /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/listBoards) (y las equivalentes de [tapacantos](https://apis.cortecloud.com.br/docs/swagger#/Edges/listEdges) y [componentes](https://apis.cortecloud.com.br/docs/swagger#/Components/listComponents)).

Devuelve `internal_code`, `active`, `price`, `stock` y `unit` de cada ítem, paginado por `limit` y `offset` (ver [paginación](https://apis.cortecloud.com.br/docs/es/comecando/erros-limites-paginacao.md#paginacao)). Para buscar un solo ítem, use la [consulta por código](https://apis.cortecloud.com.br/docs/es/guias/integracao-erp/materiais.md#consultar-um-item). Límite: 1 solicitud cada 5 segundos.

## Consultar un ítem {#consultar-um-item}

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

Devuelve el ítem con el código interno indicado en la URL, o `404` si la central no tiene un ítem con ese código.

## Actualizar varios ítems {#atualizar-varios-itens}

Rutas: [`PUT /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/updateBoards) o [`PATCH /materials/boards`](https://apis.cortecloud.com.br/docs/swagger#/Boards/patchBoards). Las dos hacen lo mismo.

Es la forma recomendada para sincronizar el ERP con Cortecloud: una llamada actualiza todos los ítems enviados. Solo cambian los campos enviados; los demás quedan como están.

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

El cuerpo puede ser una lista de ítems, como la anterior, un objeto `{ "resource": [...] }` o un solo ítem.

- Cada ítem debe tener `internal_code`. Si falta en alguno, la solicitud entera se rechaza con `400` y no se modifica nada.
- Los ítems cuyo `internal_code` no existe en la central se ignoran sin error. La respuesta lista solo los códigos actualizados: compárela con lo que se envió para saber cuáles quedaron fuera.
- Límite: 1 solicitud cada 5 segundos.

Campos aceptados:

| Campo | Efecto |
| --- | --- |
| `price` | Precio del ítem. Un valor negativo borra el precio (queda nulo). |
| `stock` | Stock. Un valor negativo se convierte en `0`. |
| `unit` | Unidad de redondeo. Cero o un valor negativo borra el valor (queda nulo). |
| `active` | `true` activa el ítem en la central; `false` lo desactiva. |

## Actualizar un ítem {#atualizar-um-item}

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

Actualiza el ítem con el código interno de la URL, con los mismos campos de la actualización en lote. Responde `404` si la central no tiene un ítem con ese código.

Si el cuerpo también trae `internal_code`, prevalece el del cuerpo: el ítem actualizado es el que tiene ese código, y no el de la URL. Para no actualizar el ítem equivocado, no envíe `internal_code` en el cuerpo de esta ruta.

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

Ruta: [`POST /materials/boards/cross-sync`](https://apis.cortecloud.com.br/docs/swagger#/Boards/crossSyncBoards) (y las equivalentes de [tapacantos](https://apis.cortecloud.com.br/docs/swagger#/Edges/crossSyncEdges) y [componentes](https://apis.cortecloud.com.br/docs/swagger#/Components/crossSyncComponents)).

Sirve para empresas con varias centrales que venden el mismo catálogo: en lugar de actualizar cada central, la integración actualiza una y copia sus materiales a las demás.

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

Cada central de destino queda con los mismos materiales que la central de origen: los ítems que el destino no tenía pasan a existir en él, y los que ya tenía reciben los datos del origen, como el código interno y el estado activo/inactivo.

| Opción | `true` | `false` (predeterminado) |
| --- | --- | --- |
| `syncPrice` | Copia el precio. | El destino conserva el precio que tenía; los ítems nuevos en el destino quedan con precio `0`. |
| `syncStock` | Copia el stock. | El destino conserva el stock que tenía; los ítems nuevos en el destino quedan con stock `0`. |
| `syncActive` | Desactiva en el destino los ítems que no existen en el origen. | Esos ítems quedan como están. |

Reglas:

- La central de origen debe ser la central de la solicitud (`x-company-internal-code`), y las de destino deben estar activas en Cortecloud y vinculadas a la misma api key. Si alguna no lo está, la respuesta es `403` y no se copia nada.
- La copia se ejecuta en segundo plano: la respuesta `202` solo confirma que fue programada. Ninguna ruta informa cuándo termina la copia; para verificar el resultado, liste los materiales con el código de la central de destino en `x-company-internal-code`.
- Límite: 1 solicitud cada 5 segundos.