Facturas de Clientes

El API de Facturas de Clientes proporciona un mecanismo para gestionar diversas transacciones comerciales con clientes, incluidos los Movimientos de Ventas y Stock, así como Recibos de Cobro. El objetivo primordial de esta API es permitir la inserción precisa y eficiente de nuevos movimientos financieros y de stock en el sistema. No está diseñada para actualizar movimientos ya existentes. Debido a la naturaleza compleja de la configuración empresarial, la implementación de esta API requiere un conocimiento profundo de los parámetros de la empresa y la participación activa de los usuarios responsables.

URL y Servicio

• Descripción: https://api.zetasoftware.com/z.apis.asoapfacturaclientev4?wsdl
• Servicio: https://api.zetasoftware.com/z.apis.asoapfacturaclientev4

Método Agregar

Este método se especializa en la generación de comprobantes de diversos tipos como Venta Contado, Venta Crédito, y respectivas notas correctivas, además de Movimientos de Stock de clientes (Pedidos y Remitos) y Recibos de Cobro.

Datos para el Encabezado del Comprobante

1. CodigoComprobante: N(3) – Obligatorio. Define el tipo del movimiento: Venta Crédito, Venta Contado, Remito, Recibo, etc.
2. Serie: T(6) – Si el comprobante es un CFE, se asignará automáticamente al momento de emitir. Si no es un CFE, si no tiene Formato de Impresión y tiene Numerador asignado, la Serie se generará en forma automática.
3. Numero: N(10) – Si el comprobante es un CFE, se asignará automáticamente al momento de emitir. Si no es un CFE, si no tiene Formato de Impresión y tiene Numerador asignado, el número se generará en forma automática.
4. Fecha: AAAAMMDD – Obligatorio.
5. CodigoMoneda: N(2) – Obligatorio.
6. Cotizacion: N(7.7) – Valor de cotización de la moneda.
7. CodigoCliente: N(10) – Identifica al cliente.
8. CodigoVendedor: T(3) – Identifica al vendedor.
9. CodigoPrecio: N(3) – Código de la lista de precios aplicada.
10. CodigoCondicionPago: N(3) – Aplica solo a comprobantes del tipo venta crédito.
11. CodigoDepositoOrigen: N(3) – Depósito de origen en movimientos de stock.
12. CodigoDepositoDestino: N(3) – Depósito de destino en movimientos de stock.
13. FechaEntrega: AAAAMMDD – Fecha prevista para la entrega de productos.
14. CodigoCentroCosto: T(10) – Centro de costo al que se asocia el movimiento.
15. CodigoReferencia: N(10) – Código de referencia externa.
16. Notas: T(30) – Notas adicionales. Obligatorio enviar el valor «#CUENTAAJENA» si es una venta por cuenta ajena.
17. TotalRecibo: N(10.2) – Solo para comprobantes del tipo recibo de cobro.
18. CodigoLocal: N(3) – Código del local comercial.
19. CodigoUsuario: N(3) – Código del usuario que realiza la operación.
20. CodigoCaja: N(3) – Código de la caja que registra la operación.

Datos Eventuales del Clientes

Los «Datos Eventuales» ofrecen una capa adicional de especificidad y flexibilidad en el encabezado del comprobante. Estos campos son especialmente críticos en casos de comprobantes de venta por cuenta ajena, donde los mismos deben ser obligatoriamente informados. De igual forma, algunos de estos campos adquieren carácter obligatorio bajo determinadas condiciones fiscales o montos de transacción.

1. ClienteNombre: T(100) – Obligatorio si el comprobante es de venta por cuenta ajena. Debe corresponder al proveedor en ese caso.
2. ClienteTipoDocumento: T(1) – Valores aceptados son variados como R para RUT, C para Cédula Uruguaya, P para Pasaporte, D para DNI en ciertos países, y la letra O para Otro.
   Es obligatorio si el comprobante es de venta por cuenta ajena, y en ese caso, debe reflejar el documento del proveedor.
