Contabilidad y reportes

CRUD de las cuentas contables que componen el plan de cuentas. Cada cuenta tiene un código, un tipo y una posición jerárquica que permite armar el árbol contable. Soporta cargar un plan de cuentas argentino por defecto y consultar el saldo de cada cuenta.

Endpoint base: /api/v1/accounting/accounts

Scope: accounting:read / accounting:write

Campos

Body de POST /api/v1/accounting/accounts/:

Petición

{
  "code": "1.1.01",
  "name": "Caja",
  "account_type": "asset",
  "parent_code": "1.1",
  "level": 3,
  "is_detail": true,
  "description": "Dinero en efectivo disponible"
}

Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "code": "1.1.01",
    "name": "Caja",
    "account_type": "asset",
    "parent_code": "1.1",
    "level": 3,
    "is_detail": true,
    "is_active": true,
    "balance": 0.0
  }
}

CRUD de asientos contables. Cada asiento se compone de al menos dos líneas que imputan cuentas al debe y al haber. Los asientos se crean en estado de borrador y luego pueden asentarse (post) para actualizar los saldos de las cuentas, o revertirse mediante un contrasiento.

Endpoint base: /api/v1/accounting/journal

Scope: accounting:read / accounting:write

Campos

Body de POST /api/v1/accounting/journal/:

Cada elemento del array lines tiene estos campos:

Petición

{
  "date": "2026-05-21",
  "description": "Venta de mercadería en efectivo",
  "lines": [
    {
      "account_code": "1.1.01",
      "account_name": "Caja",
      "debit": 12100.00,
      "credit": 0.00
    },
    {
      "account_code": "4.1.01",
      "account_name": "Ventas",
      "debit": 0.00,
      "credit": 10000.00
    },
    {
      "account_code": "2.1.05",
      "account_name": "IVA Débito Fiscal",
      "debit": 0.00,
      "credit": 2100.00
    }
  ],
  "reference_type": "invoice",
  "reference_id": "66f1a2b3c4d5e6f7a8b9c0d1"
}

Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0e2",
    "date": "2026-05-21",
    "description": "Venta de mercadería en efectivo",
    "lines": [
      { "account_code": "1.1.01", "debit": 12100.00, "credit": 0.00 },
      { "account_code": "4.1.01", "debit": 0.00, "credit": 10000.00 },
      { "account_code": "2.1.05", "debit": 0.00, "credit": 2100.00 }
    ],
    "total_debit": 12100.00,
    "total_credit": 12100.00,
    "status": "draft"
  }
}

Gestión de los libros de IVA compras y ventas, la administración de impuestos y la generación de la declaración jurada de IVA. Los libros se arman por período, pueden cerrarse y reabrirse, y exportarse para su presentación.

Endpoint base: /api/v1/iva

Scope: accounting:read / accounting:write

Este submódulo expone endpoints específicos de su dominio. Estos son los principales:

Reportes contables generados a partir del plan de cuentas y los asientos del libro diario: balance de sumas y saldos, estado de resultados, balance general, libro mayor y flujo de efectivo.

Endpoint base: /api/v1/accounting/reports

Scope: accounting:read

Este submódulo expone endpoints específicos de su dominio, todos de solo lectura:

Importación de extractos bancarios y conciliación de sus movimientos contra los registros contables. Soporta conciliación automática y conciliación manual movimiento por movimiento.

Endpoint base: /api/v1/accounting/bank

Scope: accounting:read / accounting:write

Este submódulo expone endpoints específicos de su dominio. Estos son los principales:

Seguimiento de los vencimientos fiscales: lista de obligaciones, vencimientos próximos y marcado de obligaciones como cumplidas. Permite cargar un set de vencimientos por defecto.

Endpoint base: /api/v1/accounting/fiscal-calendar

Scope: accounting:read / accounting:write

Este submódulo expone endpoints específicos de su dominio. Estos son los principales:

Cierre del ejercicio contable. Permite listar los ejercicios fiscales, calcular el resultado del ejercicio antes de cerrarlo y ejecutar el cierre definitivo del año.

Endpoint base: /api/v1/accounting/fiscal-close

Scope: accounting:read / accounting:write

Este submódulo expone endpoints específicos de su dominio. Estos son los principales:

Administración de regímenes de retención y percepción, cálculo y aplicación de retenciones y percepciones, emisión de certificados y generación de declaraciones juradas del período.

Endpoint base: /api/v1/accounting/retenciones-percepciones

Scope: accounting:read / accounting:write

Este submódulo expone endpoints específicos de su dominio. Estos son los principales:

Datos fiscales del contribuyente por sistema de facturación. Permite cargar y mantener los datos del contribuyente, elegir el sistema de facturación activo, gestionar el certificado y verificar la delegación de servicios y los puntos de venta ante AFIP.

Endpoint base: /api/v1/bill/tax_info

Scope: accounting:read / accounting:write

Este submódulo expone endpoints específicos de su dominio. Estos son los principales:

