# Importação de peças por arquivo JSON

> Formato do arquivo JSON com que o marceneiro importa peças, furações e usinagens num serviço; não usa a API.

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

O Cortecloud importa listas de peças, com furações e usinagens, a partir de um arquivo JSON no formato descrito nesta página. É o caminho para um software de projeto de móveis levar o projeto do [marceneiro](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#quem-e-quem) ao Cortecloud: o seu sistema gera o arquivo e o marceneiro o carrega num [serviço](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#servico).

Essa integração não passa pela API Pública: não há credenciais nem rotas envolvidas. O contrato é o formato do arquivo.

## Como o marceneiro importa o arquivo {#como-o-marceneiro-importa-o-arquivo}

A importação é feita no Cortecloud do marceneiro, pelo navegador do computador. O app mobile não tem essa opção.

1. O marceneiro cria um novo serviço do tipo **Serviço completo**. Serviços com módulos não aceitam importação de peças.

   ![Tela de novo serviço do Cortecloud com as opções Serviço com módulos, Serviço completo e Tiras](https://apis.cortecloud.com.br/docs/img/guias/importacao-json-novo-servico.png)

2. Com a [linha de produção](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#servico) do serviço escolhida (sem ela o botão fica desabilitado), ele abre **Importar peças** e escolhe **Carregar arquivo Cortecloud**, que aceita arquivos `.json`.

   ![Menu Importar peças com a opção Carregar arquivo Cortecloud destacada](https://apis.cortecloud.com.br/docs/img/guias/importacao-json-importar-pecas.png)

3. O Cortecloud lista as peças do arquivo e pede que ele vincule cada material do arquivo a uma chapa e a uma fita de borda cadastradas na central (ver [vínculo de materiais](https://apis.cortecloud.com.br/docs/guias/importacao-json.md#vinculo-de-materiais)).

   ![Tela de importação com a lista de peças lidas do arquivo e os campos de cliente, chapa e fita](https://apis.cortecloud.com.br/docs/img/guias/importacao-json-vincular-materiais.png)

4. Depois de criar as peças, o marceneiro confere o resultado na lista de peças. Nas peças com usinagem, a miniatura da peça mostra as furações, com as cotas de cada furo.

   ![Lista de peças importadas com a miniatura de uma peça mostrando as cotas de um furo](https://apis.cortecloud.com.br/docs/img/guias/importacao-json-pecas-importadas.png)

Use esse fluxo para testar o arquivo que o seu sistema gera: com uma conta de marceneiro no Cortecloud, carregue o arquivo num serviço e confira na miniatura de cada peça se as usinagens ficaram onde deveriam.

## Estrutura do arquivo {#estrutura-do-arquivo}

O arquivo é um objeto com a lista `parts`, uma entrada por peça:

```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
      }
    }
  ]
}
```

Arquivos de exemplo, com os casos de teste e o resultado esperado de cada um, estão na [pasta da Serrabits no Google Drive](https://drive.google.com/drive/folders/12UqqduUalFZwWxRnaLawKr4qvHRipcgE).

Todas as medidas são em milímetros.

### Campos da peça {#campos-da-peca}

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `quantity` | inteiro | Quantidade de peças iguais. Precisa ser maior que zero. |
| `c` | número | Comprimento da peça. Precisa ser maior que zero. |
| `l` | número | Largura da peça. Precisa ser maior que zero. |
| `function` | texto | Função da peça no móvel (por exemplo, "Lateral", "Porta", "Base"). |
| `complement` | texto | Texto livre que acompanha a peça, como o nome do módulo ou ambiente. |
| `c1`, `c2`, `l1`, `l2` | texto ou `null` | Nome da fita de borda aplicada em cada lado da peça (ver [sistema de coordenadas](https://apis.cortecloud.com.br/docs/guias/importacao-json.md#sistema-de-coordenadas)), ou `null` para o lado sem fita. |
| `material` | texto | Nome da chapa de onde a peça é cortada. |
| `machining` | objeto ou `null` | Furações e usinagens da peça (ver [usinagem](https://apis.cortecloud.com.br/docs/guias/importacao-json.md#usinagem)), ou `null` para peça sem usinagem. |

Peças com `quantity`, `c` ou `l` ausentes, zerados ou negativos não são criadas.

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

`material` e as fitas (`c1`, `c2`, `l1`, `l2`) são os nomes que o seu sistema usa, não códigos do Cortecloud. Na importação, o Cortecloud agrupa as peças por `material` e o marceneiro escolhe, para cada material, a [chapa e a fita de borda](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#materiais) da central que correspondem a ele. O marceneiro também pode marcar um material para ser ignorado; as peças dele não são criadas.

Se nenhuma peça do arquivo tiver `material`, o marceneiro escolhe uma única chapa e uma única fita para todas as peças.

Cada peça pode usar no máximo duas fitas diferentes, e a segunda só é vinculada se a central aceitar duas fitas por peça. Quando a central não aceita, os lados com a segunda fita ficam sem fita.

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

As posições das usinagens são medidas a partir de um dos cantos da peça, com a peça vista pela face interna:

![Peça vista de frente com os cantos 0 a 3, os eixos X e Y partindo de cada canto e os lados C1, C2, L1 e L2](https://apis.cortecloud.com.br/docs/img/guias/importacao-json-coordenadas.png)

- **Cantos** (`corner`): `0` (superior esquerdo), `1` (inferior esquerdo), `2` (inferior direito) e `3` (superior direito).
- **Eixos**: a partir de cada canto, X corre ao longo do comprimento (lados C) e Y ao longo da largura (lados L), sempre para dentro da peça.
- **Lados**: C1 e C2 são os lados do comprimento; L1 e L2, os da largura.
- **Segmentos**: cada lado também é identificado pelos cantos que o delimitam. C1 é o segmento 0-1, L1 é o 1-2, C2 é o 2-3 e L2 é o 3-0.

**Face interna** (`"i"`) é a face da frente da peça, a que aparece na imagem; **face externa** (`"e"`) é a de trás.

## Usinagem {#usinagem}

O objeto `machining` descreve as furações e os rasgos de uma peça.

| Campo | Descrição |
| --- | --- |
| `x`, `y`, `z` | Dimensões da peça no sistema de coordenadas da usinagem. Com `startSide` igual a `0`, `x` é o comprimento (`c`), `y` é a largura (`l`) e `z` é a espessura da chapa. |
| `startSide` | `0` mantém a usinagem como descrita; `1` gira a usinagem inteira da peça em 90°. |
| `horizontalDrills` | Lista de furos horizontais: furos feitos no topo da peça (na borda), paralelos às faces. |
| `verticalDrills` | Lista de furos verticais: furos feitos numa das faces, perpendiculares a ela. |
| `furrowMachining` | Rasgo ou rebaixo na face interna, ou `null` se não houver. |
| `furrowMachiningPair` | Rasgo ou rebaixo na face externa, ou `null` se não houver. |

### Furos horizontais {#furos-horizontais}

| Campo | Descrição |
| --- | --- |
| `corner` | Canto de referência para `x` e `y` (`0` a `3`). |
| `direction` | `XP` para furos nas bordas L1 ou L2 (segmentos 1-2 e 3-0), que entram na peça na direção do eixo X; `YP` para furos nas bordas C1 ou C2 (segmentos 0-1 e 2-3), que entram na direção do eixo Y. |
| `x` | Posição no eixo X. Deve ser `0` quando `direction` é `XP`, porque o furo começa na borda. |
| `y` | Posição no eixo Y. Deve ser `0` quando `direction` é `YP`. |
| `z` | Posição do furo na espessura da peça, entre `0` e a espessura. É a espessura menos a distância do centro do furo até a face interna. |
| `depth` | Profundidade do furo. |
| `diameter` | Diâmetro do furo. |
| `face` | Sempre `"i"`. |

Exemplos de `z`:

- furo no centro da espessura de uma peça de 15 mm: `z` = 7.5;
- furo a 7.5 mm da face interna de uma peça de 25 mm: `z` = 25 − 7.5 = 17.5.

### Furos verticais {#furos-verticais}

| Campo | Descrição |
| --- | --- |
| `corner` | Canto de referência para `x` e `y` (`0` a `3`). |
| `x` | Posição do centro do furo no eixo X. |
| `y` | Posição do centro do furo no eixo Y. |
| `depth` | Profundidade do furo. Em furo passante, a espessura da chapa. |
| `diameter` | Diâmetro do furo. |
| `bolthole` | `true` se o furo é passante (atravessa a peça), como os furos de montagem com parafuso; `false` caso contrário. |
| `face` | Face em que o furo é feito: `"i"` (interna) ou `"e"` (externa). |

### Rasgos e rebaixos {#rasgos-e-rebaixos}

Um **rasgo** é um canal fresado na face da peça, a alguma distância da borda; um **rebaixo** é o mesmo corte encostado na borda. Os dois servem, por exemplo, para encaixar o fundo de um móvel. São sempre feitos ao longo do lado C2 (segmento 2-3), em todo o comprimento da peça.

`furrowMachining` e `furrowMachiningPair` têm a mesma estrutura:

| Campo | Descrição |
| --- | --- |
| `face` | `"i"` em `furrowMachining` e `"e"` em `furrowMachiningPair`. |
| `depth` | Profundidade do corte. |
| `width` | Largura do corte. |
| `distance` | Distância do corte até a borda C2. Com `0`, o corte é um rebaixo; com valor maior que zero, um rasgo. |

`furrowMachiningPair` é para peças com rasgo ou rebaixo nas duas faces, como divisórias e prateleiras que recebem fundo dos dois lados. A miniatura da peça no Cortecloud mostra só o `furrowMachining`; o da face externa não aparece nela.

### Quando a linha de produção não usina {#quando-a-linha-de-producao-nao-usina}

A usinagem só é aplicada se a linha de produção do serviço tiver máquina de usinagem. Se não tiver, as peças são criadas sem usinagem: o Cortecloud guarda o conteúdo de `machining` do arquivo, mas não o aplica às peças nem o cobra no orçamento.

## Dúvidas {#duvidas}

Dúvidas técnicas sobre o formato do arquivo: suporte@serrabits.com.br.