Características funcionales

Modelo de conexión

En el conjunto de API’s que provee a3innuva Contabilidad se plantean dos posibles mecanismos de conexión, muy relacionados con el modelo de integración que el tercero pueda necesitar.

El primer modelo va enforcado a nivel de entidades, permitiendo que lo que ocurre en un sistema se materialice en el otro. Un ejemplo, que puede ser clarificador, es una facturación que al crear la factura quiere que esté contabilizada al momento. Este modelo es el que permite mayor nivel de integración entre dos sistemas.

El segundo modelo va enfocado a contabilizaciones por periodo. En este caso queremos una integración enfocada a volcar la contabilidad por periodos, y no de forma inmediata.Este segundo modelo se detalla en el punto contabilización por periodos.

La elección de un modelo u otro, o su combinación, dependerá, en gran medida, de vuestras necesidades.

Empresas

Mediante el recurso Companies, se accede a todas las empresas de contabilidad a las que se tiene acceso según las credenciales. Incluye la longitud del plan contable y el estado de la Company.

Tipos de Operaciones e Impuestos

Mediante el recurso Transactions, se accede a todas las operaciones que se pueden incluir en las facturas:
IssuedInvoices: nos devuelve las operaciones de factura expedida.
InputInvoices: nos devuelve las operaciones de factura recibida.

Mediante el código de operación, propiedad longCode, se informará de la afectación fiscal de la base de factura.
Para cada operación se detallan los tipos de impuestos que soporta, desglosando una serie de enumerados en la propiedad validTaxTypes. Por ejemplo, los valores Vat y Withholding nos indican que la operación soporta IVA y retención. Las operaciones están asociadas a la tributación, por lo que obtendremos un juego para Estatal y otro para Canarias.

Mediante el recurso Taxes, se accede a los diferentes impuestos que se soportan en la factura.
La propiedad code es importante para indicar, por poner un ejemplo, si el IVA es de tipo General o Reducido.
Los impuestos se devuelven con su porcentaje, más el porcentaje de recargo si corresponde a IVA, indicando la fecha inicial y final de aplicación. Por tanto, la consulta del IVA General devuelve una entrada diferente por cada porcentaje y periodo de aplicación.

Los tipos de impuestos soportados son los siguientes:

• Vat: IVA
• Withholding: IRPF
• Agrarian: agrario en IVA
• Igic: IGIC
• IgicAgrarian: agrario en IGIC
• IgicRetailer: IGIC minorista

Este recurso permite utilizar un filtro con las siguientes propiedades:

• Type: valores de 0 a 5 que corresponde con los tipos de impuestos soportados.
• Code: corresponde al código de impuesto; por ejemplo, General o Reducido si nos referimos al IVA.
• Date: fecha de validez del impuesto.

Por ejemplo, si filtramos por IVA, type=0, con fecha 01/01/2021, se devolverán dos entradas para los códigos General, Reducido y Superreducido, una que corresponde a cuando se aplica IVA y otra cuando se aplica IVA más recargo.

Plan Contable

El plan contable tiene las siguientes características:

• Longitud fija comprendida entre 6 y 20 posiciones.
• Es el mismo plan para toda la vida de la empresa.
• La cuenta solo dispone de las propiedades código y descripción. Para la entrada de facturas, se requiere del concepto de cliente o proveedor, que se relaciona con la cuenta.
  Al configurar la empresa, en la que se define un plan contable tipo, se utiliza un template, como por ejemplo Plan general de contabilidad, que se replica sobre la empresa que estamos configurando.
  Las cuentas del template no están realmente creadas, de ahí que la propiedad state de la cuenta tenga un valor denominado template. A efectos prácticos, las cuentas de este tipo, como se puede observar al realizar un GET, no tienen CorrelationId, por lo que es necesario crearlas si es necesario su uso en la contabilidad.
  Este mecanismo permite conocer que cuentas realmente están en uso, y es muy habitual que del plan contable de la empresa se utilice un porcentaje muy pequeño de las mismas.

La entrada de facturas está separada del diario, disponiendo de dos recursos que permite generar tanto expedidas como recibidas.
En las facturas no usamos cuentas, sino que usamos las entidades de cliente o proveedor.
Un cliente o proveedor es una entidad que está compuesta de:

• Una entidad cuenta contable, preferiblemente con un código de cuenta correspondiente a los grupos contables de cliente o proveedor.
• Un nombre comercial, que se utilizará como descripción de la cuenta asociada al cliente o proveedor.
• Una entidad persona o dato fiscal; es opcional y permite crear clientes o proveedores genéricos.

