Documentación para el Desarrollador

Los Desarrolladores e Integradores de soluciones para empresas que necesitan utilizar las APIs de ZetaSoftware deberán registrarse previamente para obtener el Código y la Clave.

Todos los llamados a las APIs de ZetaSoftware deberán realizarse enviando:

• Código y Clave de la Empresa. (Estos datos serán proporcionados por la propia empresa al Desarrollador)

• Código y Clave del Desarrollador. (Estos datos serán proporcionados por ZetaSoftware al Desarrollador)
  

ZetaSoftware se guarda el derecho a suspender la habilitación de un Desarrollador en cualquier momento y sin previo aviso, cuando el uso de las APIs se realice de forma incorrecta o que pueda afectar la estabilidad de ZetaSoftware y su infraestructura.

El Desarrollador debe conocer la operativa de nuestra aplicación, al igual que el uso que le da el cliente, e ir ejecutando la integración en conjunto con el cliente, generando tantas instancias de consultas como se consideren necesarias.

Para poder importar o exportar información, el desarrollador debe estar en conocimiento de los datos que la empresa tenga cargados en ZetaSoftware. El trabajo en conjunto entre el desarrollador y el cliente es parte fundamental del proceso.
A manera de ejemplo, si se deseara importar comprobantes de venta, el desarrollador precisará saber datos específicos para poder realizar la gestión (códigos de comprobantes a utilizar, códigos de depósitos, códigos de vendedores, códigos de formas de pago, etc.).
Es tarea del cliente brindar este y cualquier otro dato que el desarrollador considere pertinente.

Salvo que existieran consultas técnicas, que serán resueltas entre el desarrollador y ZetaSoftware, la gran mayoría de consultas que se generen serán operativas o de datos y deberán ser resueltas entre el desarrollador y la empresa.

Todo consumo de un Método, tanto sea por el protocolo SOAP como REST, necesitará establecer los datos básicos de conexión. Estos datos son los que definen los niveles de seguridad al usar los distintos métodos para manipular la información de cada entidad publicada.

Los campos que siempre se requieren para realizar la conexión son los siguientes:

• DesarrolladorCodigo: Código de Desarrollador otorgado en ZetaSoftware. El dato se corresponde al anterior PartnerId.

• DesarrolladorClave: Clave de Desarrollador asignada por ZetaSoftware, El dato se corresponde a la anterior PartnerKey

• EmpresaCodigo: Código de la empresa. La misma será recibida vía email (junto al siguiente dato) cuando la empresa habilite el acceso al desarrollador.

• EmpresaClave: Clave de la empresa. Cada Desarrollador tendrá una clave diferente para la misma empresa.

• RolCodigo: Código del Rol del Usuario. Dato numérico de hasta dos dígitos que debe representar a un rol existente en la empresa en cuestión. Se sugiere crear un Rol específico para el Desarrollador. No se tomarán en cuenta los permisos de dicho Rol/usuario, solo se utilizará para verificar que exista en la configuración de la empresa.

El proceso de manipulación de datos de una entidad ofrece una serie de Métodos en donde cada uno cumple funciones específicas, las cuales describimos a continuación:

1. MÉTODO QUERY

El método Query tiene como objetivo desplegar una lista de registros de una entidad. La consulta puede contener las siguientes campos o subestructuras:

Datos de envío

Búsqueda genérica

En algunas consultas podrá existir el campo Search que implica una búsqueda genérica de una palabra en un conjunto de campos (por lo general de formato texto) pre-establecidos por el sistema. Por ejemplo, en el Search de clientes se puede indicar parte del nombre, el cual será buscado tanto en el nombre del cliente como en su Razón Social.

Filtros

Los filtros permitirán segmentar o restringir el resultado de la lista resultante sobre campos específicos de la entidad. Los filtros podrán tener tres tipos de condición de búsqueda:

1. Búsqueda por rango: Se disponen dos campos (Desde/Hasta) para buscar valores entre dichos márgenes. Típicamente se usan para campos numéricos o de fechas.

2. Búsqueda por contenido o like: Se busca el texto indicado en este filtro en cualquier parte del texto del campo sobre el que se está buscando. Por ejemplo, si se busca el texto Juan en el nombre del cliente, se obtendrán todos los registros donde Juan sea parte del nombre.

