# Conceitos

> Termos usados nas rotas: central, marceneiro, vendedor, código interno, materiais, serviço e códigos de status do serviço.

URL canônica: https://apis.cortecloud.com.br/docs/comecando/conceitos/

Termos do negócio usados nas rotas e nos guias.

## Quem é quem {#quem-e-quem}

| Termo | Significado |
| --- | --- |
| **Central de serviço** (central) | Empresa que vende os materiais e produz as peças encomendadas pelos marceneiros. Os dados que a sua integração lê e altera são sempre de uma central. |
| **Marceneiro** | Cliente da central: profissional que projeta e monta móveis e encomenda as peças pelo Cortecloud. Nas rotas, `carpenter`. |
| **Vendedor** | Funcionário da central que atende o marceneiro. Nas rotas, `seller`, identificado pelo e-mail. |
| **Integração** | O seu sistema, identificado pela api key (ver [Autenticação](https://apis.cortecloud.com.br/docs/comecando/autenticacao.md)). |

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

A API identifica centrais, materiais, serviços e marceneiros pelo **código interno** (`internal_code`): o código que identifica o registro no sistema da central, normalmente o ERP. Assim a sua integração trabalha com os códigos que já conhece, e não com os ids do Cortecloud.

| Registro | Código interno | Onde aparece |
| --- | --- | --- |
| Central | Código da central | Cabeçalho `x-company-internal-code` de toda requisição. |
| Material | Código do item no ERP | `internal_code` nas rotas de [materiais](https://apis.cortecloud.com.br/docs/guias/integracao-erp/materiais.md) e nos materiais e peças de um serviço. |
| Serviço | Número do pedido no ERP | `internal_code` do serviço, gravado pela sua integração (ver [Atualizar serviços](https://apis.cortecloud.com.br/docs/guias/integracao-erp/atualizar-servicos.md)). |
| Marceneiro | Código do cliente no ERP | `client.internal_code` de um serviço e `carpenterInternalCode` no [login embutido](https://apis.cortecloud.com.br/docs/guias/login-embutido.md). |
| Linha de produção | Código da linha | `productionInternalCode` no [login embutido](https://apis.cortecloud.com.br/docs/guias/login-embutido.md). |

### Código da central {#codigo-da-central}

Cada requisição atua sobre uma única central, indicada pelo código dela no cabeçalho `x-company-internal-code`. Uma mesma api key pode estar vinculada a várias centrais: para trabalhar com outra central, troque o valor do cabeçalho. Se você não sabe o código da central que vai integrar, peça-o ao suporte junto com as credenciais.

## Materiais {#materiais}

Os materiais são os itens que a central vende e que compõem um serviço. São de três tipos:

| Tipo | Na API | O que é |
| --- | --- | --- |
| **Chapa** | `boards` | Painel de MDF, MDP ou similar de onde as peças são cortadas. |
| **Fita de borda** | `edges` | Fita que reveste e dá acabamento às bordas das peças cortadas. |
| **Componente** | `components` | Ferragens e acessórios, como dobradiças, corrediças, puxadores e parafusos. |

Cada material tem:

- **`internal_code`**: o [código interno](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#codigo-interno) do item. Materiais sem código interno não aparecem nas rotas.
- **`active`**: se o item está ativo na central.
- **`price`**: preço do item na central.
- **`stock`**: estoque disponível.
- **`unit`**: unidade de arredondamento do item (opcional).

## Serviço {#servico}

Um **serviço** é um pedido de peças cortadas sob medida feito no Cortecloud por um marceneiro (ou por um vendedor em nome dele) a uma central. Corresponde a um pedido no seu ERP. É identificado pelo `id` numérico do Cortecloud e, depois que a sua integração o associa a um pedido, também pelo `internal_code` (o número do pedido no ERP).

O conteúdo de um serviço inclui:

- **peças**: cada pedaço cortado de uma chapa, com medidas, quantidade, fitas de borda aplicadas em cada lado (`c1`, `c2`, `l1`, `l2`), furações e usinagens;
- **materiais consumidos**: chapas, fitas de borda e componentes, com quantidade e preço;
- **mão de obra**: corte, aplicação de fita, usinagem (furos e rasgos), embalagem e frete;
- **status** e histórico de mudanças de status.

O serviço é produzido numa **linha de produção** da central, a unidade que corta e acaba as peças.

## Status do serviço {#status-do-servico}

O status (`status.code`) indica em que etapa o serviço está. A API trabalha com estes:

| Código | Status | Significado |
| --- | --- | --- |
| `4` | Orçamento gerado | O Cortecloud calculou o orçamento e o serviço aguarda a aprovação do marceneiro. |
| `25` | Aguardando pagamento online | O marceneiro escolheu pagar online e o pagamento está em andamento no checkout da central (ver [Checkout de pagamento](https://apis.cortecloud.com.br/docs/guias/checkout.md)). |
| `6` | Aprovado | O orçamento foi aprovado; o serviço pode ser enviado para produção. |
| `7` | Enviado para produção | O serviço foi enviado para a linha de produção. |
| `9` | Produzido | As peças foram produzidas. |

`GET /services` lista serviços em qualquer um desses status, e a associação de `internal_code` só é aceita com o serviço num deles.

O caminho mais comum é orçamento gerado (`4`) → aprovado (`6`) → enviado para produção (`7`) → produzido (`9`). Com pagamento online, o serviço passa por aguardando pagamento online (`25`) entre `4` e `6`; se o pagamento for cancelado, volta para `4`. O estorno de um pagamento já confirmado também leva o serviço de `6` de volta para `4`.

O Cortecloud tem outros status internos (por exemplo, serviço salvo e ainda sem orçamento, em otimização, cancelado ou arquivado). `GET /services` não aceita esses códigos no filtro `status`, e a associação de `internal_code` é recusada para serviços neles.