Contabilidad: cómo funciona

Contabilidad conecta tu espacio con tu software contable (Alegra o Siigo) para que tus ventas lleguen solas: facturas, pagos y clientes. También lee de él el catálogo y el stock, y te dice qué quedó sin confirmar. Si tu programa no tiene API (World Office clásico, Helisa…), te arma un archivo CSV listo para importar.

Por API lo usas para facturar desde tu propia tienda o tu sistema de pedidos, conciliar al cierre del mes o leer el inventario sin entrar a tu programa contable.

También puedes verlo desde la consola: en el Estudio de un espacio con el módulo activo, el panel Contabilidad enseña el conector, la conciliación y la cola, con un botón para procesarla y otro para reintentar lo que falló.

Antes de empezar

• El espacio tiene que tener el módulo Contabilidad: contabilidad sale en sus módulos en GET /api/companies. Si no, cada ruta responde 403 módulo no habilitado para este espacio.
• Leer (las rutas GET) vale con cualquier clave. Todo lo demás pide una clave escribe, también probar la conexión, leer el catálogo o procesar la cola.
• Las rutas cuelgan de /api/mod/contabilidad/{espacio}/, con la misma clave y los mismos límites que el resto de la API.
• No gasta créditos: ninguna ruta del módulo descuenta de tu bolsa.

Conecta tu software

1. Configura el conector con proveedor y sus credenciales.
2. Prueba la conexión: ok: true quiere decir que las credenciales abren tu software.
3. Mira qué puede hacer: si lee catálogo y stock, si recibe facturas, o si solo exporta archivos.

worldoffice_cloud, quickbooks y xero se pueden elegir, pero todavía no conectan.

Las credenciales entran y no vuelven a salir. Ni la configuración ni ninguna otra ruta devuelve sus valores: solo sus nombres, en credenciales_set. Para cambiar una, manda la misma clave con el valor nuevo; una clave con valor vacío no borra la que había.

PATCH …/config
{ "proveedor": "alegra",
  "credenciales": { "email": "[email protected]", "api_token": "TU_TOKEN_DE_ALEGRA" } }

→ { "proveedor": "alegra", "credenciales_set": ["api_token", "email"], … }

Facturas, pagos y clientes

Nada se manda a tu software en el momento: todo pasa por una cola de envíos. Así una venta nunca se queda colgada porque tu programa contable tarde o esté caído.

1. Encola una factura, un pago o un cliente: responde 202 con su outbox_id en pending.
2. Procesa la cola: manda a tu software lo que toca y responde con cuántas entradas salieron bien.
3. Consulta el estado de cada envío: en done, resultado_json trae su id en tu software y, en las facturas, su número y su CUFE si tu software los da.
4. Si algo queda en dead, corrige lo que dice motivo_error y reinténtalo.

referencia_interna es tu id de la venta, del pago o del cliente, y es lo que impide duplicar: encolar dos veces la misma no crea otra entrada, te devuelve la que ya había con idempotent_replay: true. La clave va por tipo: la factura y el pago de una misma venta pueden llevar la misma referencia.

Si el espacio tiene además el módulo Facturación con la emisión contable encendida, cada orden pagada entra sola en la cola como factura, con el id de la orden como referencia_interna.

Estados de un envío

pending → processing → done
                     ↘ failed → (siguiente procesado) → processing
                     ↘ dead                               (agotó sus intentos)
failed | dead → (reintentar) → pending

• Un fallo no se pierde: queda en failed y vuelve a intentarse en un procesado posterior, cada vez con más espera (next_attempt_at).
• Tras max_intentos fallos queda en dead y ya no se reintenta sola. Reintentar le da un intento más; no reinicia la cuenta.
• Si encolas antes de conectar tu software, las entradas esperan en failed sin gastar intentos.

Conciliación

La conciliación cuadra un periodo: cuántas facturas y pagos hay en cada estado, cuánto suman los que tu software confirmó y cuáles quedaron sin confirmar. deriva: true quiere decir que hay algo pendiente o parado que mirar; la lista pendientes dice qué.

Programas sin API: el archivo

Con csv_export, procesar la cola no llama a nadie: deja cada entrada en done, lista para el archivo. Después exporta facturas, pagos o clientes y recibes el CSV dentro de un JSON (filename y contenido).

• plantilla_export elige las columnas de las facturas: generico, worldoffice o helisa.
• Exportar no marca nada como exportado: cada vez trae todo lo de ese tipo. Lleva tú la cuenta de qué importaste.

Catálogo y stock

• Lee el catálogo o el stock de tu software en un formato común (sku, nombre, precio, cantidad…). Cada lectura queda en el historial.
• Para una tarea programada, sincroniza solo si toca: no llama a tu software hasta que pasen cadencia_sync_horas.
• Con write_back_stock autorizado, puedes descontar cada venta del inventario de tu software (hoy, con Alegra).

Rutas