3. Búsqueda por igualación: Se busca el valor ingresado en el filtro por el valor exacto.Por ejemplo, si se desean obtener todas las facturas de un determinado código de cliente.

Paginado (Page)

Todo Query va a devolver una lista de hasta 500 registros, lo cual se hace así para no saturar el uso de los servicios. El campo Page permite indicar la página correspondiente, por lo que si se indica el valor 3, se obtendrán los registros del 1500 al 1999. Si no se indica valor alguno a este campo devolverá siempre la primera página resultante de la consulta, o sea los primeros 500 registros.

Datos de devolución

• Success: Valor Boolean que indica si la consulta se pudo realizar o no. En caso de fallo, típicamente es un fallo relacionado con los datos de conexión.

• Error: En caso de que el valor Success devuelve False se devolverá una estructura donde se detalla el motivo del error con los siguientes campos:

  • Code: Código interno del error.

  • Message: Mensaje detallando el error.

  • Response: Lugar donde se devolverá la lista de registros resultante de la consulta.

2. MÉTODO LOAD

El método Load tiene como objetivo obtener la información completa de un registro.

En el caso de que el Query no contenga la totalidad de campos de la entidad será necesario ejecutar este método para obtener la totalidad de campos antes de solicitar una modificación de algún valor a través del método Save.

En algunas entidades podrán existir resultados que no solo contendrán los datos del registro de la tabla principal de la misma sino que puede contener adicionalmente la lista de registros de una o más tablas subordinadas a la entidad. Estas situaciones suceden cuando es importante almacenar la totalidad de la información de la tabla principal de la entidad junto con el resto de las tablas subordinadas en un solo Commit. Típicamente en base de datos se denomina participar de una única UTL (Unidad de Transacción Lógica).

Datos de envío: Los datos de envío en este método serán siempre la(s) clave(s) de la entidad.

Datos de devolución

• Success: Valor Boolean que indica si la consulta se pudo realizar o no. En caso de fallo, típicamente es un fallo relacionado con los datos de conexión.

• Error: En caso de que el valor Success devuelve False se devolverá una estructura donde se detalla el motivo del error con los siguientes campos:

  • Code: Código interno del error.

  • Message: Mensaje detallando el error.

  • Response: Lugar donde se devolverá la totalidad de campos de la tabla principal de la entidad. En caso de que esta entidad maneje tablas subordinadas que se necesitan actualizar en la misma UTL también devolverá la totalidad de los registros de cada una de dichas tablas subordinadas.

3. MÉTODO SAVE

El método Save tiene como objetivo insertar o actualizar la información completa de un registro.

En algunas entidades podrán tener que enviarse datos que no solo contendrán los campos del registro de la tabla principal de la misma sino que puede tener que informarse adicionalmente la lista de registros de una o más tablas subordinadas a la entidad. Estas situaciones suceden cuando es importante almacenar la totalidad de la información de la tabla principal de la entidad junto con el resto de las tablas subordinadas en un solo Commit. Típicamente en base de datos se denomina participar de una única UTL (Unidad de Transacción Lógica).

Datos de envío: Los datos de envío en este método serán siempre la totalidad de campos de la entidad.

Datos de devolución:

• Success: Valor Boolean que indica si la inserción o actualización se pudo realizar o no.

• Error: En caso de que el valor Success devuelve False se devolverá una estructura donde se detalla el motivo del error con los siguientes campos:

  • Code: Código interno del error.

  • Message: Mensaje detallando el error.

  • Detail: Lista de errores detallados con la siguiente estructura:

  • Id: Identificación interna del error específico.

  • Tipo: Error o Warning.

  • Descripcion: Detalle del error específico.

4. MÉTODO DELETE

El método Delete tiene como objetivo eliminar un registro.

Datos de envío: Los datos de envío en este método serán siempre la(s) clave(s) de la entidad.

Datos de devolución:

• Success: Valor Boolean que indica si la eliminación se pudo realizar o no.

• Error: En caso de que el valor Success devuelve False se devolverá una estructura donde se detalla el motivo del error con los siguientes campos:

  • Code: Código interno del error.

  • Message: Mensaje detallando el error.

  • Detail: Lista de errores detallados con la siguiente estructura:

  • Id: Identificación interna del error específico.

  • Tipo: Error o Warning.

  • Descripcion: Detalle del error específico.