¿Cómo facturo con la API de Xubio?

Todos los llamados van a https://xubio.com/API/1.1/ y necesitan el token que obtuviste con tus credenciales. El token dura una hora.

Qué necesitás antes de empezar

Elegí cómo se numeran tus comprobantes

Tu punto de venta puede numerar de dos formas, y de eso depende con qué endpoint creás la factura.

El punto de venta va en cada factura que emitís, pero no hace falta que lo consultes cada vez: lo buscás una sola vez al armar la integración y te guardás su id.

GET /API/1.1/puntoVentaBean

curl "https://xubio.com/API/1.1/puntoVentaBean" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

[
  {
    "puntoVentaId": 4821,
    "nombre": "Ventas online",
    "codigo": "0003",
    "puntoVenta": "00003",
    "modoNumeracion": "automatico",
    "circuitoContable": { "ID": -2, "nombre": "default", "codigo": "DEFAULT" },
    "activo": 1,
    "factElectronicaConXB": 1
  }
]

modoNumeracion es el dato que define con qué endpoint vas a crear la factura, y factElectronicaConXB te dice si ese punto de venta emite factura electrónica. Los dos indicadores vienen como 1 o 0, no como true o false.

Paso 1Indicá el cliente

La factura lleva el cliente en el campo cliente, que lo referencia por id, código o nombre. Tiene que existir antes: si todavía no está en tu cuenta, creálo.

POST /API/1.1/clienteBean

Son tres campos obligatorios: nombre, identificacionTributaria y categoriaFiscal.

Ver documentación de clientes

Paso 2Indicá los productos

Cada item de la factura lleva un producto dentro de transaccionProductoItems. Tiene que existir antes: si todavía no está en tu cuenta, creálo.

POST /API/1.1/ProductoVentaBean

Son cuatro campos obligatorios: nombre, codigo, cuentaContable y tasaIva.

Ver documentación de productos

Paso 3Creá la factura

El ejemplo usa el endpoint de punto de venta automático.

POST /API/1.1/facturar

El cuerpo del pedido reproduce las mismas partes que ves en la pantalla de factura de venta: el encabezado, los items, las percepciones y los instrumentos de cobro.

Ejemplo

{
  "cliente": { "nombre": "Distribuidora del Norte SA" },
  "puntoVenta": { "codigo": "0003" },
  "tipo": 1,
  "fecha": "2026-09-25",
  "condicionDePago": 2,
  "transaccionProductoItems": [
    {
      "producto": { "codigo": "SERVICIO_DE_MANTENIMIENTO_MENSUAL" },
      "cantidad": 2,
      "precio": 15000
    }
  ],
  "transaccionCobranzaItems": [
    {
      "cuentaId": -13,
      "moneda": { "codigo": "PESOS_ARGENTINOS" },
      "cotizacionMonTransaccion": 1,
      "importeMonTransaccion": 36300
    }
  ]
}

Si la condición de pago es 1 (cuenta corriente), sacá transaccionCobranzaItems y agregá fechaVto.

El encabezado

Son los datos de la cabecera de la factura: a quién le facturás, con qué punto de venta, cuándo y cómo se cobra. En el JSON van en el nivel principal, sin anidar.

Los items

Es la grilla de productos: qué vendés, cuánto y a qué precio. Cada fila de la pantalla es un objeto dentro de transaccionProductoItems, y va al menos uno.

El importe, el IVA y el total no se mandan: los calcula Xubio a partir de la cantidad, el precio y la alícuota configurada en el producto.

El depósito no se define por fila: el item toma siempre el deposito del encabezado. Si mandás uno distinto adentro del item, la respuesta te lo devuelve pero el comprobante queda guardado con el del encabezado.

Percepciones e impuestos

Son las percepciones que se suman al comprobante. Cada fila es un objeto dentro de transaccionPercepcionItems, y toda la sección es opcional.

En el listado de GET /percepcionBean el identificador viene en percepcionId. Para referenciarlo desde la factura mandalo como { "ID": -55 }, o usá el código de la percepción.

Ejemplo

"transaccionPercepcionItems": [
  {
    "percepcionImpuesto": { "ID": -55 },
    "importe": 900,
    "descripcion": "Percepción IIBB CABA"
  }
]

La percepción se suma al total del comprobante. Si la factura es al contado, el cobro tiene que cubrir ese total con la percepción incluida.

Los instrumentos de cobro

Es con qué te pagan. Solo va si la condición de pago es contado, y cada fila es un objeto dentro de transaccionCobranzaItems. El total de los cobros tiene que coincidir exactamente con el total del comprobante, con el IVA y las percepciones incluidas. Si no coincide, el alta se rechaza con el detalle de la diferencia: Suma del Debe: 20000.00. Suma del Haber: 30000.00, Diferencia: 10000.00.

Los cuatro campos del cheque quedan guardados en el comprobante y los recuperás con GET /comprobanteVentaBean/{transaccionid}.

Ejemplo

