API de Dibujos Externos. Guía de implementación

PRODUCTOR External Drawings API es una integración de Productor ERP con una API externa que genera los dibujos de las líneas de presupuestos y pedidos.
Está disponible tanto para las aplicaciones de escritorio Productor como para Productor Web,

Este documento está orientado a desarrolladores, responsables técnicos e integradores del cliente. El archivo OpenAPI R8 entregado junto al Sample es la referencia normativa del contrato HTTP/JSON.

Contenido

• 1. Qué debe implementar el cliente

• 2. Arquitectura y escenarios de despliegue

• 3. Puesta en marcha rápida del Sample

• 4. Endpoints y cabeceras HTTP

• 5. Contrato de petición

• 6. Modelo público de línea

• 7. Variables calculadas de línea - R8

• 8. Dibujos por fase de fabricación - ProduccionFase

• 9. Contrato de respuesta y formatos

• 10. Cómo adaptar DemoDrawingGenerator

• 11. Serialización y compatibilidad del modelo PRODUCTOR

• 12. Seguridad

• 13. Logging y trazabilidad en la API del cliente

• 14. Despliegue local y público

• 15. Errores y comportamiento esperado

• 16. Pruebas de integración y homologación

• 17. Diagnóstico de incidencias

• Anexo A. Ejemplo completo R8

• Anexo B. Configuración orientativa del Sample

• Anexo C. Catálogo de errores

1. Qué debe implementar el cliente

PRODUCTOR puede delegar la generación de dibujos de una línea en una WebAPI privada mantenida por el cliente. GAIA entrega el proyecto External Drawings API - Sample como implementación de referencia del contrato. El cliente debe adaptar el generador de demostración para obtener o crear sus dibujos reales, manteniendo intacto el contrato público.

1.1 Responsabilidades del cliente

1.  Desplegar una instancia de la External Drawings API accesible desde PRODUCTOR ERP y, si se utiliza PRODUCTOR Web, desde el backend de PRODUCTOR Web en Azure.

2.  Configurar una API Key suficientemente robusta y conservarla fuera del código fuente.

3.  Adaptar el generador de dibujos del Sample para interpretar la línea recibida y devolver los dibujos adecuados.

4.  Respetar los endpoints, headers, nombres JSON, tokens de enum, tipos de dibujo, formatos MIME y estructura de errores definidos por la versión 1.0.

5.  Mantener un sistema de logging que permita localizar una petición mediante X-Correlation-Id sin registrar secretos ni el contenido Base64 completo.

6.  Probar la implementación con los cuatro tipos de línea que vayan a utilizarse y con las configuraciones funcionales reales del cliente.

1.2 Qué puede modificar en el Sample

2. Arquitectura y escenarios de despliegue

2.1 Servicio sólo en red local

Es válido cuando únicamente PRODUCTOR ERP necesita consumir los dibujos. La API puede escuchar en una URL local accesible desde los equipos/servidores de PRODUCTOR. Si PRODUCTOR Web también debe utilizarla, Azure necesitará conectividad privada expresa hacia esa red o una URL pública.

2.2 Servicio público

Es la opción habitual cuando PRODUCTOR Web debe consumir el servicio. Debe publicarse mediante HTTPS y ser accesible desde el backend de PRODUCTOR Web. PRODUCTOR ERP también puede utilizar la misma URL pública.

2.3 Acceso local y público

El mismo servicio puede exponerse mediante una URL interna y otra pública. El contrato es idéntico en ambos accesos. Esta configuración permite que ERP utilice la red local mientras PRODUCTOR Web utiliza la URL pública.

3. Puesta en marcha rápida del Sample

El proyecto Sample es una ASP.NET Core Web API en C#. No contiene lógica CAD real: su objetivo es demostrar el contrato y ofrecer un punto de extensión seguro.

3.1 Estructura de referencia

3.2 Primera ejecución

1.  Abra el proyecto Sample con un SDK .NET compatible con la versión entregada.

2.  Configure la API Key mediante secret, variable de entorno o configuración protegida. No incluya una clave real en el repositorio.

3.  Ejecute el proyecto con dotnet run o desde el entorno de desarrollo.

4.  Compruebe GET /api/v1/health enviando la API Key.

5.  Realice una petición de prueba a POST /api/v1/drawings con X-Company-Code y X-Correlation-Id.

6.  Una vez validado el contrato, sustituya o adapte DemoDrawingGenerator con la lógica real del cliente.

4. Endpoints y cabeceras HTTP

4.1 Cabeceras de /api/v1/drawings

No existe asociación obligatoria entre API Key y empresa. Si el cliente desea comprobar que X-Company-Code corresponde a una empresa conocida, puede hacerlo como validación funcional y devolver COMPANY_NOT_FOUND (HTTP 422).

4.2 /api/v1/health

