Conceitos
Termos do negócio usados nas rotas e nos guias.
Quem é 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). |
Código 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 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). |
| Marceneiro | Código do cliente no ERP | client.internal_code de um serviço e carpenterInternalCode no login embutido. |
| Linha de produção | Código da linha | productionInternalCode no login embutido. |
Código 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
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 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
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
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). |
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.