# **Best Practices API GO!manage** <br> <table> <colgroup> <col style="width: 27%" /> <col style="width: 72%" /> </colgroup> <tbody> <tr class="odd"> <td><strong>Código Documento</strong></td> <td>Best Practices API GOManage</td> </tr> </tbody> </table> <table> <colgroup> <col style="width: 26%" /> <col style="width: 73%" /> </colgroup> <thead> <tr class="header"> <th><strong>Release</strong></th> <th>2022/5</th> </tr> </thead> <tbody> </tbody> </table> <table> <colgroup> <col style="width: 11%" /> <col style="width: 17%" /> <col style="width: 14%" /> <col style="width: 55%" /> </colgroup> <thead> <tr class="header"> <th><strong>Versión</strong></th> <th><strong>Fecha</strong></th> <th><strong>Realizado por</strong></th> <th><strong>Comentarios</strong></th> </tr> </thead> <tbody> <tr class="odd"> <td>V1.0</td> <td><blockquote> <p>09/6/2022</p> </blockquote></td> <td><blockquote> <p>CMT</p> </blockquote></td> <td><blockquote> <p>Versión Inicial</p> </blockquote></td> </tr> <tr class="even"> <td>V1.1</td> <td>13/1/2021</td> <td>CMT</td> <td>Actualizado a la release 2022.5</td> </tr> <tr class="odd"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="even"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="odd"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="even"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="odd"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="even"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="odd"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="even"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="odd"> <td></td> <td></td> <td></td> <td></td> </tr> <tr class="even"> <td></td> <td></td> <td></td> <td></td> </tr> </tbody> </table> <br> ## Tabla de Contenido ### <a href="#introduccion">Introducción</a> ### <a href="#comprobaciones_inicio">Comprobaciones de Inicio</a> ### <a href="#consideracines_generales">Consideraciones generales</a> ### <a href="#casos_uso">Casos de uso</a> <br> <h2 id="introduccion">Introducción</h2> El objetivo de este documento es el de describir las mejores prácticas que se deberán seguir para integrar GO!Manage con otras aplicaciones externas a través de la API de GO!Manage. El documento está dirigido a integradores que requieren tener un conocimiento funcional de los circuitos de negocios implicados, así como en la programación con API’s.. El documento está estructurado en los siguientes capítulos: - Comprobaciones de inicio. A tener en cuenta para que la API pueda ser consumida por un integrador. - Consideraciones generales de la API. Son generalidades que interesa conocer antes de empezar a consumir la API - Casos de uso. Se explicarán las mejores prácticas para cada caso de uso que requiera consumo de la API. <br> <h2 id="comprobaciones_inicio">Comprobaciones de Inicio</h2> **Verificar que el servicio de PASOE está activo** Para empezar a usar la API de Telematel, a parte de tener la plataforma activa y configurada en GO!Manage, que son acciones que realizan los técnicos de TELEMATEL, es indispensable tener el PASOE arrancado y con los puertos habilitados. Para comprobar que el PASOE está correctamente instalado deberemos acceder a servicios de Windows y localizar el siguiente servicio Progress Application Server Oepas1 y comprobar que esté arrancado: <img src="/images/media/image1.jpg" style="width:6.76875in;height:1.54444in" alt="Interfaz de usuario gráfica, Texto, Aplicación Descripción generada automáticamente" /> Si no está arrancado por cualquier motivo debe arrancarse. Si a pesar de ello no funciona, o es necesario ponerse en contacto con el servicio de atención al cliente de TELEMATEL <br> <h2 id="consideracines_generales">Consideraciones generales</h2> **Usuarios y passwords** Hay que diferenciar los siguientes tipos de usuarios: - <u>El usuario que se utiliza para el token</u>. Este debe ser un usuario existente dentro del maestro de usuarios de GO!Manange, y el password que se envía a la API debe ser coincidente con el que tiene registrado en GO!Manage. Por este motivo se recomienda que este usuario sea siempre el mismo en todos los consumos que se realice desde la API. Por lo tanto, el administrador de GO!Manage debe crear este usuario, asignarle un password y comunicárselo al integrador de la API para que lo utilice en la programación. - <u>Usuario que se utiliza en el consumo de la API tanto como parámetro como tag dentro de un JSON.</u> Este usuario será validado por la API y debe existir dentro de maestro de usuarios de GO!Manage, pero nunca se hace un validación de su contraseña. Una solución sencilla sería utilizar el mismo que se utiliza para el token. <br> **Control seguridad de acceso a la información y a la funcionalidad** La lógica de negocio de GO!Manage delimita el acceso a la información y a la funcionalidad de los usuarios logados a dicha aplicación, en función del perfil de seguridad y propiedades definidas en su ficha. Por ejemplo, el administrador de la seguridad de GO!Manage delimita que el usuario X cuando se loga en la aplicación tenga acceso o no ciertas funcionalidad, a ciertos datos (costes) o ciertos ámbitos de información (empresas). La API lo que permite es la publicación de la información que contiene GO!Manage, así como de su lógica de negocio, pero sin restricciones de seguridad de acceso. Por lo tanto será la aplicación que explota la API la que deba implementar la capa de seguridad. Es decir, definir sus propios usuarios, y la gestión de seguridad. No existe un endpoint para crear usuarios en GO!Manage. <br> <h2 id="casos_uso">Casos de uso</h2> **Gestión de usuarios y de seguridad** Será la aplicación externa la que deberá mantener los usuarios de acceso, así como su gestión de seguridad. Los únicos usuarios que necesita la API son el usuario del token y el usuario referenciado dentro de los documentos. Ambos pueden ser el mismo. <br> **Empresas/delegación** - La sesión de B2C podrá trabajar contra una o varias empresa/delegación de GO!Manage. - Será el B2C el que gestione las posibles empresas/delegaciones de GO!Manage contra las que puede trabajar el usuario logado a dicho B2C. - Será el B2C quien informe de la empresa/delegación en el consumo de la API. <br> **Obtención maestros de forma incremental** Existen determinados maestros que la API permite recoger sólo aquellos registros que han tenido cambios (alta, baja, modificación) desde la última replicación. Es la aplicación externa la que ha de registrar la fecha de esta última replicación. Será el endpoint tipo Pending el que permitirá obtener sólo la lista de registros modificados desde una fecha concreta. <u>Catálogo de artículos</u> La API sólo devolverá artículos que estén marcados en GO!Manage como publicados. Además, también permitirá obtener: - Documentos relacionados con el artículo. - Condición comercial de venta de un artículo - Condición comercial de venta de varios artículos en forma de array - Stock de un artículo - Stock de varios artículos en forma de array Endpoints: Apitmt-products <u>Cliente</u> Los usuarios que compran en el B2C son “Clientes no habituales” según la terminología de GO!Manage. Los diferentes clientes no habituales que utilice el B2B deberán crearse manualmente, y anticipadamente en GO!Manage. Será el B2C quien informará en los JSON de la API el código de cliente no habitual. Los usuarios que compran en un B2B son “clientes habituales”. Estos deberán estar creados en GO!Manage antes de ser referenciados por el B2B. Será el B2B quien asociará el usuario del B2B con el código de cliente que se informe en el JSON de la API. Además, también permite: - Consultar el riesgo del cliente Endpoints: Apitmt-customers <u>Contactos de clientes</u> Permite obtener contactos de clientes. Endpoints: Apitmt-contacts <u>Direcciones de clientes</u> Permite obtener las direcciones de los clientes. Endpoints: Apitmt-customeraddresses <u>Clientes potenciales</u> Permite obtener los clientes potenciales Endpoints: Apitmt-potencialcustomer <br> **Obtención de maestros de forma acotada** La API permite recoger de forma acotada los registros deseados. La acotación se realiza filtrando por los parámetros que se definen en la documentación de la API. Los tipos de maestros que se pueden obtener son: <u>Maestros incrementales</u> Todos los maestros que permiten obtener registros de forma incremental también lo permiten de forma acotada. <u>Transportistas</u> Endpoints: Apitmt-carriermethods <u>Formas de pago</u> Endpoints: Apitmt-paymentmethods <u>Clasificaciones de artículos</u> La API comparte todos los tipos de clasificaciones Será la aplicación externa la que determine con que tipo o tipos de clasificaciones querrá trabajar. También recaerá en la lógica de la aplicación externa determinar si muestra o no los artículos que están o no en cada clasificación. Endpoints: Apitmt-product-families <u>Unidades de embalaje del artículo</u> Además de obtener las posibles unidades de venta del artículo, también proporciona las cantidades mínimas y múltiples de venta. Endpoints: Apitmt-product-packingunits <u>Gestión documental</u> Permite obtener la gestión documental asociada con cualquier maestro que disponga de la misma. Por ejemplo: imágenes de artículos. Endpoints: Apitmt-documents <br> **Obtención de documentos de forma acotada** La API permite recoger de forma acotada los registros deseados. La acotación se realiza filtrando por los parámetros que se definen en la documentación de la API. Los tipos de documentos que se pueden obtener son: <u>Acciones comerciales</u> Endpoints: Apitmt-commercial-actions <u>Ofertas/presupuestos de venta</u> Además, también permite obtener: - Calcular costes de envío según la lógica de GO!Manage - El pdf de la oferta - Documentos relacionados con la oferta Endpoints: Apitmt-sales-offers <u>Pedidos de venta</u> Además, también permite obtener: - Calcular costes de envío según la lógica de GO!Manage - El pdf del pedido - El pdf de la factura asociada con el pedido - Documentos relacionados con el pedido Endpoints: Apitmt-sales-orders <u>Albaranes de venta</u> Además, también permite obtener: - El pdf del albarán - Documentos relacionados con el albarán Endpoints: Apitmt-deliverynotes <u>Facturas de venta</u> Además, también permite obtener: - El pdf de la factura - Documentos relacionados con la factura Endpoints: Apitmt-sales-invoices <u>Efectos de cobro</u> Endpoints: Apitmt-billsreceivable <u>Gestión documental</u> Permite obtener la gestión documental asociada con cualquier documento de GO!Manage que disponga de la misma. Endpoints: Apitmt-documents <br> **Obtención de maestros y documentos por graphQL** La API permite, mediante mediante una sintaxis concreta de graphQL, puede obtener registros de múltiples tablas de GO!Manage. Permite interrogar a la base de datos para acotar los registros a considerar, y definir los campos que se precisan. En el manual de ayuda de la API se concreta su funcionamiento y alcance. <br> **Creación y modificación de maestros** La API permite para ciertos maestros crear nuevos registros, modificar y/o eliminar los existentes. Estos tipos de maestros son: <u>Contactos de clientes</u> Permite crear y modificar Endpoints: Apitmt-contacts <u>Direcciones de clientes</u> Permite crear y modificar. Endpoints: Apitmt-customeraddresses <u>Clientes potenciales</u> Permite crear y modificar Endpoints: Apitmt-potencialcustomer <br> **Creación y modificación de documentos** La API permite para ciertos documentos crear nuevos registros, modificar y/o eliminar los existentes. Estos tipos de documentos son: <u>Notificaciones de entrega</u> Permite crear. Endpoints: Apitmt-purchases-deliverynotification <u>Ofertas/presupuestos de venta</u> Permite: - Borrar - Crear - Aceptar - Modificar Endpoints: Apitmt-sales-offers <u>Pedidos de venta</u> Permite: - Crear - Crear anticipo asociado con el pedido Endpoints: Apitmt-sales-orders