El endpoint de salud utiliza la autenticación por API Key, pero no requiere X-Company-Code. Su finalidad es comprobar que el servicio está disponible y que las credenciales configuradas son válidas.

5. Contrato de petición

5.1 Tipos de dibujo

Una misma petición puede solicitar varios tipos. La respuesta siempre contiene una colección Dibujos y puede incluir varios dibujos del mismo tipo.

6. Modelo público de línea

PRODUCTOR no envía un DTO simplificado creado específicamente para esta API. La propiedad Linea utiliza el modelo público PRODUCTOR correspondiente al TipoLinea indicado. El Sample incluye las clases necesarias para deserializarlo.

6.1 Datos que PRODUCTOR no exporta para dibujos

El perfil de exportación excluye información comercial, fiscal, documental o de despiece que no debe ser necesaria para generar el dibujo, como Valor, Impuestos, DatosAuxiliares, FechaEntrega, ObservacionesProduccion, referencias de documento origen y DespieceLinea.

7. Variables calculadas de línea - R8

R8 añade la colección Variables a LineaEstructura, LineaPersiana, LineaToldo y LineaVentana. PRODUCTOR calcula estas variables antes de exportar la línea; la API externa las recibe ya resueltas y puede utilizarlas para adaptar el dibujo.

7.1 Reglas de uso

• La Sample API consume las variables; no debe recalcularlas.

• No existe un catálogo global obligatorio de símbolos. Los símbolos dependen de la configuración/cálculo de PRODUCTOR y del acuerdo funcional de cada integración.

• La colección puede estar vacía.

• Una variable ausente NO equivale a Valor = 0. Sólo hay valor cero cuando el elemento existe y su Valor es 0.

• SimboloVariable debe tratarse como un código opaco. Para búsquedas exactas, el Sample usa comparación ordinal.

• Las variables pueden utilizarse para decidir geometría, componentes, anotaciones, archivos de plantilla o cualquier otro aspecto del dibujo.

7.2 Ejemplo conceptual de lectura

8. Dibujos por fase de fabricación - ProduccionFase

ProduccionFase permite solicitar un dibujo técnico específico para una fase del proceso de fabricación. El único contexto adicional es FaseFabricacion, un código string en el sobre de la petición.

• FaseFabricacion es obligatoria y no puede estar vacía o contener sólo espacios cuando se solicita ProduccionFase.

• PRODUCTOR no traduce ni normaliza el código de fase. El servicio debe tratarlo como un código opaco.

• No se añade ningún identificador de línea específico para ProduccionFase: la petición ya contiene el objeto Linea completo.

• Un request representa como máximo una fase. Si se necesitan dibujos de CORTE y MONTAJE, se realizan dos peticiones independientes.

• Un request mixto puede solicitar, por ejemplo, Presentacion y ProduccionFase. FaseFabricacion sólo aporta contexto al dibujo ProduccionFase.

9. Contrato de respuesta y formatos

9.1 Cero dibujos no es un error

Si la petición es válida pero no existe dibujo para esa configuración, debe devolverse HTTP 200, Exito=true y Dibujos=[]. Puede añadirse un aviso DRAWING_NOT_AVAILABLE. No debe utilizarse HTTP 404 para este caso.

9.2 Límites recomendados

10. Cómo adaptar DemoDrawingGenerator

DemoDrawingGenerator existe únicamente para demostrar el flujo. El cliente debe sustituir o ampliar su lógica para conectarse con su motor de dibujos, CAD, configurador, repositorio de imágenes o sistema industrial.

10.1 Flujo recomendado

1.  Recibir DrawingRequest ya validado.

2.  Examinar TipoLinea y trabajar con la clase pública correspondiente.

3.  Leer medidas, opciones, acabados, complementos y Variables necesarias para la decisión gráfica.

4.  Si se solicita ProduccionFase, utilizar también FaseFabricacion.

5.  Generar o localizar uno o más archivos.

6.  Convertir los bytes a Base64.

7.  Crear uno o más elementos Drawing con Tipo y MimeType correctos.

8.  Devolver DrawingResponse manteniendo IdPeticion de la petición.

10.2 Lógica conceptual

10.3 Reglas que no deben alterarse

• No cambie la ruta /api/v1/drawings.

• No devuelva URLs en sustitución de Contenido Base64 en la versión 1.0.

• No introduzca nombres CLR o metadatos $type en el JSON público.

• No convierta BoolEnum a true/false ni a 0/1.

• No exponga excepciones, stack traces o secretos en DrawingResponse.

• No dependa de que exista siempre una variable concreta salvo acuerdo funcional específico.

11. Serialización y compatibilidad del modelo PRODUCTOR

El Sample contiene una capa de serialización específica para respetar el contrato público PRODUCTOR. No debe sustituirse por la configuración JSON por defecto sin comprobar antes todos los alias y enums.

11.1 BoolEnum

Los campos del modelo público que usan BoolEnum deben viajar como strings "N" o "S". No son booleanos JSON.

11.2 Otros enums

Los enums públicos utilizan sus tokens de XmlEnum. Ejemplos del contrato: I, D, ID, DI, TOTAL, MASCAJON, TAPAJUNTAS, PREMARCO, PERSIANA, etc. El Sample ya incluye el converter necesario.

11.3 Alias de propiedades

Algunas propiedades se publican con nombres XML históricos. El cliente debe consumir los nombres recibidos por el contrato, no deducirlos desde el nombre de la propiedad CLR. Por ejemplo, en LineaVentana se utilizan alias públicos como Perfiles.Acabado y Accesorios.Tonalidad.

11.4 TipoLinea y deserialización polimórfica

TipoLinea actúa como discriminador seguro y sólo admite LineaEstructura, LineaPersiana, LineaToldo o LineaVentana. La API no debe permitir resolución arbitraria de tipos CLR a partir del JSON.

12. Seguridad

13. Logging y trazabilidad en la API del cliente

El Sample utiliza Serilog como implementación de referencia. El cliente puede cambiar sinks o plataforma de observabilidad, pero debe conservar una trazabilidad suficiente para soporte.

Los valores completos de Variables no necesitan registrarse como propiedades estructuradas de Serilog. Para soporte, X-Correlation-Id es la referencia principal que debe conservarse.

14. Despliegue local y público

14.1 Kestrel / Windows Service en red local

La referencia local es ejecutar la misma ASP.NET Core Web API sobre Kestrel, normalmente instalada como Windows Service. La configuración, los logs y los secretos deben mantenerse fuera de la carpeta de binarios para facilitar actualizaciones.

Rutas orientativas del proyecto de referencia:

14.2 IIS, Azure App Service u otro hosting público

El mismo proyecto puede publicarse en IIS, Azure App Service u otro hosting compatible con ASP.NET Core. Dominio, TLS, bindings, certificados, App Settings, secretos y sinks de logging son responsabilidad de la infraestructura del cliente.

14.3 Actualizaciones

1.  Detener la instancia o servicio.

2.  Sustituir los binarios conservando configuración, secretos y logs.

3.  Arrancar de nuevo el servicio.

4.  Ejecutar /api/v1/health.

5.  Realizar al menos una petición /api/v1/drawings de prueba.

6.  Aplicar rollback si la comprobación falla.

15. Errores y comportamiento esperado

15.1 Formato de error

Los códigos son estables y apropiados para lógica; Mensaje es descriptivo para diagnóstico. No utilice mensajes de excepción .NET como contrato público.

16. Pruebas de integración y homologación

Antes de considerar la integración lista, el cliente debería validar como mínimo los siguientes escenarios contra su versión desplegada:

☐ GET /api/v1/health con API Key válida.

☐ 401 con API Key ausente o incorrecta.

☐ 400 si falta X-Company-Code en /drawings.

☐ Una petición válida por cada TipoLinea utilizado.

☐ BoolEnum recibido como N/S.

☐ Variables presentes, vacías y con Valor = 0.

☐ Variable ausente tratada de forma distinta a valor cero.

☐ Presentacion, Produccion y Galeria si se utilizan.

☐ ProduccionFase con FaseFabricacion válida.

☐ 400 PRODUCTION_PHASE_REQUIRED cuando falta la fase.

☐ Dos fases distintas mediante dos requests independientes.

☐ Respuesta con varios dibujos del mismo tipo.

☐ HTTP 200 con Dibujos=[] cuando no existe dibujo.

☐ PNG/JPEG/SVG/PDF según formatos utilizados.

☐ Límites de tamaño configurados.

☐ Logs localizables por X-Correlation-Id y sin secretos/Base64.

☐ Acceso desde PRODUCTOR Web/Azure si la integración lo requiere.

17. Diagnóstico de incidencias

Para soporte, facilite siempre el valor de IdPeticion/X-Correlation-Id, fecha/hora aproximada, CompanyCode, TipoLinea y tipo de dibujo solicitado. No envíe la API Key por canales no seguros.

Anexo A. Ejemplo completo R8

A.1 Petición ProduccionFase con Variables

A.2 Respuesta

Anexo B. Configuración orientativa del Sample

En producción, la API Key real debe suministrarse mediante el mecanismo seguro del entorno. La configuración de Kestrel, certificados, IIS, Azure, Windows Service y sinks de Serilog puede variar sin alterar el contrato HTTP.

Anexo C. Referencias normativas de la entrega

La documentación del cliente debe utilizarse junto con los artefactos entregados con la revisión R8:

• Proyecto External Drawings API - Sample.

• OpenAPI 3.1 de PRODUCTOR External Drawings API v1.0 R8.

• README incluido en el proyecto Sample.

• Modelos públicos PRODUCTOR incluidos en ProductorModel/.

GAIA Software - PRODUCTOR External Drawings API v1.0 - R8