CRUD de CUITs adicionales para cuentas que facturan bajo más de una identidad fiscal (por ejemplo, varias razones sociales o sucursales con CUIT propio). El CUIT primario de la cuenta nunca se administra acá: sigue viviendo en Datos fiscales y el flujo normal de facturación lo sigue usando exactamente igual si no elegís uno adicional explícitamente.

Este recurso está detrás del widget multi-taxpayer: si la cuenta no lo tiene activo, los seis endpoints responden 403 aunque el token tenga el scope correcto. Sin el widget activo, la facturación sigue funcionando con normalidad usando solo el CUIT primario.

Endpoint base: /api/v1/widgets/multi-taxpayer/taxpayers

Scope: accounting:read / accounting:write

Campos

Body de POST /taxpayers/. Cada campo tiene un alias en español (terminología AFIP), aceptado indistintamente:

Endpoints

Relativos a /api/v1/widgets/multi-taxpayer/taxpayers. No hay operaciones masivas ni DELETE en cascada: borrar un CUIT adicional no toca los comprobantes ya emitidos con él, solo desactiva la posibilidad de emitir nuevos bajo esa identidad.

Petición

POST /api/v1/widgets/multi-taxpayer/taxpayers/
{
  "tax_id": "30712345679",
  "tax_condition": "responsable_inscripto",
  "punto_venta": "2",
  "business_name": "Sucursal Norte S.A.",
  "afip_environment": "production"
}

Respuesta

{
  "success": true,
  "message": "Taxpayer adicional creado exitosamente",
  "data": {
    "success": true,
    "message": "Taxpayer adicional creado exitosamente",
    "taxpayer": {
      "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
      "tax_id": "30712345679",
      "tax_condition": "responsable_inscripto",
      "punto_venta": "2",
      "business_name": "Sucursal Norte S.A.",
      "afip_environment": "production"
    }
  }
}

GET /all/ es la lista pensada para armar un selector: devuelve el primario y los adicionales juntos, cada uno con el flag is_primary:

curl "https://api.yo-facturo.com/api/v1/widgets/multi-taxpayer/taxpayers/all/" \
  -H "X-API-Key: TU_TOKEN"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "tax_id": "30709876543",
        "business_name": "Mi Empresa S.A.",
        "afip_environment": "production",
        "is_primary": true
      },
      {
        "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
        "tax_id": "30712345679",
        "business_name": "Sucursal Norte S.A.",
        "afip_environment": "production",
        "is_primary": false
      }
    ],
    "count": 2
  }
}

CRUD de reglas de impuestos reutilizables (alícuotas de IVA y otros impuestos) para componer el precio de tus productos. Cada regla tiene un país, una categoría y una alícuota, y puede marcarse como la regla por defecto de su combinación país + categoría. Incluye un endpoint para cargar de una vez las alícuotas de IVA habituales de un país.

Endpoint base: /api/v1/bill/tax_info/tax-rules

Scope: accounting:read / accounting:write

Campos

Body de POST /api/v1/bill/tax_info/tax-rules/:

Endpoints

Relativos a /api/v1/bill/tax_info/tax-rules. GET / y GET /by-country/{country}/ devuelven, por defecto, solo las reglas activas (is_active: true); para incluir las desactivadas, pasá ?is_active=false explícitamente a GET /.

Petición

POST /api/v1/bill/tax_info/tax-rules/
{
  "name": "IVA 21%",
  "rate": 21,
  "country": "AR",
  "category": "iva",
  "is_default": true,
  "display_order": 1
}

Respuesta

{
  "success": true,
  "data": {
    "id": "9c1d2e3f-4a5b-4c6d-8e7f-1a2b3c4d5e6f",
    "name": "IVA 21%",
    "rate": 21.0,
    "country": "AR",
    "category": "iva",
    "type": "percentage",
    "description": "",
    "is_default": true,
    "is_active": true,
    "display_order": 1
  }
}

GET /by-country/{country}/ —código de 2 letras— trae solo las reglas activas de ese país:

curl "https://api.yo-facturo.com/api/v1/bill/tax_info/tax-rules/by-country/AR/" \
  -H "X-API-Key: TU_TOKEN"

POST /seed/{country}/ carga las alícuotas de IVA por defecto del país (AR, UY, MX, CO, BR, BO o PE). Es todo o nada por país: si ya existe cualquier regla para ese país, no inserta nada y devuelve seeded: 0 con un mensaje avisando que ya existían — no hay manera de sembrar solo las que faltan.

curl -X POST "https://api.yo-facturo.com/api/v1/bill/tax_info/tax-rules/seed/AR/" \
  -H "X-API-Key: TU_TOKEN"

{
  "success": true,
  "data": {
    "message": "Tax rules already exist for AR",
    "seeded": 0
  }
}

Métricas del negocio: indicadores del panel principal, estadísticas de actividad y métricas de transacciones. Es un recurso de solo lectura.

Endpoint base: /api/v1/stats

Scope: stats:read (solo lectura)

Endpoints principales de Estadísticas: