# Importación de piezas por archivo JSON

> Formato del archivo JSON con el que el carpintero importa piezas, perforaciones y mecanizados a un servicio; no usa la API.

URL canónica: https://apis.cortecloud.com.br/docs/es/guias/importacao-json/

Cortecloud importa listas de piezas, con perforaciones y mecanizados, a partir de un archivo JSON en el formato descrito en esta página. Es el camino para que un software de diseño de muebles lleve el proyecto del [carpintero](https://apis.cortecloud.com.br/docs/es/comecando/conceitos.md#quem-e-quem) a Cortecloud: su sistema genera el archivo y el carpintero lo carga en un [servicio](https://apis.cortecloud.com.br/docs/es/comecando/conceitos.md#servico).

Esta integración no pasa por la API Pública: no hay credenciales ni rutas involucradas. El contrato es el formato del archivo.

## Cómo importa el archivo el carpintero {#como-o-marceneiro-importa-o-arquivo}

La importación se hace en el Cortecloud del carpintero, desde el navegador de la computadora. La app móvil no tiene esa opción.

Las opciones de la interfaz se indican a continuación con el nombre que aparece en pantalla, en portugués, seguido de su traducción.

1. El carpintero crea un nuevo servicio del tipo **Serviço completo** (servicio completo). Los servicios con módulos no aceptan la importación de piezas.

   ![Pantalla de nuevo servicio de Cortecloud con las opciones Serviço com módulos, Serviço completo y Tiras](https://apis.cortecloud.com.br/docs/es/img/guias/importacao-json-novo-servico.png)

2. Con la [línea de producción](https://apis.cortecloud.com.br/docs/es/comecando/conceitos.md#servico) del servicio elegida (sin ella el botón queda deshabilitado), abre **Importar peças** (importar piezas) y elige **Carregar arquivo Cortecloud** (cargar archivo Cortecloud), que acepta archivos `.json`.

   ![Menú Importar peças con la opción Carregar arquivo Cortecloud resaltada](https://apis.cortecloud.com.br/docs/es/img/guias/importacao-json-importar-pecas.png)

3. Cortecloud lista las piezas del archivo y le pide que vincule cada material del archivo a un tablero y a un tapacanto registrados en la central (ver [vínculo de materiales](https://apis.cortecloud.com.br/docs/es/guias/importacao-json.md#vinculo-de-materiais)).

   ![Pantalla de importación con la lista de piezas leídas del archivo y los campos de cliente, tablero y tapacanto](https://apis.cortecloud.com.br/docs/es/img/guias/importacao-json-vincular-materiais.png)

4. Después de crear las piezas, el carpintero revisa el resultado en la lista de piezas. En las piezas con mecanizado, la miniatura de la pieza muestra las perforaciones, con las cotas de cada agujero.

   ![Lista de piezas importadas con la miniatura de una pieza que muestra las cotas de un agujero](https://apis.cortecloud.com.br/docs/es/img/guias/importacao-json-pecas-importadas.png)

Use este flujo para probar el archivo que genera su sistema: con una cuenta de carpintero en Cortecloud, cargue el archivo en un servicio y revise en la miniatura de cada pieza si los mecanizados quedaron donde debían.

## Estructura del archivo {#estrutura-do-arquivo}

El archivo es un objeto con la lista `parts`, una entrada por pieza:

```json
{
  "parts": [
    {
      "quantity": 1,
      "c": 500,
      "l": 500,
      "function": "Lateral",
      "complement": "Balcao A",
      "c1": "Branco 0.4",
      "c2": null,
      "l1": null,
      "l2": null,
      "material": "Branco 18",
      "machining": {
        "x": 500,
        "y": 500,
        "z": 18,
        "startSide": 0,
        "horizontalDrills": [
          { "corner": 2, "direction": "XP", "x": 0, "y": 69, "z": 10.5, "depth": 24, "diameter": 8, "face": "i" },
          { "corner": 1, "direction": "XP", "x": 0, "y": 37, "z": 10.5, "depth": 24, "diameter": 8, "face": "i" },
          { "corner": 1, "direction": "XP", "x": 0, "y": 57, "z": 9, "depth": 22, "diameter": 8, "face": "i" },
          { "corner": 2, "direction": "XP", "x": 0, "y": 89, "z": 9, "depth": 22, "diameter": 8, "face": "i" },
          { "corner": 3, "direction": "XP", "x": 0, "y": 69, "z": 10.5, "depth": 24, "diameter": 8, "face": "i" },
          { "corner": 0, "direction": "XP", "x": 0, "y": 37, "z": 10.5, "depth": 24, "diameter": 8, "face": "i" },
          { "corner": 0, "direction": "XP", "x": 0, "y": 57, "z": 9, "depth": 22, "diameter": 8, "face": "i" },
          { "corner": 3, "direction": "XP", "x": 0, "y": 89, "z": 9, "depth": 22, "diameter": 8, "face": "i" }
        ],
        "verticalDrills": [
          { "corner": 2, "bolthole": false, "x": 25, "y": 69, "depth": 12, "diameter": 15, "face": "i" },
          { "corner": 1, "bolthole": false, "x": 25, "y": 37, "depth": 12, "diameter": 15, "face": "i" },
          { "corner": 3, "bolthole": false, "x": 25, "y": 69, "depth": 12, "diameter": 15, "face": "i" },
          { "corner": 0, "bolthole": false, "x": 25, "y": 37, "depth": 12, "diameter": 15, "face": "i" }
        ],
        "furrowMachining": {
          "face": "i",
          "depth": 8,
          "width": 6.7,
          "distance": 15
        },
        "furrowMachiningPair": null
      }
    }
  ]
}
```

Hay archivos de ejemplo, con los casos de prueba y el resultado esperado de cada uno, en la [carpeta de Serrabits en Google Drive](https://drive.google.com/drive/folders/12UqqduUalFZwWxRnaLawKr4qvHRipcgE).

Todas las medidas están en milímetros.

### Campos de la pieza {#campos-da-peca}

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `quantity` | entero | Cantidad de piezas iguales. Debe ser mayor que cero. |
| `c` | número | Largo de la pieza. Debe ser mayor que cero. |
| `l` | número | Ancho de la pieza. Debe ser mayor que cero. |
| `function` | texto | Función de la pieza en el mueble (por ejemplo, "Lateral", "Puerta", "Base"). |
| `complement` | texto | Texto libre que acompaña a la pieza, como el nombre del módulo o del ambiente. |
| `c1`, `c2`, `l1`, `l2` | texto o `null` | Nombre del tapacanto aplicado en cada lado de la pieza (ver [sistema de coordenadas](https://apis.cortecloud.com.br/docs/es/guias/importacao-json.md#sistema-de-coordenadas)), o `null` para el lado sin tapacanto. |
| `material` | texto | Nombre del tablero del que se corta la pieza. |
| `machining` | objeto o `null` | Perforaciones y mecanizados de la pieza (ver [mecanizado](https://apis.cortecloud.com.br/docs/es/guias/importacao-json.md#usinagem)), o `null` para una pieza sin mecanizado. |

Las piezas con `quantity`, `c` o `l` ausentes, en cero o negativos no se crean.

### Vínculo de materiales {#vinculo-de-materiais}

`material` y los tapacantos (`c1`, `c2`, `l1`, `l2`) son los nombres que usa su sistema, no códigos de Cortecloud. En la importación, Cortecloud agrupa las piezas por `material` y el carpintero elige, para cada material, el [tablero y el tapacanto](https://apis.cortecloud.com.br/docs/es/comecando/conceitos.md#materiais) de la central que le corresponden. El carpintero también puede marcar un material para que se ignore; sus piezas no se crean.

Si ninguna pieza del archivo tiene `material`, el carpintero elige un único tablero y un único tapacanto para todas las piezas.

Cada pieza puede usar como máximo dos tapacantos distintos, y el segundo solo se vincula si la central acepta dos tapacantos por pieza. Cuando la central no lo acepta, los lados con el segundo tapacanto quedan sin tapacanto.

## Sistema de coordenadas {#sistema-de-coordenadas}

Las posiciones de los mecanizados se miden a partir de una de las esquinas de la pieza, con la pieza vista por la cara interna:

![Pieza vista de frente con las esquinas 0 a 3, los ejes X e Y que parten de cada esquina y los lados C1, C2, L1 y L2](https://apis.cortecloud.com.br/docs/es/img/guias/importacao-json-coordenadas.png)

- **Esquinas** (`corner`): `0` (superior izquierda), `1` (inferior izquierda), `2` (inferior derecha) y `3` (superior derecha).
- **Ejes**: a partir de cada esquina, X corre a lo largo del largo (lados C) e Y a lo largo del ancho (lados L), siempre hacia el interior de la pieza.
- **Lados**: C1 y C2 son los lados del largo; L1 y L2, los del ancho.
- **Segmentos**: cada lado también se identifica por las esquinas que lo delimitan. C1 es el segmento 0-1, L1 es el 1-2, C2 es el 2-3 y L2 es el 3-0.

La **cara interna** (`"i"`) es la cara frontal de la pieza, la que aparece en la imagen; la **cara externa** (`"e"`) es la de atrás.

## Mecanizado {#usinagem}

El objeto `machining` describe las perforaciones y las ranuras de una pieza.

| Campo | Descripción |
| --- | --- |
| `x`, `y`, `z` | Dimensiones de la pieza en el sistema de coordenadas del mecanizado. Con `startSide` igual a `0`, `x` es el largo (`c`), `y` es el ancho (`l`) y `z` es el espesor del tablero. |
| `startSide` | `0` mantiene el mecanizado tal como se describe; `1` gira 90° todo el mecanizado de la pieza. |
| `horizontalDrills` | Lista de perforaciones horizontales: agujeros hechos en el canto de la pieza, paralelos a las caras. |
| `verticalDrills` | Lista de perforaciones verticales: agujeros hechos en una de las caras, perpendiculares a ella. |
| `furrowMachining` | Ranura o rebaje en la cara interna, o `null` si no hay. |
| `furrowMachiningPair` | Ranura o rebaje en la cara externa, o `null` si no hay. |

### Perforaciones horizontales {#furos-horizontais}

| Campo | Descripción |
| --- | --- |
| `corner` | Esquina de referencia para `x` e `y` (`0` a `3`). |
| `direction` | `XP` para agujeros en los cantos L1 o L2 (segmentos 1-2 y 3-0), que entran en la pieza en la dirección del eje X; `YP` para agujeros en los cantos C1 o C2 (segmentos 0-1 y 2-3), que entran en la dirección del eje Y. |
| `x` | Posición en el eje X. Debe ser `0` cuando `direction` es `XP`, porque el agujero empieza en el canto. |
| `y` | Posición en el eje Y. Debe ser `0` cuando `direction` es `YP`. |
| `z` | Posición del agujero en el espesor de la pieza, entre `0` y el espesor. Es el espesor menos la distancia del centro del agujero a la cara interna. |
| `depth` | Profundidad del agujero. |
| `diameter` | Diámetro del agujero. |
| `face` | Siempre `"i"`. |

Ejemplos de `z`:

- agujero en el centro del espesor de una pieza de 15 mm: `z` = 7.5;
- agujero a 7.5 mm de la cara interna de una pieza de 25 mm: `z` = 25 − 7.5 = 17.5.

### Perforaciones verticales {#furos-verticais}

| Campo | Descripción |
| --- | --- |
| `corner` | Esquina de referencia para `x` e `y` (`0` a `3`). |
| `x` | Posición del centro del agujero en el eje X. |
| `y` | Posición del centro del agujero en el eje Y. |
| `depth` | Profundidad del agujero. En un agujero pasante, el espesor del tablero. |
| `diameter` | Diámetro del agujero. |
| `bolthole` | `true` si el agujero es pasante (atraviesa la pieza), como los agujeros de montaje con tornillo; `false` en caso contrario. |
| `face` | Cara en la que se hace el agujero: `"i"` (interna) o `"e"` (externa). |

### Ranuras y rebajes {#rasgos-e-rebaixos}

Una **ranura** es un canal fresado en la cara de la pieza, a cierta distancia del canto; un **rebaje** es el mismo corte pegado al canto. Los dos sirven, por ejemplo, para encajar el fondo de un mueble. Siempre se hacen a lo largo del lado C2 (segmento 2-3), en todo el largo de la pieza.

`furrowMachining` y `furrowMachiningPair` tienen la misma estructura:

| Campo | Descripción |
| --- | --- |
| `face` | `"i"` en `furrowMachining` y `"e"` en `furrowMachiningPair`. |
| `depth` | Profundidad del corte. |
| `width` | Ancho del corte. |
| `distance` | Distancia del corte al canto C2. Con `0`, el corte es un rebaje; con un valor mayor que cero, una ranura. |

`furrowMachiningPair` es para piezas con ranura o rebaje en las dos caras, como divisiones y estantes que reciben fondo por ambos lados. La miniatura de la pieza en Cortecloud muestra solo el `furrowMachining`; el de la cara externa no aparece en ella.

### Cuando la línea de producción no mecaniza {#quando-a-linha-de-producao-nao-usina}

El mecanizado solo se aplica si la línea de producción del servicio tiene máquina de mecanizado. Si no la tiene, las piezas se crean sin mecanizado: Cortecloud guarda el contenido de `machining` del archivo, pero no lo aplica a las piezas ni lo cobra en el presupuesto.

## Dudas {#duvidas}

Dudas técnicas sobre el formato del archivo: suporte@serrabits.com.br.