Tarifas e Impuestos Bills de compra

Docs Facturas TaxCodes

Estructura del campo tarifas

Las facturas de compra de la API externa incluyen un array tarifas con el desglose de impuestos. Cada tarifa se convierte en una linea separada del Bill en QuickBooks.

{
  "numero": "FC-001-2025",
  "fecha": "2025-01-20",
  "proveedor": "Distribuidora ABC S.A.",
  "descripcion": "Compra de suministros de oficina",
  "subtotal": 30.46,
  "total": 34.42,
  "tarifas": [
    {
      "id": 724,
      "nombre_tarifa": "Tarifa general 13%",
      "tasa": "13.00",
      "monto": "3.96"
    }
  ]
}

Campos de cada tarifa

Campo	Tipo	Descripcion	Ejemplo
`id`	number	Identificador unico en API externa	724
`nombre_tarifa`	string	Nombre descriptivo del impuesto	"Tarifa general 13%"
`tasa`	string	Porcentaje del impuesto	"13.00"
`monto`	string	Valor calculado (positivo o negativo)	"3.96" o "-2000.00"

Montos negativos: Las retenciones tienen monto negativo porque se descuentan del total a pagar al proveedor.

Tipos de impuestos

Tipo	Nombres reconocidos	Cuenta QB	Codigo
IVA	"Tarifa general 13%", "IVA", "impuesto sobre las ventas"	IVA por Pagar	2110
RETENCION IR	"Retencion IR 2%", "retencion", "renta"	Retencion Impuesto sobre la Renta	2120
RETENCION IVA	"retencion_iva", "retencion_otros"	Retenciones por Pagar	2125
TIMBRES	"timbre", "timbres"	Timbres Fiscales	2130
CONTRIBUCION	"contribucion", "contribución"	Contribuciones por Pagar	2140
GENERICO	Tipos no especificos	Impuestos por Pagar	2100

Todas las cuentas de impuestos son tipo Other Current Liability en QuickBooks.

Conversion a QuickBooks Bill

El sistema crea multiples lineas en el Bill: una linea principal de gasto (sugerida por IA) y una linea por cada tarifa.

Linea principal (gasto)

{
  Amount: 100000,   // subtotal sin impuestos
  DetailType: "AccountBasedExpenseLineDetail",
  AccountBasedExpenseLineDetail: {
    AccountRef: { value: "601" }  // Cuenta sugerida por IA
  },
  Description: "Compra de suministros de oficina"
}

Linea de impuesto

{
  Amount: 13000,    // monto del IVA
  DetailType: "AccountBasedExpenseLineDetail",
  AccountBasedExpenseLineDetail: {
    AccountRef: { value: "2110" }  // IVA por Pagar
  },
  Description: "IVA - 13%"
}

Asignacion de cuentas

Paso	Accion
1	Busca cuenta exacta en el plan de cuentas de QB
2	Busca cuenta similar si no existe exacta
3	Crea nueva cuenta si es necesario
4	Usa cuenta generica como fallback final

CRC vs USD: En CRC, las tarifas se crean como lineas separadas. En USD, los impuestos se incluyen en el monto principal para evitar conflictos de moneda en QB.

Ejemplo completo

Factura de entrada

{
  "numero": "FC-001-2025",
  "proveedor": "Distribuidora ABC S.A.",
  "descripcion": "Compra de suministros de oficina",
  "subtotal": 100000,
  "total": 111000,
  "tarifas": [
    { "nombre_tarifa": "Tarifa general 13%", "tasa": "13.00", "monto": "13000" },
    { "nombre_tarifa": "Retencion IR 2%", "tasa": "2.00", "monto": "-2000" }
  ]
}

Bill generado en QuickBooks

{
  VendorRef: { value: "789" },
  TxnDate: "2025-01-20",
  DocNumber: "FC-001-2025",
  Line: [
    {
      Amount: 100000,
      DetailType: "AccountBasedExpenseLineDetail",
      AccountBasedExpenseLineDetail: { AccountRef: { value: "601" } },
      Description: "Compra de suministros de oficina"
    },
    {
      Amount: 13000,
      DetailType: "AccountBasedExpenseLineDetail",
      AccountBasedExpenseLineDetail: { AccountRef: { value: "2110" } },
      Description: "IVA - 13%"
    },
    {
      Amount: -2000,
      DetailType: "AccountBasedExpenseLineDetail",
      AccountBasedExpenseLineDetail: { AccountRef: { value: "2120" } },
      Description: "Retencion - 2%"
    }
  ]
}

Contabilizacion resultante

Asiento contable — FC-001-2025

Cuenta Debe Haber

Gastos de Oficina

₡100,000

IVA por Pagar

₡13,000

Retencion IR

₡2,000

Cuentas por Pagar

₡111,000

La Retencion IR va al haber porque reduce el total a pagar al proveedor (monto negativo en la tarifa).

Configuracion

Agregar nuevos tipos de impuestos

// En el metodo determinarCuentaImpuesto()

if (tipoLower.includes('nuevo_impuesto')) {
  nombreCuenta = 'Nuevo Impuesto por Pagar';
  codigoCuenta = '2150';
  tipoCuenta = 'Other Current Liability';
}

Personalizar reglas de IA

// En el array reglasAsignacion de IAAsignacionCuentas

{
  palabrasClave: ['nueva', 'categoria'],
  cuenta: 'Nueva Cuenta de Gastos',
  codigo: '6950'
}

Troubleshooting

Problema	Causa	Solucion
Tarifa no reconocida	Nombre no esta en lista de tipos	Agregar a `determinarCuentaImpuesto()`
Monto de tarifa como string	API externa envia strings	El sistema convierte a number automaticamente
Cuenta de impuesto no existe	Primera vez del tipo	El sistema crea la cuenta automaticamente en QB
Impuestos no aparecen en USD	Se incluyen en monto principal	Comportamiento esperado para evitar conflictos de moneda