“Homologar” un sistema de facturación es la forma en que muchos contadores y dueños de negocio en Bolivia se refieren al proceso completo que deja a una empresa habilitada para emitir facturas electrónicas válidas ante Impuestos Nacionales (el SIN, a través de su plataforma SIAT). No es un trámite único: es una secuencia de pasos técnicos, y cuando usas una API como la de Xmart, la mayoría de esos pasos se automatizan solos.
Acá te mostramos exactamente qué pasa en cada etapa, con los endpoints reales que se usan.
Paso 1: registrar la empresa
Todo arranca con el NIT y la razón social de tu empresa, los mismos datos con los que el SIN te identifica:
POST /companies{
"nit": "1234567890",
"business_name": "XMART SRL",
"activity_codes": ["620100", "461000"]
}El NIT no se puede cambiar después de este paso, así que conviene revisarlo antes de enviarlo. Apenas se crea la empresa, el sistema deja lista automáticamente tu Casa Matriz: la sucursal principal (identificada siempre con el código 0) y su punto de venta principal. No necesitas crearlos a mano para empezar a operar.
Si algo falla en ese armado automático, existe un endpoint de respaldo, seguro de repetir las veces que haga falta:
POST /companies/{company_uid}/bootstrapPaso 2: elegir la modalidad de facturación
Bolivia reconoce distintas modalidades de facturación (electrónica, computarizada, entre otras). La modalidad se define a nivel de empresa y todos sus puntos de venta la heredan automáticamente; no la configuras punto de venta por punto de venta.
Por defecto, una empresa nueva queda en modalidad electronic. Si tu operación necesita otra modalidad, se ajusta actualizando la empresa:
PUT /companies/{company_uid}{ "modality": "computarized" }Paso 3: sucursales y puntos de venta adicionales
Si tu negocio factura desde más de un local, cada uno se registra como una sucursal con su propio código:
POST /branchesY cada caja o terminal desde la que emites facturas dentro de esa sucursal se registra como un punto de venta:
POST /posNo necesitas indicar la modalidad al crear el punto de venta: la hereda sola de la empresa.
Paso 4: obtener el CUIS
Acá empieza la parte que técnicamente es “la homologación” frente al SIN: cada punto de venta necesita dos credenciales de seguridad antes de poder emitir. La primera es el CUIS (Código Único de Inicio de Sistema), que funciona como la llave que habilita a esa caja a arrancar.
POST /cuis?pos_uid={pos_uid}En condiciones normales no necesitas pedirlo a mano: un proceso automático se encarga de solicitarlo la primera vez que hace falta. El endpoint existe para forzar una renovación puntual si la necesitas.
Paso 5: obtener el CUFD
La segunda credencial es el CUFD (Código Único de Facturación Diaria), que como su nombre lo dice, se renueva todos los días y es la que efectivamente habilita a facturar durante esa jornada.
POST /cufd?pos_uid={pos_uid}Un detalle importante: el CUFD depende de que exista antes un CUIS activo. Si intentas pedir un CUFD sin CUIS vigente, la API te va a devolver:
{
"title": "renew CUIS before CUFD",
"status": 422,
"code": "INV_CREDENTIAL_EXPIRED"
}Igual que el CUIS, el CUFD se renueva solo por detrás; no necesitas correr este endpoint todos los días a mano.
Paso 6: revisar los catálogos oficiales
Antes de emitir tu primera factura, es buena idea revisar los catálogos del SIN que vas a necesitar: formas de pago, monedas, unidades de medida, actividades económicas, tipos de documento de identidad, entre otros. Todos están disponibles con:
GET /catalogs?catalog_type=payment_methodsEstos catálogos no te los inventas: los define Impuestos, y tu sistema los sincroniza automáticamente para que siempre tengas los códigos vigentes.
Paso 7: emitir tu primera factura
Con la empresa registrada, la modalidad definida y las credenciales del punto de venta activas, ya puedes emitir tu primera factura:
POST /invoices{
"branch_uid": "...",
"pos_uid": "...",
"payment_method_code": 1,
"user": "cajero1",
"invoice_type": "factura",
"items": [{ "product_code": "...", "quantity": 1, "unit_price": 100 }]
}Por defecto la factura se registra al instante y se despacha al SIN en segundo plano (mode=async), así que tu sistema no se queda esperando la respuesta de Impuestos. Si necesitas confirmar en el momento si quedó validada, puedes forzar el modo síncrono con mode=sync.
Errores comunes durante el proceso
Al automatizar el registro y las credenciales, la mayoría de los problemas que puedes encontrar tienen un código de error claro en la respuesta de la API, en vez de un mensaje genérico:
INV_VALIDATION_FAILED(422): algún dato obligatorio falta o no cumple el formato esperado, por ejemplo un NIT mal escrito al crear la empresa.INV_CREDENTIAL_EXPIRED(422): intentaste renovar el CUFD sin tener un CUIS activo para ese punto de venta.INV_SIN_UNAVAILABLE(503): el servicio del SIN no respondió en ese momento. No es un error de tu integración: puedes reintentar, o revisar si conviene abrir una ventana de contingencia si el problema persiste.INV_TENANT_SUSPENDED(423): tu cuenta quedó suspendida y no puede registrar nuevas empresas hasta regularizar la situación.
Tener estos códigos identificados de antemano ayuda a que tu equipo de soporte o tu contador sepan de inmediato si el problema es un dato mal cargado de tu lado o una caída temporal del SIN.
Qué significa “estar homologado” en la práctica
Al final del día, estar homologado significa tener:
- Una empresa registrada con NIT verificado.
- Al menos un punto de venta con su CUIS y su CUFD vigentes.
- La capacidad de emitir una factura y recibir confirmación del SIN sobre esa factura.
Cuando usas la API de Xmart, los pasos 1 a 3 son casi automáticos, y los pasos 4 y 5 se mantienen solos una vez configurados. Lo único que realmente tienes que decidir de tu lado es la modalidad de facturación y la estructura de sucursales y puntos de venta que refleje tu negocio real.
Si quieres ver el detalle completo de la API, revisa nuestra página de facturación electrónica o consulta directamente los planes disponibles.