"transaccionCobranzaItems": [
  {
    "cuentaId": -2,
    "moneda": { "codigo": "PESOS_ARGENTINOS" },
    "cotizacionMonTransaccion": 1,
    "importeMonTransaccion": 36300,
    "banco": { "codigo": "BANCO_BICA" },
    "numeroCheque": "12345678",
    "fechaVto": "2026-11-30",
    "descripcion": "Cheque a 60 días"
  }
]

Si la moneda o la cotización del cobro no son las del comprobante, el alta se rechaza con Todos los items de cobro deben tener la misma moneda y cotización que la factura.

Tipos de comprobante

Respuesta

Te devuelve el mismo comprobante que mandaste, más el transaccionid y el numeroDocumento que asignó Xubio. Los campos que no mandaste y quedaron con su valor por defecto, como el circuito contable, también vuelven completos.

{
  "transaccionid": 101224258,
  "numeroDocumento": "A-00003-00001547",
  "fecha": "2026-09-25",
  "condicionDePago": 2,
  "tipo": 1,
  "cliente": { "ID": 13103455, "id": 13103455 },
  "puntoVenta": { "ID": 4821, "codigo": "0003", "id": 4821 },
  "circuitoContable": { "ID": -2, "id": -2 },
  "transaccionProductoItems": [
    {
      "producto": { "ID": 3529585, "codigo": "SERVICIO_DE_MANTENIMIENTO_MENSUAL", "id": 3529585 },
      "cantidad": 2,
      "precio": 15000
    }
  ],
  "transaccionCobranzaItems": [
    {
      "cuentaId": -13,
      "moneda": { "ID": -2, "codigo": "PESOS_ARGENTINOS", "id": -2 },
      "cotizacionMonTransaccion": 1,
      "importeMonTransaccion": 36300,
      "importeMonPrincipal": 36300
    }
  ],
  "tienePeriodoServicio": false
}

Guardá el transaccionid: lo vas a necesitar en el paso siguiente.

Tené en cuenta que la respuesta no trae los importes calculados —total, gravado ni impuestos— ni el CAE. Para eso, consultá el comprobante con GET /API/1.1/comprobanteVentaBean/{transaccionid}.

Paso 4Pedí el CAE

POST /API/1.1/solicitarCAE

Ejemplo

{
  "transaccionId": 98432
}

Obligatorio: transaccionId o externalId.

Si ARCA autoriza el comprobante, recibís el CAE y su fecha de vencimiento:

Respuesta

{
  "cae": "75318294016523",
  "caeFechaVto": "2026-10-05",
  "transaccionId": 98432
}

Listo: la factura quedó emitida y autorizada.

Obtené el PDF

GET /API/1.1/imprimirPDF?idtransaccion=98432&tipoimpresion=1

Obligatorio: idtransaccion y tipoimpresion, que va del 1 al 5 y tiene que existir para ese tipo de comprobante. No hay parámetros opcionales.

Respuesta

{
  "urlPdf": "https://xubio.com/NXV/ImprimirPdf?transaccionid=98432&tenant=tnt_000000&tipoimpresion=1"
}

No devuelve el archivo: devuelve el link de descarga en el campo urlPdf.

Enviá el comprobante por mail

POST /API/1.1/enviarTransaccionPorMail

Ejemplo

{
  "transaccionId": 98432,
  "para": "administracion@distribuidoradelnorte.com",
  "asunto": "Factura A-00003-00001547",
  "cuerpo": "Te adjuntamos la factura correspondiente a tu compra."
}

Obligatorio: transaccionId, y al menos una dirección de destino.

Opcional: para, copia y copiaOculta (separadas por punto y coma, hasta cinco por campo), asunto, cuerpo y la marca para adjuntar el certificado de retención.

Tres cosas a tener en cuenta: el mail del cliente no se toma automáticamente, tenés que mandarlo siempre; el PDF se adjunta solo, con el formato por defecto del comprobante; y la respuesta confirma que recibimos el pedido, no que el mail haya llegado.

Emití una nota de crédito

No hay un endpoint aparte: se usa el mismo de la factura. El cuerpo es igual al del Paso 3 —cliente, punto de venta, fecha, condición de pago e items— y cambian solo estos tres campos.

Ejemplo

{
  "tipo": 3,
  "comprobante": 98432,
  "comprobanteAsociado": 1
}

comprobante es el transaccionid de la factura original y comprobanteAsociado indica el tipo de vínculo: 1 por comprobante, 2 por período.

De los dos, el que no podés omitir es comprobanteAsociado: sin él el alta se rechaza con El campo comprobanteAsociado debe contener el valor 1 (comprobante) o 2 (período). Si elegís por período, sumá también fechaDesde y fechaHasta.

El cliente de la nota de crédito tiene que ser el mismo que el de la factura original. Si no coincide, el alta se rechaza con El ID cliente del comprobante creado debe coincidir con el ID cliente del comprobante asociado.

Después pedile el CAE igual que a cualquier comprobante.

Preguntas frecuentes