3. ClientePais: T(3) – Debe ser un código de país válido. Obligatorio si el comprobante es de venta por cuenta ajena, y en ese caso, debe corresponder al proveedor.
4. ClienteDocumento: T(30) – Formato sin puntos, guiones ni espacios. Es obligatorio si el monto del comprobante sin impuestos supera ciertos umbrales específicos. También es obligatorio si el comprobante es de venta por cuenta ajena.
5. ClienteDireccion: T(100) – Dirección del cliente. Obligatorio si el comprobante es de venta por cuenta ajena, y en ese caso, debe corresponder al proveedor.
6. ClienteDepartamento: T(50) – Es obligatorio si el comprobante es de venta por cuenta ajena, y en ese caso, debe corresponder al proveedor.
7. ClienteCiudad: T(50) – Es obligatorio si el comprobante es de venta por cuenta ajena, y en ese caso, debe corresponder al proveedor.
8. ClienteCP: N(10) – Código Postal del cliente.
9. ClienteTelefono: T(30) – Número de teléfono del cliente.
10. ClienteSucursal: N(3) – Código de la sucursal del cliente.
11. ClienteEmail: T(50) – Dirección de correo electrónico del cliente.
12. ClienteEntrega: T(100) – Dirección de entrega, relevante si difiere de ClienteDireccion.

Artículos de la Factura

La sección de «Líneas del comprobante» en la API es crítica para la exactitud y la completitud de las transacciones, ya que dicta los detalles de cada artículo incluido en el comprobante. Este segmento se itera tantas veces como sea necesario para incluir todos los artículos pertinentes, asegurando así que cada elemento del movimiento esté debidamente registrado y valorado.

1. CodigoArticulo: T(20) – Este campo identifica de manera única el artículo involucrado en la transacción.
2. Concepto: T(50) – Este campo describe el concepto o la naturaleza del artículo.
3. CodigoLote: T(20) – Obligatorio si el artículo está sujeto a un sistema de lote.
4. Vencimiento: T(AAAAMMDD) – Este campo es obligatorio si el artículo tiene una fecha de vencimiento.
5. Cantidad: N(17.5) – Este campo es obligatorio y debe ser un número mayor a cero.
6. PrecioUnitario: N(17.5) – Este campo define el precio unitario del artículo. El IVA puede estar incluido o excluido, dependiendo de la configuración del comprobante. El cálculo de los totales se efectúa automáticamente.
7. Descuento1, Descuento2, Descuento3: N(5.2) – Estos campos permiten aplicar hasta tres descuentos distintos en el artículo. Si no se aplica ningún descuento, el valor debe ser cero.
8. CodigoIVA: N(2) – Este campo puede o no coincidir con el código de IVA del artículo pero es fundamental para calcular correctamente el IVA en la transacción.
9. Notas: T(1000) – Este es un campo flexible para agregar cualquier anotación o detalle adicional que pueda ser relevante para el movimiento.

Cada uno de estos campos tiene un propósito específico y contribuye al éxito de la transacción. Por ejemplo, el campo CodigoLote y Vencimiento son esenciales para empresas en la industria alimentaria o farmacéutica donde el seguimiento de lotes y fechas de vencimiento es una necesidad reglamentaria. Del mismo modo, los campos de descuento ofrecen la flexibilidad para implementar estrategias de precios dinámicas.

Dado que la API está diseñada para cálculos automáticos de totales y métricas relacionadas, es crucial que los usuarios comprendan y respeten las especificaciones de cada campo. Una correcta implementación asegura que el sistema pueda realizar cálculos precisos en función de las reglas fiscales y los requisitos específicos de la empresa, garantizando así la integridad de los datos y el cumplimiento de todas las obligaciones legales y fiscales.

Formas de Pago

La sección «Formas de Pago» en la API permite una flexibilidad y precisión notables en cómo se abordan los movimientos financieros asociados a una transacción. Estos detalles son cruciales para el control financiero, el flujo de efectivo y la conformidad regulatoria.

Detalles de los Campos en Formas de Pago

1. CodigoFormaPago: N(3) – Este campo es obligatorio y dicta el tipo de la forma de pago, como efectivo, cheque recibido, tarjeta de crédito, movimiento bancario o documento recibido.
2. CodigoMonedaPago: N(2) – Identifica la moneda en la cual se efectuará el pago, proporcionando un marco para las transacciones internacionales.
3. MontoMonedaPago: N(17.2) – Especifica el importe abonado en la moneda del pago.
4. MontoMonedaMovimiento: N(17.2) – Este monto debe coincidir con el total del movimiento y la suma del total de las líneas del movimiento.

Detalles del Documento de Pago

Estos campos son aplicables a casos específicos, generalmente cuando no se trata de una venta en efectivo.

