Ingresar

Buenas prácticas

Para lograr una integración estable y eficiente, se recomienda aplicar buenas prácticas al momento de consumir las APIs de ZetaSoftware.
Estas recomendaciones ayudan a reducir errores y mejorar el rendimiento de las integraciones.

1. Validar primero la conexión

Antes de avanzar con una integración completa, se recomienda validar la conexión con una consulta simple.

Ejemplo:

Artículos / Query
Clientes / Query
Proveedores / Query
Datos comerciales de clientes / Query

Esto permite confirmar que las credenciales, la empresa, el usuario, el rol y la API estén correctamente configurados.

2. Utilizar filtros en las consultas

Siempre que el método lo permita, se recomienda utilizar filtros para acotar la información solicitada.

Ejemplo:

Consultar por fecha.
Consultar por código.
Consultar por RUT.
Consultar por cliente.
Consultar por proveedor.
Consultar por local.
Consultar por artículo.

Evitar consultas generales cuando solo se necesita información específica.

3. Utilizar paginación

En los métodos que devuelven listados, se debe utilizar el campo Page para recorrer los resultados.

Ejemplo:

{
  "Data": {
    "Page": <span class="ͼk">"1"</span>
  }
}

Si la respuesta indica que no es la última página, se debe consultar la página siguiente.

Ejemplo conceptual:

{
  "IsLastPage": <span class="ͼj">false</span>,
  "Succeed": <span class="ͼj">true</span>,
  "Response": []
}

En ese caso, se debe consultar:

{
  "Data": {
    "Page": <span class="ͼk">"2"</span>
  }
}

4. Evitar consultas masivas innecesarias

No se recomienda consultar toda la información de la empresa en cada ejecución.

En integraciones frecuentes, es mejor trabajar con consultas incrementales.

Ejemplo:

Consultar únicamente documentos modificados desde una fecha.
Consultar solo artículos activos.
Consultar comprobantes dentro de un rango de fechas.
Guardar localmente información que no cambia con frecuencia.

Esto mejora el rendimiento y evita cargas innecesarias sobre la integración.

5. Validar datos antes de enviar

Antes de enviar un request, se recomienda validar:

Que el JSON esté correctamente formado.
Que los campos obligatorios estén informados.
Que los códigos existan en Zeta.
Que las fechas tengan el formato esperado.
Que los importes tengan el formato correcto.
Que los arrays y objetos respeten la estructura del método.
Que no se envíen campos con tipos de datos incorrectos.

Esto ayuda a evitar errores de formato, errores 400 o rechazos por validación.

6. Evitar duplicar operaciones

En métodos que registran comprobantes, movimientos o datos, se debe controlar que la operación no se envíe más de una vez.

Se recomienda que el sistema externo guarde:

Identificador propio de la operación.
Fecha y hora de envío.
Request enviado.
Response recibido.
Estado del procesamiento.
Identificador devuelto por Zeta, si corresponde.

Esto permite evitar duplicaciones y facilita el seguimiento ante errores.

7. Manejar errores correctamente

Cuando la API devuelve error, no se recomienda reenviar el mismo request en bucle sin analizar la causa.

Se debe identificar si el error corresponde a:

Tipo de error Acción recomendada
Error de credenciales Revisar datos del bloque Connection.
Error de permisos Revisar usuario, rol y permisos en Zeta.
Error de formato Revisar estructura JSON, arrays, objetos y tipos de datos.
Error funcional Revisar códigos, comprobantes, artículos, clientes o configuración.
Error transitorio Reintentar luego de una espera controlada.

8. Controlar la frecuencia de consultas

La frecuencia de consumo debe definirse según el tipo de integración.

Ejemplos:

Proceso Recomendación
Consulta de artículos Sincronizar por cambios o en intervalos controlados.
Consulta de stock Consultar solo cuando sea necesario para la operación.
Consulta de ventas Consultar por rango de fechas.
Consulta de saldos Consultar por cliente o proveedor cuando se requiera.
Registro de comprobantes Enviar bajo demanda, evitando duplicaciones.

No se recomienda ejecutar consultas continuas sin filtros ni intervalos definidos.

9. Proteger credenciales

Las credenciales de desarrollador, empresa y usuario deben almacenarse de forma segura.

No se recomienda:

Compartir credenciales por canales no seguros.
Publicar credenciales en código fuente.
Guardar credenciales en repositorios públicos.
Exponer credenciales en capturas de pantalla.
Enviar credenciales en reportes o consultas de soporte.

Cuando se reporte un error, se debe enviar el body ocultando o reemplazando las claves sensibles.

10. Consultar la documentación específica de cada API

Cada API puede tener campos, filtros, validaciones y estructuras particulares.

Antes de consumir un método se debe revisar:

Endpoint.
Método.
Body requerido.
Campos obligatorios.
Campos opcionales.
Filtros disponibles.
Response esperado.

Recomendación general

  • Consultar solo la información necesaria.
  • Usar filtros y paginación.
  • Validar datos antes de enviar.
  • Controlar duplicados.
  • Guardar logs de request y response.
  • Manejar errores según su causa.
  • Proteger credenciales.
Buenas prácticas - PreviousActualizaciones recientes APIsNext - Buenas prácticasÍndice de APIs
Compartir

Buenas prácticas

O copia el enlace

CONTENIDO