En a3innuva Contabilidad solo se permiten una serie de grupos contables para su uso como cliente o proveedor. La relación de grupos contables es la siguiente:

• Clientes: 430, 440, 433, 434, 435
• Proveedores: 400, 410, 173, 523, 174, 524, 403, 404, 405

En la API no existe ningún tipo de validación de los grupos contables, pudiéndose crear clientes o proveedores con cualquier código de cuenta. Nuestra recomendación es utilizar los grupos contables propuestos.

Propiedad State

Esta propiedad nos indica el estado de la entidad. En la mayoría se devolverán los valores Enabled o Deleted. La petición de un GETALL devuelve todas las entidades, pero no incluye las que tienen estado Deleted.

Sin embargo, un GETID sí devuelve información de entidades en estado Deleted.

Las cuentas, clientes o proveedores no se pueden eliminar. Tenemos el concepto de desactivar, que permite que la entidad no pueda seleccionarse en la entrada de asientos o facturas. Desde la API se podrán usar sin problemas entidades con estado Disabled.

Desde la API no es posible desactivar una entidad.

En cuentas existe un tercer estado, denominado Template, que nos indica que la entidad no está creada. Por tanto, las cuentas con dicho estado se deberán crear antes de utilizarse.

Concepto de persona

La entidad persona recoge los diferentes terceros relacionados con la empresa. En realidad, son datos fiscales que son utilizados en los diferentes clientes, proveedores y perceptores de cada empresa. Principalmente está enfocada a la fiscalidad; cumplimentación de los modelos 180, 190, 193, 347 y 349.

Es posible tener varios clientes o proveedores relacionados con la misma persona; ejemplo de un cliente con diferentes delegaciones, disponiendo cada cliente de la misma persona, pero diferente cuenta y con nombre comercial distinto.

La propiedad documentType identifica el tipo de documento teniendo los siguientes valores:

• Auto: asigna automáticamente el tipo de documento a partir de ciertos patrones que permiten reconocer si es NIF/CIF/NIE o NIF intracomunitario. Si no corresponde con los anteriormente citados, se asignará como Otro documento probatorio.
• NIF/CIF/NIE
• Intracommunity VAT ID: NIF intracomunitario. Es obligatorio informar el código de país en el documento. La validación comprueba código de país más patrón de longitud.
• Official residence document: documento oficial de residencia.
• Passport: pasaporte.
• Official residence certificate: certificado de residencia fiscal.
• Other supporting document: otro documento probatorio.

Asientos

La entidad asiento se compone de una cabecera y de un detalle de apuntes. A nivel de cabecera contiene las siguientes propiedades:

• approvalState: el asiento puede tener dos estados, con los que pueden filtrar en la consulta. Los valores son borrador, valor Draft, o como definitivo, valor Completed.
• journalType: tipo de asiento que puede corresponder con los siguientes valores:
  Regular : asiento normal.
  Output: asiento automático generado por una factura expedida.
  Input: asiento automático generado por una factura recibida.
  Regularization, Close y Open: corresponden a los asientos automáticos de cierre.
  Charge: asiento automático generado por un cobro o devolución.
  Payment: asiento automático generado por un pago.
  maturityCorrelationId: mediante este correlationId asociamos el asiento con un vencimiento. Admitido para asientos de tipo Charge y Payment cuando el vencimiento no genera el asiento.
  

Aunque la mayoría son tipos de asientos que se generan automáticamente dentro de la contabilidad, también se pueden utilizar desde la API. Por tanto, es posible generar asiento de cierre, o asientos de cobro o pago.

En el detalle se desglosan los diferentes apuntes que conforman el asiento. Hay que destacar que no se informa el código de cuenta, sino que es obligatorio informar su correlationId (propiedad accountCorrelationId).

Facturas expedidas y recibidas

Disponemos de una entidad distinta para factura expedida y otra para factura recibida; son entidades prácticamente iguales, pero tienen alguna diferencia provocada por el tratamiento del IVA deducible. Estas entidades se estructuran en una cabecera y en un detalle de bases.

A nivel de cabecera de factura disponemos de las siguientes propiedades:

• approvalState: la factura puede tener dos estados, con los que se puede filtran en la consulta. Los valores son borrador, valor Draft, o como definitivo, valor Completed.
• customerCorrelationId, supplierCorrelationId, vatNumberCorrelationId: es obligatorio informar el correlationId de cliente o proveedor, siendo opcional el correlationId de persona.
  La afectación fiscal, a efectos por ejemplo de un 190 o 347, lo determina la persona asociada a la factura. Si tenemos varias facturas con un mismo cliente, y obviamente con persona asociada que también hemos trasladado a las facturas, si se cambia la persona del cliente no se cambia la persona en las facturas que estén asociadas al cliente. En la contabilidad se dispone de utilidades para normalizar esta situación.
• createJournal: indica si queremos crear o no el asiento correspondiente a la factura.

A nivel de detalle de base, comentar algunas de sus propiedades:

• transaction: corresponde con la propiedad longcode de la entidad transactions. Por ejemplo, OP_INT nos indica que es una operación interior.
• tax: corresponde con la propiedad code de la entidad taxes. Por ejemplo, en IVA podemos usar General, Reducido, Superreducido o Exento.
• withHolding: tipo de retención que corresponde con el code de la entidad taxes. El valor SIN_RET indica que la base no tiene retención, y el valor CIN_ARR, por poner un ejemplo, nos indica retención por arrendamiento de local.
  Las bases de factura no requieren de ningún porcentaje, simplemente asignamos el tipo de impuesto, la cuota y/o recargo, más la retención. Al editar la factura, veremos porcentajes que están relacionados con el tipo de impuesto más la fecha de factura o fecha de operación.
• counterpartCorrelationId: correlationId de la cuenta de contrapartida. Si no se informa, se tomará la cuenta configurada a nivel de empresa.

A nivel de bases de factura recibida, comentar las siguientes propiedades:

• applyProrrata: indica si queremos o no calcular el IVA deducible a partir de la prorrata configurada para la empresa de la factura.
• taxAmountDeductible, taxSurchargeAmountDeductible: cuota de IVA o IGIC deducible, y recargo deducible, respectivamente. Estas propiedades se informarán si queremos indicar la parte deducible sin tener en cuenta la prorrata configurada a nivel de empresa.
  Reseñar que la cuota deducible se contabilizará con la cuenta de IVA o IGIC soportado, y que la diferencia entre la cuota y la cuota deducible, que corresponde con la parte no deducible, se contabilizará como gasto.

Cartera de cobros y pagos

Disponemos de una entidad distinta para cobros, relacionada con la factura expedida, y otra para pagos, relacionada con la factura recibida; son entidades muy parecidas, pero con alguna diferencia.

Atención

Cualquier cobro o pago debe estar relacionado con una factura.

Detallar las siguientes propiedades que son extensibles a cobros y pagos:

• issuedInvoiceCorrelationId o inputInvoiceCorrelationId: correlationId obligatorio que indica con que factura expedida o recibida está relacionado el vencimiento.
• situation: los estados en función del tipo de vencimiento:
  Cobros
  Pending: pendiente.
  Charged o Returned: cobrado o devuelto.
  Pagos Pending: pendiente.
  Paid: pagado.
  createJournal: indica si queremos crear o no el asiento correspondiente al vencimiento.
  Solo los estados Charged, Returned o Paid pueden generar o asociar un asiento contable.

Si la generación es automática, es obligatorio informar el correlationId de la cuenta de banco.

Si optamos por crear un asiento de cartera, y no por su generación automática, tendremos que:

• Crear el asiento indicando el tipo Charge o Payment e indicando la relación con el vencimiento mediante la propiedad maturityCorrelationId.
• Asignar el valor false a la propiedad createJournal del vencimiento.

Contabilización por periodos (Importia)

Bajo el concepto de API Importia, se expone el recurso integrationFiles que está enfocado a la subida de ficheros de tipo JSON sobre la plataforma de a3innuva Contabilidad. Cada fichero JSON admite un volumen de entidades considerable, disponiendo de cuatro tipos distintos:

• Plan contable
• Asientos
• Facturas expedidas
• Facturas recibidas

La estructura y contenido de los ficheros JSON está detallada en el siguiente repositorio de GitHub

La API Importia, además de la subida de ficheros, dispone de los siguientes servicios:

• validate: valida el contenido del fichero devolviendo un JSON con los errores detectados. Es recomendable utilizar este servicio durante el periodo de desarrollo.
• undo: permite solicitar la eliminación de las entidades creadas por un fichero. Cada fichero subido tendrá un correlationId, que obviamente deberás conocer, por si necesitas realizar esta acción de undo.
  

Atención

No se puede aplicar un deshacer sobre un fichero de tipo Plan contable, y solo funciona sobre ficheros procesados.

• summary: sobre ficheros procesados, permite conocer las entidades integradas, además de los posibles errores de integración que se hayan producido.
  Te puedes suscribir a las notificaciones de cambio de los ficheros.