Conceptos
Términos del negocio usados en las rutas y en las guías.
Quién es quién
| Término | Significado |
|---|---|
| Central de servicio (central) | Empresa que vende los materiales y produce las piezas encargadas por los carpinteros. Los datos que su integración lee y modifica son siempre de una central. |
| Carpintero | Cliente de la central: profesional que diseña y arma muebles y encarga las piezas a través de Cortecloud. En las rutas, carpenter. |
| Vendedor | Empleado de la central que atiende al carpintero. En las rutas, seller, identificado por el correo electrónico. |
| Integración | Su sistema, identificado por la api key (ver Autenticación). |
Código interno
La API identifica centrales, materiales, servicios y carpinteros por el código interno (internal_code): el código que identifica el registro en el sistema de la central, normalmente el ERP. Así su integración trabaja con los códigos que ya conoce, y no con los ids de Cortecloud.
| Registro | Código interno | Dónde aparece |
|---|---|---|
| Central | Código de la central | Encabezado x-company-internal-code de cada solicitud. |
| Material | Código del ítem en el ERP | internal_code en las rutas de materiales y en los materiales y piezas de un servicio. |
| Servicio | Número del pedido en el ERP | internal_code del servicio, que graba su integración (ver Actualizar servicios). |
| Carpintero | Código del cliente en el ERP | client.internal_code de un servicio y carpenterInternalCode en el inicio de sesión integrado. |
| Línea de producción | Código de la línea | productionInternalCode en el inicio de sesión integrado. |
Código de la central
Cada solicitud actúa sobre una única central, indicada por su código en el encabezado x-company-internal-code. Una misma api key puede estar vinculada a varias centrales: para trabajar con otra central, cambie el valor del encabezado. Si no conoce el código de la central que va a integrar, solicítelo a soporte junto con las credenciales.
Materiales
Los materiales son los ítems que la central vende y que componen un servicio. Son de tres tipos:
| Tipo | En la API | Qué es |
|---|---|---|
| Tablero | boards | Panel de MDF, MDP o similar del que se cortan las piezas. |
| Tapacanto | edges | Cinta que reviste y da acabado a los cantos de las piezas cortadas. |
| Componente | components | Herrajes y accesorios, como bisagras, correderas, tiradores y tornillos. |
Cada material tiene:
internal_code: el código interno del ítem. Los materiales sin código interno no aparecen en las rutas.active: si el ítem está activo en la central.price: precio del ítem en la central.stock: stock disponible.unit: unidad de redondeo del ítem (opcional).
Servicio
Un servicio es un pedido de piezas cortadas a medida que un carpintero (o un vendedor en su nombre) hace en Cortecloud a una central. Corresponde a un pedido en su ERP. Se identifica por el id numérico de Cortecloud y, después de que su integración lo asocia a un pedido, también por el internal_code (el número del pedido en el ERP).
El contenido de un servicio incluye:
- piezas: cada trozo cortado de un tablero, con medidas, cantidad, tapacantos aplicados en cada lado (
c1,c2,l1,l2), perforaciones y mecanizados; - materiales consumidos: tableros, tapacantos y componentes, con cantidad y precio;
- mano de obra: corte, aplicación de tapacanto, mecanizado (perforaciones y ranuras), embalaje y flete;
- estado e historial de cambios de estado.
El servicio se produce en una línea de producción de la central, la unidad que corta y da acabado a las piezas.
Estado del servicio
El estado (status.code) indica en qué etapa está el servicio. La API trabaja con estos:
| Código | Estado | Significado |
|---|---|---|
4 | Presupuesto generado | Cortecloud calculó el presupuesto y el servicio espera la aprobación del carpintero. |
25 | Esperando pago en línea | El carpintero eligió pagar en línea y el pago está en curso en el checkout de la central (ver Checkout de pago). |
6 | Aprobado | El presupuesto fue aprobado; el servicio puede enviarse a producción. |
7 | Enviado a producción | El servicio fue enviado a la línea de producción. |
9 | Producido | Las piezas fueron producidas. |
GET /services lista servicios en cualquiera de estos estados, y la asociación de internal_code solo se acepta con el servicio en uno de ellos.
El recorrido más común es presupuesto generado (4) → aprobado (6) → enviado a producción (7) → producido (9). Con pago en línea, el servicio pasa por esperando pago en línea (25) entre 4 y 6; si el pago se cancela, vuelve a 4. El reembolso de un pago ya confirmado también lleva el servicio de 6 de vuelta a 4.
Cortecloud tiene otros estados internos (por ejemplo, servicio guardado y todavía sin presupuesto, en optimización, cancelado o archivado). GET /services no acepta esos códigos en el filtro status, y la asociación de internal_code se rechaza para los servicios que están en ellos.