Developers Esofitec |

Documentación de la API de a3ERP donde se explican los diferentes métodos que la componen así como la manera de interactuar con ella.

A continuación se explica la manera de interactuar con los métodos usando el token de autenticación, cómo funciona la paginación de la API, cómo se envían los parámetros en los métodos GET, cómo se comprueba si un método POST ha funcionado correctamente y cómo trabajar con los nombres de los campos de las respuestas/peticiones

Todos los métodos que se incluyen en la documentación son modificables según la necesidad del cliente.

1. TOKEN DE AUTENTIFICACIÓN

Para autentificarnos en la API y obtener el token es necesario usar el endpoint "/api/Login" pasándole los parámetros "UserID" y "Password" como se puede observar en el método Login.

Una vez que tenemos el Token de autorización el siguiente paso es añadirlo en el header "Authorization" ya que este token es requerido por todos los métodos de la API.

2. PAGINACIÓN

2.1 ¿Cómo funciona la paginación?

Por defecto, si no se le envía ningún parámetro, la API pagina los resultados en páginas de 50 elementos cada una y habiendo tantas páginas como sean necesarias. Por defecto te posiciona siempre en la primera página.

Ejemplo: https://127.0.0.1/api/proc/Clientes

También se le puede indicar cuántos registros queremos por página y sobre qué página queremos situarnos (el máximo número de elementos por página es 50). En el ejemplo de abajo estamos navegando a la página número 2 con una cantidad de 20 registros por página.

Ejemplo: https://127.0.0.1/api/proc/Clientes?pageSize=20&PageNumber=2

2.2 ¿Cómo sabemos cuántas páginas tiene nuestra respuesta y cuantos registros?

En los headers de la respuesta, se almacena una etiqueta llamada “X-Pagination” que contiene diversa información:

Cuántos registros hay en total (“TotalCount”:165)
De qué tamaño es la página (“PageSize”: 50)
Cuál es la página actual (“CurrentPage”: 1)
Número total de páginas (“TotalPages”: 4)
Si tiene página siguiente (“HasNextPage”: true)
Si tiene página anterior (“HasPreviousPage”: false)

Ejemplo: X-Pagination: {"TotalCount":165,"PageSize":50,"CurrentPage":1,"TotalPages":4,"HasNextPage":true,"HasPreviousPage":false}

Lo que se suele hacer, si el lenguaje lo permite, es deserializar esta etiqueta en un objeto para trabajar más cómodamente.

3. ¿CÓMO SE ENVÍAN LOS PARÁMETROS EN LOS MÉTODOS GET?

Los parámetros se envían en el header "Parameters" con un formato JSON codificado en base64.

Imaginemos que queremos buscar un cliente con el siguiente código de cliente " 1". Lo que deberemos hacer es crear un JSON indicandole el parámetro y su valor. Recordemos que, por ejemplo, el código de un cliente está formado por 8 caracteres por lo que debemos de rellenar con espacios a la izquierda para completar la cantidad de 8 caracteres.

Ejemplo:

{
"codcli": " 1"
}

Una vez tengamos el JSON bien formado procederemos a encodearlo a base64. El anterior JSON en base64 quedaría de la siguiente manera:

JSON en base64: ewoiQGNvZGNsaSI6ICIgICAgICAgMSIKfQ==

Una vez tengamos el JSON encodeado en base64 el último paso es añadirlo al header "Parameters" y listo.

4. ¿CÓMO SE COMPRUEBA SI HA FUNCIONADO CORRECTAMENTE UN MÉTODO POST?

Para saber si la petición de un método POST ha ido como esperábamos es necesario coger el número de tarea que nos ha devuelto el método POST y realizar una llamada al método Task con dicho número.

Cuando hacemos una llamada a un método POST nos devuelve un JSON con este formato:

{
"TaskId": 23,
"ItemsBefore": 0
}

Imaginemos que nos ha devuelto el número 23 en el campo "TaskId". Tendremos que llamar al método Task pasándole el parámetro "TaskId" en el propio path de la llamada.

Ejemplo: https://127.0.0.1/api/task/23

5. ¿CÓMO ME ACLARO CON LOS NOMBRES DE LOS CAMPOS?

Los campos tienen nombres que en ocasiones resultan descriptivos y en otras no.

Para saber a qué campo de a3ERP hace referencia cada campo de la API basta con acceder en a3ERP a "Ficheros" (Esquina superior izquierda) > "Listado de ficheros". A continuación, se nos abrirá una ventana en la que podremos seleccionar un fichero (por ejemplo "Cabeceras de facturas de venta") para ver todos sus campos así como la descripción de cada uno de ellos. Una vez seleccionado le damos a la flecha que hay a la derecha del botón "Imprimir" y podremos guardarlo en .PDF para así poder buscar más agilmente cualquier nombre de campo o cualquier descripción para ver en qué campo está contemplada la información que queremos buscar.

6. Algunos consejos

Establecer fechas en formato ISO 8601 (yyyy-MM-ddTHH:mm:ss[.mmm]) tiene la ventaja de utilizar un estándar internacional con una especificación inequívoca (p.e. evitamos ambigüedades de tipo dd/MM/yyyy vs MM/dd/yyyy).

Al dar de alta documentos (como pedidos, albaranes o facturas) no es necesario tratar de establecer todos sus campos. Pocos son realmente los campos obligatorios (por ejemplo, la fecha, código de cliente/proveedor, líneas del documento con código de artículo y unidades...), el resto se establecerán por defecto según la configuración establecida en a3ERP para esa empresa. Por otra parte, existen campos no editables por el usuario (son calculados por el ERP) y tratar de establecerlos puede provocar el rechazo del ERP para registrar el documento.

Por otra parte, no es lo mismo establecer un valor 0 (en caso de campos numéricos) o "" (en caso de campos de tipo cadena) que null.

Asimismo, en el alta de documentos (como pedidos, albaranes o facturas) si se establecen precios en las líneas, éstos deben indicarse en campos distintos según se haya establecido en la cabecera del documento que éstos incluyen o no IVA mediante el campo IVAINCLUIDO. En el caso de IVAINCLUIDO=T deberá indicarse el precio mediante el campo PRCMONEDAMASIVA, mientras en en caso contrario deberá establecerse mediante el campo PRCMONEDA (y solo se deberá establecer el campo de precio correspondiente según valor establecido en IVAINCLUIDO, exclusivamente).

Muchos códigos en a3ERP (p.e. CODCLI, CODPRO, CODART,...) están formateados de modo que, en el caso de que su valor solo se componga de dígitos numéricos, se rellene hasta la longitud máxima del campo mediante espacios a la izquierda (de modo que se visualice como un número con alineación derecha). Esto debe ser tenido en cuenta en consultas y al establecer valores sobre este tipo de campos (no es lo mismo un código de cliente "328" -sin espacios, que nunca se registra así en a3ERP"- que el código realmente formateado " 328", rellenando con 5 espacios en blanco para completar su longitud máxima de 8 caracteres). Cuando los valores son alfanuméricos (contienen alguna letra o carácter no numérico) entonces pueden tener una longitud inferior a la máxima determinada para ese campo de código (por ejemplo el CODCLI "CON12")