Impuestos y TaxCodes

Docs Dashboard Swagger

TaxCodes en QuickBooks

Los TaxCodes son identificadores que QuickBooks usa para determinar que impuestos aplicar a cada linea de factura. En el sistema de Costa Rica se usan estos codigos:

13%

IVA General

TaxCode: 18

13%

IVA Servicios

TaxCode: 17

Exento / Exportacion

TaxCode: 12

TaxCode	Tasa	Tipo	Uso
`18`	13%	IVA General	Productos y bienes gravados
`17`	13%	IVA Servicios	Servicios profesionales
`12`	0%	Exento	Productos exentos, exportaciones

GlobalTaxCalculation: Siempre usar "TaxExcluded" en facturas con impuestos. Esto indica que los montos de linea no incluyen el impuesto — QB lo calcula aparte.

Tasas de impuesto — Costa Rica

13%

IVA Estandar

Bienes y servicios

IVA Reducida

Canasta basica

IVA Minima

Salud, educacion

Tasa	Nombre	TaxCode QB	Aplicacion
13%	IVA General	`18`	Bienes y servicios generales
13%	IVA Servicios	`17`	Servicios profesionales y tecnicos
4%	IVA Reducida	—	Canasta basica tributaria
2%	IVA Minima	—	Servicios de salud y educacion
1%	IVA Especial	—	Bienes de primera necesidad
0%	Exento	`12`	Exportaciones, exoneraciones

Uso en facturas de venta (Invoices)

Cada linea de factura incluye un TaxCodeRef que determina el impuesto aplicado.

Estructura de linea

{
  Amount: 100000,
  DetailType: "SalesItemLineDetail",
  SalesItemLineDetail: {
    ItemRef: { value: "1", name: "Services" },
    Qty: 1,
    UnitPrice: 100000,
    TaxCodeRef: { value: "18" }     // ← 18 = IVA 13%
  }
}

Factura completa con impuesto

{
  CustomerRef: { value: "42" },
  DocNumber: "FE-001-2025",           // max 21 chars
  TxnDate: "2025-02-15",
  CurrencyRef: { value: "CRC" },
  GlobalTaxCalculation: "TaxExcluded", // REQUERIDO con impuestos
  Line: [
    {
      Amount: 100000,
      DetailType: "SalesItemLineDetail",
      SalesItemLineDetail: {
        ItemRef: { value: "1", name: "Services" },
        Qty: 1,
        UnitPrice: 100000,
        TaxCodeRef: { value: "18" }   // IVA 13%
      }
    },
    {
      Amount: 50000,
      DetailType: "SalesItemLineDetail",
      SalesItemLineDetail: {
        ItemRef: { value: "1", name: "Services" },
        Qty: 1,
        UnitPrice: 50000,
        TaxCodeRef: { value: "12" }   // Exento
      }
    }
  ]
}
// Total = 100,000 + 13,000 (IVA) + 50,000 = 163,000

Mapeo automatico: El sistema determina el TaxCode segun la tasa: 13% → 18, 0% → 12. La funcion determinarTaxCodeOptimo(tasa) maneja la logica.

Tarifas en facturas de compra (Bills)

Las facturas de compra traen un campo tarifas con el desglose detallado de impuestos. Cada tarifa se mapea a una linea separada en el Bill.

Formato de la API externa

{
  "numero": "FC-001-2025",
  "proveedor": "Distribuidora ABC S.A.",
  "subtotal": 100000,
  "total": 111000,
  "tarifas": [
    {
      "id": 724,
      "nombre_tarifa": "Tarifa general 13%",
      "tasa": "13.00",
      "monto": "13000.00"
    },
    {
      "id": 825,
      "nombre_tarifa": "Retencion IR 2%",
      "tasa": "2.00",
      "monto": "-2000.00"      // negativo = retencion
    }
  ]
}

Tipos de impuestos reconocidos

Tipo	Palabras clave	Cuenta QB	Codigo
IVA	Tarifa general 13%, IVA, impuesto sobre las ventas	IVA por Pagar	2110
RET IR	Retencion IR 2%, retencion, renta	Retencion Impuesto sobre la Renta	2120
RET IVA	retencion_iva, retencion_otros	Retenciones por Pagar	2125
Timbres	timbre, timbres	Timbres Fiscales	2130
Contrib.	contribucion, contribucion	Contribuciones por Pagar	2140
Otros	Cualquier otro	Impuestos por Pagar	2100

Ejemplo de contabilizacion

Una factura de compra con IVA y retencion genera multiples lineas en el Bill de QuickBooks.

Bill generado

Line: [
  {
    Amount: 100000,                    // Gasto principal
    DetailType: "AccountBasedExpenseLineDetail",
    AccountBasedExpenseLineDetail: {
      AccountRef: { value: "601" }     // Gastos de Oficina (IA)
    },
    Description: "Compra de suministros"
  },
  {
    Amount: 13000,                     // IVA
    DetailType: "AccountBasedExpenseLineDetail",
    AccountBasedExpenseLineDetail: {
      AccountRef: { value: "2110" }    // IVA por Pagar
    },
    Description: "IVA - 13%"
  },
  {
    Amount: -2000,                     // Retencion (negativa)
    DetailType: "AccountBasedExpenseLineDetail",
    AccountBasedExpenseLineDetail: {
      AccountRef: { value: "2120" }    // Retencion IR
    },
    Description: "Retencion - 2%"
  }
]

Asiento contable resultante

Cuenta	Debe	Haber
Gastos de Oficina	₡100,000
IVA por Pagar	₡13,000
Retencion IR		₡2,000
Cuentas por Pagar		₡111,000

API y CLI

Endpoints REST

Metodo	Endpoint	Descripcion
GET	`/taxrates`	Obtener tasas de impuestos configuradas en QB
GET	`/taxcodes`	Obtener codigos de impuestos disponibles

Obtener TaxCodes via API

curl -X GET "https://api.admindual.com/taxcodes?org=DUAL" \
  -H "x-api-key: YOUR_API_KEY"

Logica de determinacion

// src/utils/taxUtils.js

function determinarTaxCodeOptimo(taxRate) {
  if (!taxRate || taxRate <= 0)  return '12';   // Exento
  if (taxRate === 13)             return '18';   // IVA General
  return '18';                                    // Default IVA
}

Asignacion de cuentas: En facturas de compra, la IA analiza la descripcion y proveedor para sugerir la cuenta contable del gasto base. Las cuentas de impuestos se asignan automaticamente por tipo.

Configuracion en QuickBooks

Requisitos previos

1. Settings → Tax → Configurar tasas de impuestos
2. Activar codigos necesarios (18, 17, 12)
3. Verificar que las cuentas contables existan:
   - 2110: IVA por Pagar
   - 2120: Retencion IR
   - 2125: Retenciones por Pagar

Mejores practicas

Practica	Detalle
Cachear TaxCodes	Evitar llamadas repetitivas al API de QB
Validar tasas	Asegurar que sean numericas antes de mapear
Fallback	Si QB no responde, usar codigos por defecto (18, 12)
Rate limiting	Respetar limites: delay entre llamadas al endpoint