1. CodigoComprobante: N(3) – Este campo opcional establece el tipo de documento que se maneja, como un cheque recibido, tarjeta de crédito, movimiento bancario o documento recibido.
2. Serie, Numero, FechaEmision, FechaVencimiento: Estos campos dan detalles adicionales sobre el documento de pago, añadiendo capas de especificidad y trazabilidad.
3. Concepto: T(50) – Especifica el concepto cuando el documento de pago es del tipo tarjeta recibida.
4. CodigoCaja, CodigoBancoFinanciera, CodigoCtaBancaria: Estos campos son obligatorios en ciertos tipos de formas de pago, proporcionando información adicional que facilita el manejo financiero y la conformidad regulatoria.
5. Titular, NumeroTarjeta, AutorizacionTarjeta, PlanTarjeta: Estos son aplicables especialmente a transacciones que involucran tarjetas de crédito.
6. Resultado: Este campo indicará el estado final del proceso, ya sea OK, Error o Mensaje, ofreciendo una retroalimentación inmediata sobre la transacción.

Es imperativo tener en cuenta el redondeo de la moneda del comprobante. El total grabado en las formas de pago es la suma del total de las líneas, redondeadas según lo indique la moneda. Esto puede obtenerse utilizando el Load o Query de la API de Monedas, lo que garantiza que no haya discrepancias entre los montos.

Método QueryVentas

Permite desplegar una lista de los comprobantes de venta y notas de crédito generados a clientes, para un año, un mes y un rango de fechas específicos.

Filtros

• Mes: T(MM) – Obligatorio.
• Año: T(AAAA) – Obligatorio.
• FechaDesde: AAAA-MM-DD – Debe estar dentro del rango de fechas informado en Mes.
• FechaHasta: AAAA-MM-DD – Debe estar dentro del rango de fechas informado en Mes.
• DocSerie: T(6).
• NumeroDesde: N(10).
• NumeroHasta: N(10).
• ClienteCodigo: T(10) – Enviando valor vacío, se obtienen todos los registros dentro de la página indicada (page).
• ComprobanteCodigo: N(3).
• MonedaCodigo: N(2) – Filtro para selección de comprobantes emitidos en la moneda informada.
• LocalCodigo: N(4).
• Page: N(2) – Obligatorio.

Resultado

• FacturaId
• Fecha
• ComprobanteCodigo
• ComprobanteNombre
• ComprobanteTipo
• ComprobanteTipoNombre
• EsCFE
• TipoDeCFECodigo
• TipoCFENombre
• Serie
• Numero
• ClienteCodigo
• ClienteNombre
• ClienteRazonSocial
• ClientePaisCodigo
• ClientePaisNombre
• ClienteDepartamentoCodigo
• ClienteDepartamentoNombre
• ClienteGrupoCodigo
• ClienteGrupoNombre
• ClienteGiroCodigo
• ClienteGiroNombre
• ClienteZonaCodigo
• ClienteZonaNombre
• ClienteCategoriaCodigo
• ClienteCategoriaNombre
• MonedaCodigo
• MonedaSimbolo
• CotizacionEspecial
• PrecioVentaCodigo
• PrecioVentaNombre
• CondicionCodigo
• CondicionNombre
• VendedorCodigo
• VendedorNombre
• LocalCodigo
• LocalNombre
• CodigoCaja
• CajaNombre
• CentroCostosCodigo
• CentroCostosNombre
• Referencia
• DepositoOrigenCodigo
• DepositoOrigenNombre
• DepositoDestinoCodigo
• DepositoDestinoNombre
• Subtotal
• SubtotalSigno
• IVA
• IVASigno
• Total
• TotalSigno
• Saldo
• SaldoSigno
• Emitido
• Notas
• UsuarioCodigo
• UsuarioNombre
• RegistroFecha
• RegistroHora

Método QuerySaldosPendientes

Este método permite desplegar un listado con el saldo de comprobantes del tipo «venta crédito» y comprobantes del tipo «nota de crédito» emitidos a clientes. Un comprobante tendrá saldo cuando el importe total del mismo no esté completamente cancelado a través de su vinculación a otro comprobante.

Filtros

• ClienteCodigo: T(10) – Especifica el código del cliente. Si se deja vacío, se obtiene la información de todos los clientes.
• Id: Debe enviarse vacío.
• ComprobanteCodigo: N(3).
• FechaDesde: AAAAMMDD.
• FechaHasta: AAAAMMDD.
• Serie: T(6).
• Numero: N(10).
• MonedaCodigo: N(2).
• LocalCodigo: N(4).
• SaldoDesde: N(10) – Corresponde al importe mínimo del saldo a buscar. Puede enviarse con valor cero para incluir todos los saldos.
• SaldoHasta: N(10) – Corresponde al importe máximo del saldo a buscar. Si «SaldoDesde» es cero, se incluirán todos los saldos.
• Emitido: Valores admitidos son S=Si, N=No, o dejarlo vacío.
• Page: N(2) – Obligatorio.

Resultado

• RegistroId
• ComprobanteCodigo
• ComprobanteAbreviacion
• ComprobanteNombre
• ComprobanteTipo
• ComprobanteTipoNombre
• ClienteCodigo
• ClienteNombre
• ClienteRazonSocial
• Fecha
• Serie
• Numero
• MonedaCodigo
• MonedaSimbolo
• MonedaNombre
• CondicionCodigo
• CondicionNombre
• LocalCodigo
• LocalNombre
• Total: Corresponde al valor absoluto del total del comprobante.
• TotalSigno: Refleja el valor del total del comprobante, mostrándose en negativo para Notas de Crédito.
• Saldo: Corresponde al valor absoluto del saldo del comprobante.
• SaldoSigno: Refleja el saldo del comprobante, mostrándose en negativo para Notas de Crédito.
• Emitido
• Notas: Corresponde a las anotaciones del comprobante.

Método Ventas

Este método se ocupa de detallar los comprobantes de venta a clientes, tomando en cuenta aspectos como la fecha y la moneda en la que se efectuó la transacción. Cabe señalar que no incluye comprobantes del tipo «movimiento de stock».

Filtros

• Mes: T(MM) – Este filtro es obligatorio y especifica el mes en el que se desea realizar la consulta.
• Anio: T(AAAA) – Al igual que el mes, el año es un dato obligatorio para realizar la búsqueda.
• Moneda: N(2) – En caso de no proporcionar este filtro, el método contemplará todas las monedas disponibles.

Resultado

La ejecución de este método retorna una serie de parámetros detallados que son:

• FacturaId
• FacturaFecha
• FacturaDia
• FacturaMes
• FacturaAnio
• MonedaCodigo
• MonedaSimbolo
• Cotizacion
• ComprobanteCodigo
• ComprobanteNombre
• ComprobanteTipo
• ComprobanteCFE
• FacturaSigno
• FacturaSerie
• FacturaNumero
• FacturaSerieNumero
• LocalCodigo
• LocalNombre
• DepositoOrigenCodigo
• DepositoOrigenNombre
• DepositoDestinoCodigo
• DepositoDestinoNombre
• CodigoCaja
• CajaNombre
• VendedorCodigo
• VendedorNombre
• CondicionPagoCodigo
• CondicionPagoNombre
• PrecioCodigo
• PrecioNombre
• FacturaReferencia
• CentroCostosCodigo
• CentroCostosNombre
• UsuarioCodigo
• UsuarioNombre
• FacturaRegistroFecha
• FacturaRegistroHora
• ClienteCodigo
• ClienteNombre
• ClienteRazonSocial
• GrupoCodigo
• GrupoNombre
• GiroCodigo
• GiroNombre
• OrigenCodigo
• OrigenNombre
• PaisCodigo
• PaisNombre
• DepartamentoCodigo
• DepartamentoNombre
• ZonaCodigo
• ZonaNombre
• CategoriaCodigo
• CategoriaNombre
• FacturaDescuentos
• FacturaSubtotal
• FacturaIVA
• FacturaTotal
• FacturaSaldo
• FacturaEmitida

Método VentasDetalladas

Este método ofrece un nivel de detalle significativamente mayor en relación con los comprobantes de venta a clientes, incorporando la especificidad de las líneas de artículos. Ha sido desarrollado para ser ejecutado como máximo una vez al día. ZetaSoftware implementa un sistema de monitoreo automatizado para su ejecución y el incumplimiento de este requisito podría generar el bloqueo de acceso.

Filtros

• Mes: T(MM) – Obligatorio. Indica el mes específico para el cual se desea obtener los datos detallados de ventas.
• Anio: T(AAAA) – Obligatorio. Acompaña al mes para delimitar el período de interés.
• Moneda: N(2) – No se utiliza como filtro en este caso. Todos los comprobantes se expresarán en la moneda que se indique aquí.

Resultado

El resultado del método se bifurca en dos secciones primordiales:

Detalles del Encabezado del Comprobante

Los mismos campos que se describen en el método «Ventas» se mantienen aquí, desde FacturaId hasta FacturaEmitida.

Detalles de las Líneas del Comprobante

Este es el conjunto de parámetros que añade una capa adicional de profundidad al análisis de las ventas:

• CategoriaCodigo
• CategoriaNombre
• ArticuloCodigo
• ArticuloNombre
• MarcaCodigo
• MarcaNombre
• CategoriaArticuloCodigo
• CategoriaArticuloNombre
• FamiliaCodigo
• FamiliaNombre
• ProveedorArticuloCodigo
• ProveedorArticuloNombre
• ConceptoCodigo
• ConceptoNombre
• LineaConcepto
• LineaLoteCodigo
• LineaLoteVencimiento
• LineaCantidad
• LineaPrecioDigitado
• LineaPrecio
• LineaDtoPorcentaje1
• LineaDtoPorcentaje2
• LineaDtoPorcentaje3
• IVACodigo
• IVATasa
• IVANombre
• IVATipo
• LineaPendienteRemision
• LineaDescuentos
• LineaSubtotal
• LineaIVA
• LineaTotal

Método VentaDetallada

Este método se sitúa como complemento al método «VentasDetalladas» y permite focalizar en el detalle de una factura de venta específica. Es decir, en el contexto de un análisis más global realizado mediante «VentasDetalladas», el método «VentaDetallada» posibilita una exploración más pormenorizada, centrándose en un único registro a través del campo FacturaId.

Filtros

• FacturaId: N(9) – Este es un dato obligatorio que funciona como identificador único de la factura dentro de la base de datos.

Resultado

El resultado mantiene la misma estructura de datos que el método «VentasDetalladas», abarcando tanto los detalles del encabezado del comprobante como los detalles de las líneas del comprobante.

Método URLPDF

El método URLPDF está diseñado para ofrecer una funcionalidad crítica en la integración de sistemas: la recuperación del enlace URL correspondiente a una factura electrónica emitida en formato PDF. Esta funcionalidad es especialmente útil para desarrolladores o integradores que requieren automatizar el acceso a facturas sin necesidad de utilizar la interfaz gráfica de usuario. La única información requerida para utilizar este método es el identificador único de la factura, conocido como FacturaId.

Parámetros de Entrada

• FacturaId (N(9)): Este parámetro (también llamado RegistroId en otras APIs) es obligatorio y actúa como el identificador único de la factura en cuestión dentro de la base de datos del sistema. Debe corresponder a un comprobante ya emitido. En la grilla de Ventas de ZetaSoftware se puede ver bajo el nombre # Registro.

Resultados Esperados

• URLComprobante: Este es el valor de salida que el método URLPDF retornará. Contiene la dirección URL específica donde se encuentra alojado el PDF de la factura correspondiente al FacturaId ingresado.
• MensajeError: Este es el valor de salida que el método URLPDF retornará cuando ha ocurrido un error, por ejemplo, cuando el comprobante no se encontró, o no fue firmado electrónicamente.

Ventajas y Limitaciones

• Ventajas:
  1. Automatización: Facilita la integración con otros sistemas que requieran acceso programático a facturas.
  2. Eficiencia: Elimina la necesidad de navegación manual para localizar una factura específica.
  3. Seguridad: Al requerir un FacturaId único, se asegura que solo se accederá a la factura que corresponda.
• Limitaciones:
  1. Requiere Conocimiento Previo: Es necesario tener en posesión el FacturaId para hacer uso de este método.
  2. No Genera PDF: Este método no se encarga de la generación del PDF, sólo proporciona el enlace para su acceso.

Consideraciones Técnicas

Es importante que los desarrolladores comprendan que este método es sensible al contexto de autenticación. Por lo tanto, el acceso al recurso estará sujeto a las políticas de seguridad y autenticación definidas en el sistema global.

Metodología Esperada de Uso (método Query)

El método Query viene con ciertas pautas que buscan optimizar el uso de los recursos computacionales y garantizar un funcionamiento eficiente de la base de datos de ZetaSoftware. A continuación, se detallan algunas de las recomendaciones y requisitos:

• Base de Datos Local: Se espera que el desarrollador mantenga una base de datos local para las consultas cotidianas. El objetivo es minimizar el impacto sobre la base de datos principal, actualizando solo las altas y modificaciones necesarias.
• Consultas Acotadas: El método Query no está diseñado para consultas generales sin el uso de parámetros que acoten la búsqueda. Se espera que se utilicen parámetros como FechaDesde y FechaHasta para restringir el rango de la consulta.
• Consulta Inicial Única: Se alienta a realizar una única consulta inicial dejando el filtro ClienteCodigo vacío, para de esta manera obtener todos los registros en una única ejecución.
• Optimización y Limitación de Uso: Las consultas deberán estar optimizadas para evitar su ejecución mediante un «cron» o más de una vez por día. Se espera que estas consultas se realicen solamente cuando la empresa actualiza datos.
• Horarios Comerciales: Se sugiere que el método Query no se ejecute de forma programada durante horarios comerciales, con el objetivo de preservar la eficiencia y rapidez del sistema.

El respeto de estas pautas asegura un uso más eficiente de los recursos, una menor probabilidad de generar cuellos de botella en la base de datos de ZetaSoftware y una mayor confiabilidad en los datos consultados.