API REST · Facturando

Documentación de la API

Referencia completa para integrar tu sistema con Facturando: autenticación, emisión de comprobantes electrónicos ante SET, productos, clientes y más.

Ingresá con tu API key

La documentación es pública. Con tu API key se habilita la Consola para probar la integración con llamadas reales a tu cuenta.

La key se valida contra la API y queda solo en este navegador mientras dure la sesión. ¿No tenés una? Generala en x.facturando.com o conocé el Plan API.

Introducción

La API REST de Facturando permite que cualquier software, ERP, app o e-commerce cree ventas con emisión de comprobante electrónico automática ante SET, y administre productos, categorías, clientes y proveedores de tu cuenta.

Todas las solicitudes van sobre HTTPS, se autentican con un token Bearer y responden JSON. La regla más importante:

Un solo POST /sales hace todo. Valida cliente, emisor y sucursal, calcula impuestos y descuentos, registra el pago, emite el comprobante ante SET y devuelve CAE, serie, número y las URLs públicas del PDF. La venta solo se confirma si SET acepta; si no, no queda nada creado.

Cómo empezar

  1. Generá un token en x.facturando.com → Configuración → API.
  2. Consultá GET /billers, GET /warehouses y GET /tax-rates para obtener los IDs de emisor, sucursal e impuestos.
  3. Creá o buscá el cliente en /customers (con el RUC alcanza: se completa desde SET).
  4. Enviá el POST /sales con los ítems. Listo: el comprobante está emitido.
Para probar con tu cuenta, ingresá tu API key y se habilita la Consola: venta rápida, consultas de cualquier recurso y notas de crédito, con la respuesta real de la API.

URL base y ambientes

Base URL
https://x.facturando.com/x/api/rest-api

Todos los endpoints de esta documentación son relativos a esa URL. Por ejemplo, GET /products es https://x.facturando.com/x/api/rest-api/products.

Los comprobantes que se emiten desde la API son reales y quedan registrados ante SET. Para probar tu integración usá un emisor de pruebas de tu cuenta o coordiná con soporte antes de emitir. No emitas "para ver qué pasa".

Autenticación

Incluí el token en el header Authorization de cada solicitud:

Header
Authorization: Bearer fct_tu_token
  • Los tokens se crean y revocan desde x.facturando.com → Configuración → API. El valor completo se muestra una sola vez al crearlo: guardalo en un lugar seguro.
  • Podés asignarles un nombre (por integración) y una fecha de expiración. Un token expirado o desactivado responde 401.
  • Cada solicitud queda registrada (endpoint, código de respuesta, duración) y podés verla en la pestaña de uso.
  • El token identifica a tu cuenta: todos los recursos que consultes o crees pertenecen a ella.
Ejemplo
curl -X GET "https://x.facturando.com/x/api/rest-api/products?page=1&per_page=10" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Formato de respuesta y errores

Todas las respuestas son JSON. Los listados vienen envueltos en data con un bloque pagination:

Lista paginada
{
  "data": [ { ... }, { ... } ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": null
  }
}

Al obtener, crear o actualizar un registro, la respuesta es el objeto en sí. Los errores devuelven un objeto con la clave error y el código HTTP correspondiente:

Error (400)
{ "error": "biller_id es requerido" }

Ante un error interno, la respuesta trae un request_id. Citalo al escribir a soporte: con él ubicamos el detalle completo en nuestros registros.

Error (500)
{
  "error": "Error interno del servidor",
  "request_id": "6f1c2a9e-3b0d-4c58-9a1e-2d7f0c3b8e41"
}
Evaluá siempre el código HTTP. Un 2xx significa que la operación se completó; en el caso de POST /sales, que el comprobante fue aceptado por SET.

Paginación, orden y búsqueda

Los endpoints de listado (GET /recurso) aceptan estos parámetros de consulta:

ParámetroTipoDescripción
pageintegerNúmero de página (default: 1)
per_pageintegerResultados por página, máximo 100 (default: 50)
sort_bystringCampo para ordenar (default: created_at)
sort_dirstringDirección del orden: asc o desc (default: desc)
searchstringBúsqueda por nombre en products, customers y suppliers
Ejemplo
curl -X GET "https://x.facturando.com/x/api/rest-api/products?page=2&per_page=25&sort_by=name&sort_dir=asc&search=coca" \
  -H "Authorization: Bearer fct_tu_token"

Crear una venta (proceso completo)

Para crear una venta y emitir su comprobante se realiza un solo POST /sales, que ejecuta todo el proceso automáticamente:

  1. Valida que el cliente, el emisor y la sucursal existan en tu cuenta.
  2. Calcula impuestos por cada ítem según su tax_rate_id y tax_method.
  3. Aplica descuentos por ítem (valor fijo o porcentaje con %).
  4. Crea la venta con todos los totales calculados y sus ítems.
  5. Registra el pago si el monto pagado es mayor a 0.
  6. Emite el comprobante electrónico ante SET a través del emisor indicado.
  7. Devuelve la venta con la respuesta de facturación y las URLs del PDF.
Ejemplos cURL
# Crear venta con facturacion electronica automatica
curl -X POST "https://x.facturando.com/x/api/rest-api/sales" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "019e1a90-622b-73c7-ab65-8e65b4d55be7",
    "biller_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0001",
    "warehouse_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0002",
    "payment_method": "cash",
    "currency": "UYU",
    "note": "Venta mostrador",
    "pdf_format": "a4",
    "items": [
      {
        "product_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d40",
        "product_code": "PROD-001",
        "product_name": "Coca-Cola 1.5L",
        "quantity": 2,
        "unit_price": 95.00,
        "tax_rate_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d30",
        "tax_method": "inclusive"
      },
      {
        "product_name": "Servicio de envio",
        "quantity": 1,
        "unit_price": 500.00,
        "discount": "10%",
        "tax_rate_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d30",
        "tax_method": "inclusive"
      }
    ]
  }'

# Respuesta HTTP 201 — la venta ya quedo facturada (CFE asignado por DGI):
# {
#   "id": "019f12a3-7c4d-71b2-8d3e-aaaaaaaaaaaa",
#   "reference_no": "VENTA-A1B2C3",
#   "cfe_name": "e-Ticket",
#   "serie": "A",
#   "numero": 12345,
#   "grand_total": 640.00,
#   "total": 640.00,
#   "total_tax": 115.41,
#   "payment_status": "paid",
#   "sale_status": "completed",
#   "billing_status": null,
#   "billing_status_reason": null,
#   "pdf_url_a4": "https://x.facturando.com/pdf/Ab3dE9",
#   "pdf_url_ticket": "https://x.facturando.com/pdft/Ab3dE9",
#   "items": [ ... ]
# }

# Crear venta en USD (cotizacion la pone el sistema desde currencies del tenant)
curl -X POST "https://x.facturando.com/x/api/rest-api/sales" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "019e1a90-622b-73c7-ab65-8e65b4d55be7",
    "biller_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0001",
    "warehouse_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0002",
    "currency": "USD",
    "items": [
      {
        "product_name": "Consultoria",
        "quantity": 5,
        "unit_price": 80.00,
        "tax_method": "exclusive"
      }
    ]
  }'

# PDF: pdf_url_a4 / pdf_url_ticket abren una pagina para verlo en el navegador.
# Para descargar el ARCHIVO PDF (ej. adjuntarlo a un correo) usa el codigo del
# final de esa URL en la API:
curl -o comprobante.pdf "https://x.facturando.com/x/api/pdf/Ab3dE9"      # A4
curl -o ticket.pdf      "https://x.facturando.com/x/api/pdft/Ab3dE9"     # ticket

# Estado en DGI: si DGI rechaza el comprobante despues de emitido, GET /sales/:id
# devuelve "sale_status": "rechazado_dgi", "billing_status": "rejected" y el
# motivo en "billing_status_reason". Cada venta se envia a DGI con su propio
# identificador, asi que se pueden crear ventas en paralelo.

Campos de la venta

CampoTipoRequeridoDescripción
customer_iduuidSíID del cliente (ver /customers)
biller_iduuidSíID del emisor (ver /billers). Debe tener la facturación electrónica activa
warehouse_iduuidSíID de la sucursal (ver /warehouses)
itemsarraySíÍtems de la venta, al menos uno (ver estructura abajo)
datestringNoFecha ISO (default: fecha actual)
payment_methodstringNocash, transfer, card, cheque u other (default: cash)
paidnumberNoMonto pagado (default: el total de la venta)
currencystringNoCódigo de moneda ISO (default: PYG). En otra moneda, la cotización la toma el sistema de /currencies
notestringNoNota o comentario
pdf_formatstringNoticket o a4 (default: a4)
reference_nostringNoNúmero de referencia. Si no se envía se genera (VENTA-00001)

Estructura de cada ítem

CampoTipoRequeridoDescripción
product_iduuidNoID del producto. Si es null, se trata como ítem manual
product_codestringNoCódigo del producto
product_namestringSíNombre del producto o servicio
quantitynumberSíCantidad (default: 1)
unit_pricenumberSíPrecio unitario
discountstringNoDescuento: "100" (fijo) o "10%" (porcentaje)
tax_rate_iduuidNoID de la tasa de impuesto a aplicar (ver /tax-rates)
tax_methodstringNo"exclusive" (el impuesto se suma) o "inclusive" (impuesto incluido en el precio)
Si el ítem trae product_id, se toma como venta de un producto de tu catálogo. Si no, es un ítem manual (por ejemplo un servicio) y alcanza con product_name, quantity y unit_price.

Lógica de pago

  • Si no enviás paid, se asume pago total y el estado queda como paid.
  • Si enviás paid: 0, la venta queda como pending (sin pago).
  • Si enviás un monto menor al total, queda como partial (pago parcial).

Campos autogenerados

Los siguientes campos se calculan automáticamente y no deben enviarse:

  • reference_no: se genera solo (VENTA-00001). Si enviás uno que ya existe, se genera uno nuevo.
  • grand_total, total, total_tax: calculados a partir de los ítems.
  • payment_status: determinado según el monto pagado.
  • customer: nombre del cliente obtenido del customer_id.
  • Subtotales e impuestos de cada ítem.
  • serie, numero, cfe_name: se completan con la respuesta de facturación.

Respuesta del POST /sales

La respuesta incluye el ID de la venta, la respuesta de facturación electrónica (billing_response) y las URLs públicas del PDF:

201 Created
{
  "id": "a13aae8d-33f7-488c-a85e-fbdfc77a27b7",
  "billing_response": {
    "CfeId": "101",
    "Serie": "A",
    "Número": "626",
    "CfeName": "e-Ticket",
    "FecEmis": "2026-03-05T21:08:06.000000Z",
    "FecVenc": null,
    "Cotizacion": "1.000",
    "DataToGeneratePDF": {
      "CAE": {
        "DNro": "1",
        "HNro": "9999999",
        "CAE_ID": "99999999993",
        "FecVenc": "2038-01-19"
      },
      "URLDGI": "https://www.efactura.dgi.gub.uy/...",
      "DocCodSeg": "/Ez4IL"
    }
  },
  "pdf_url_a4": "https://x.facturando.com/sale/uuid/pdf",
  "pdf_url_ticket": "https://x.facturando.com/sale/uuid/pdf/ticket"
}
CampoDescripción
billing_response.CfeIdTipo de CFE (101 e-Ticket, 111 e-Factura, etc.)
billing_response.SerieSerie del comprobante
billing_response.NúmeroNúmero asignado dentro de la serie
billing_response.CfeNameNombre del tipo de comprobante
DataToGeneratePDF.CAEConstancia de Autorización de Emisión utilizada (número y vencimiento)
DataToGeneratePDF.URLDGIURL de verificación del comprobante en SET
DataToGeneratePDF.DocCodSegCódigo de seguridad del comprobante
pdf_url_a4PDF en formato A4, público, listo para enviar al cliente
pdf_url_ticketPDF en formato ticket

Reglas de facturación electrónica

  • El emisor (biller_id) debe tener la integración de facturación electrónica activa. Si no la tiene, la venta no se crea y se devuelve 422.
  • Si la facturación electrónica responde con error, la venta se elimina automáticamente y se devuelve 502 con el detalle del error.
  • Solo se confirma la venta si la facturación electrónica responde exitosamente. No existen ventas "a medias".
Qué tipo de comprobante corresponde, qué indicador de facturación lleva cada ítem o cómo tratar una exoneración son definiciones fiscales, no de la API. Si tenés dudas, consultá a tu contador antes de emitir: un comprobante emitido con criterio equivocado solo se corrige con otro comprobante.

Consultar ventas y PDF

GET /sales devuelve por cada venta el id, la billing_response y las URLs pdf_url_a4 y pdf_url_ticket. GET /sales/:id devuelve la venta completa con sus ítems (también disponibles en /sale-items).

Las URLs de PDF son públicas y estables: podés guardarlas, enviarlas por email o WhatsApp, o mostrarlas en tu sistema.

Productos /products

  • GET/productsListar todos los productos
  • GET/products/:idObtener un producto por ID
  • POST/productsCrear un nuevo producto
  • PUT/products/:idActualizar un producto
  • DELETE/products/:idEliminar un producto

Campos

CampoTipoDescripción
codestringCódigo único del producto
namestringNombre del producto
pricenumberPrecio de venta
costnumberCosto del producto
quantitynumberCantidad en stock
category_iduuidID de la categoria
barcodestringCódigo de barras
tax_rate_iduuidID de la tasa de impuesto

Ejemplo cURL

/products
# Listar productos con paginacion + busqueda
curl -X GET "https://x.facturando.com/x/api/rest-api/products?page=1&per_page=10&search=coca" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Crear producto
curl -X POST "https://x.facturando.com/x/api/rest-api/products" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "PROD-001",
    "name": "Coca-Cola 1.5L",
    "price": 95.00,
    "cost": 65.00,
    "quantity": 120,
    "barcode": "7790895000232",
    "category_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d20",
    "tax_rate_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d30"
  }'

Categorias /categories

  • GET/categoriesListar todas las categorias
  • GET/categories/:idObtener una categoria por ID
  • POST/categoriesCrear una nueva categoria
  • PUT/categories/:idActualizar una categoria
  • DELETE/categories/:idEliminar una categoria

Campos

CampoTipoDescripción
codestringCódigo de la categoria
namestringNombre de la categoria
parent_iduuidID de la categoria padre (opcional)
descriptionstringDescripción de la categoria

Ejemplo cURL

/categories
# Crear una categoria padre
curl -X POST "https://x.facturando.com/x/api/rest-api/categories" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{"code": "BEB", "name": "Bebidas", "description": "Gaseosas, aguas y jugos"}'

# Crear sub-categoria (hija de la anterior)
curl -X POST "https://x.facturando.com/x/api/rest-api/categories" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BEB-GAS",
    "name": "Gaseosas",
    "parent_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d20"
  }'

Clientes /customers

  • GET/customersListar todos los clientes
  • GET/customers/:idObtener un cliente por ID
  • POST/customersCrear un nuevo cliente
  • PUT/customers/:idActualizar un cliente
  • DELETE/customers/:idEliminar un cliente

Campos

CampoTipoDescripción
namestringNombre del cliente. Si no enviás razon_social, se usa como nombre del comprador en el comprobante (auto-completado desde RUT si lo enviás)
razon_socialstringRazón social: es el nombre que va en el comprobante (auto-completado desde RUT; si no lo enviás se usa name)
nombre_fantasiastringNombre fantasía (auto-completado desde RUT)
rutstringRUT del cliente, 12 dígitos (también se puede enviar como tipo_documento "RUT" + numero_documento). Si ya existe un cliente con ese RUT, NO se duplica: la API devuelve 200 con { already_exists: true, id, data } y el UUID del existente.
emailstringCorreo electrónico (auto-completado desde RUT si no lo envías)
phonestringTeléfono (auto-completado desde RUT)
addressstringDirección (auto-completado desde RUT)
girostringGiro/actividad (auto-completado desde RUT)
countrystringNombre del país (default: país de la empresa)
codigo_paisstringCódigo ISO del país: "UY" para Uruguay (default: país de la empresa). Para un cliente del exterior, el código de su país: el documento se informa a DGI como documento extranjero.
citystringCiudad: nombre exacto de una ciudad de Uruguay (ej. "Montevideo"). Si no coincide con ninguna queda vacía. Recomendado para e-Factura.
statestringDepartamento: nombre exacto de un departamento de Uruguay (ej. "Canelones"). Si no coincide con ninguno queda vacío. Recomendado para e-Factura.
tipo_documentostring"RUT" o "CI". Con "RUT", numero_documento se toma como RUT de la empresa (e-Factura). Con "CI", como cédula del comprador: el e-Ticket sale con el comprador identificado (obligatorio en ventas de más de 5.000 UI).
numero_documentostringNúmero de documento, solo dígitos. La cédula va con el dígito verificador (ej. 51449897); si se envían puntos o guion se quitan.
Al enviar `rut`, el endpoint consulta automáticamente DGI (igual que el Bot Facturando) y completa razón social, nombre fantasía, dirección, teléfono, email y giro si vienen vacíos en el payload. Si ya existe un cliente con ese RUT (normalizado a solo dígitos), NO se crea uno nuevo: la respuesta es **HTTP 200** con `{"already_exists": true, "id": "<uuid>", "data": {...}}`. Caso nuevo: **HTTP 201** con el registro creado.

Ejemplo cURL

/customers
# Crear cliente solo con RUT — el sistema completa razon social,
# direccion, telefono, email, giro consultando a DGI automaticamente.
curl -X POST "https://x.facturando.com/x/api/rest-api/customers" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{"rut": "218759700015"}'

# Respuesta HTTP 201 (creado):
# {
#   "id": "019f12a3-7c4d-71b2-8d3e-4a5b6c7d8e9f",
#   "name": "FILTROS URUGUAY SRL",
#   "razon_social": "FILTROS URUGUAY SRL",
#   "nombre_fantasia": "FILTROSUY",
#   "rut": "218759700015",
#   "address": "AV. ITALIA 1234",
#   "phone": "099123456",
#   "email": "[email protected]",
#   "country": "UY",
#   "codigo_pais": "UY",
#   ...
# }

# Respuesta HTTP 200 (RUT ya existe — NO se duplica):
# {
#   "already_exists": true,
#   "id": "019e1a90-622b-73c7-ab65-8e65b4d55be7",
#   "message": "Ya existe un cliente con ese RUT.",
#   "data": { "id": "019e1a90-622b-73c7-ab65-8e65b4d55be7", "rut": "218759700015", ... }
# }

# Crear cliente persona con cedula (comprador identificado en el e-Ticket;
# obligatorio en ventas de mas de 5.000 UI). La cedula va solo con digitos,
# incluido el verificador:
curl -X POST "https://x.facturando.com/x/api/rest-api/customers" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Perez",
    "tipo_documento": "CI",
    "numero_documento": "51449897",
    "email": "[email protected]",
    "phone": "098765432",
    "address": "18 de Julio 1234, Montevideo"
  }'

Proveedores /suppliers

  • GET/suppliersListar todos los proveedores
  • GET/suppliers/:idObtener un proveedor por ID
  • POST/suppliersCrear un nuevo proveedor
  • PUT/suppliers/:idActualizar un proveedor
  • DELETE/suppliers/:idEliminar un proveedor

Campos

CampoTipoDescripción
namestringNombre del proveedor (auto-completado desde RUT)
razon_socialstringRazón social (auto-completado desde RUT)
rutstringRUT del proveedor — dedup automático: si ya existe, devuelve `{already_exists: true, id, data}` con HTTP 200.
emailstringCorreo electrónico (auto-completado desde RUT)
phonestringTeléfono (auto-completado desde RUT)
addressstringDirección (auto-completado desde RUT)
Al enviar `rut`, mismo comportamiento que /customers: auto-enrich con datos de DGI + dedup por RUT.

Ejemplo cURL

/suppliers
# Crear proveedor por RUT (auto-completa razon social, etc.)
curl -X POST "https://x.facturando.com/x/api/rest-api/suppliers" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{"rut": "215033960010"}'

# Buscar proveedor por nombre
curl -X GET "https://x.facturando.com/x/api/rest-api/suppliers?search=distribuidora" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Emisores /billers

  • GET/billersListar emisores (solo lectura)
  • GET/billers/:idObtener un emisor por ID (solo lectura)

Campos

CampoTipoDescripción
iduuidUUID del emisor (usar en biller_id al crear ventas)
namestringNombre comercial
razon_socialstringRazon social
rutstringRUT del emisor

Ejemplo cURL

/billers
curl -X GET "https://x.facturando.com/x/api/rest-api/billers" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Respuesta:
# {
#   "data": [
#     {
#       "id": "019e1a90-622b-73c7-aaaa-bbbbcccc0001",
#       "name": "Casa Central",
#       "razon_social": "FILTROS URUGUAY SRL",
#       "rut": "218759700015"
#     }
#   ],
#   "meta": { "total": 1, "page": 1, "per_page": 25 }
# }

Ventas /sales

  • GET/salesListar ventas (retorna id, estado, billing_response, pdf_url_a4, pdf_url_ticket)
  • GET/sales/:idObtener una venta por ID, con su estado: sale_status ("rechazado_dgi" si DGI la rechazó), billing_status ("rejected") y billing_status_reason (motivo)
  • POST/salesCrear una venta completa (factura)

Campos

CampoTipoDescripción
customer_iduuidID del cliente (requerido al crear). Para ventas de más de 5.000 UI el cliente tiene que estar identificado (CI o RUT): ver Clientes.
biller_iduuidID del facturador (requerido al crear)
warehouse_iduuidID de la sucursal (requerido al crear)
reference_nostringNúmero de referencia (auto-generado si vacío)
datestringFecha ISO (default: fecha actual)
payment_methodstringcash, transfer, card, cheque, other (default: cash)
paidnumberMonto pagado (default: grand_total)
currencystringCódigo de moneda ISO (default: UYU)
notestringNota o comentario
pdf_formatstringticket o a4 (default: a4)
itemsarrayArray de items de la venta (requerido al crear). Cada item necesita su tax_rate_id — ver GET /tax-rates

Ejemplo cURL

/sales
# Crear venta con facturacion electronica automatica
curl -X POST "https://x.facturando.com/x/api/rest-api/sales" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "019e1a90-622b-73c7-ab65-8e65b4d55be7",
    "biller_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0001",
    "warehouse_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0002",
    "payment_method": "cash",
    "currency": "UYU",
    "note": "Venta mostrador",
    "pdf_format": "a4",
    "items": [
      {
        "product_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d40",
        "product_code": "PROD-001",
        "product_name": "Coca-Cola 1.5L",
        "quantity": 2,
        "unit_price": 95.00,
        "tax_rate_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d30",
        "tax_method": "inclusive"
      },
      {
        "product_name": "Servicio de envio",
        "quantity": 1,
        "unit_price": 500.00,
        "discount": "10%",
        "tax_rate_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d30",
        "tax_method": "inclusive"
      }
    ]
  }'

# Respuesta HTTP 201 — la venta ya quedo facturada (CFE asignado por DGI):
# {
#   "id": "019f12a3-7c4d-71b2-8d3e-aaaaaaaaaaaa",
#   "reference_no": "VENTA-A1B2C3",
#   "cfe_name": "e-Ticket",
#   "serie": "A",
#   "numero": 12345,
#   "grand_total": 640.00,
#   "total": 640.00,
#   "total_tax": 115.41,
#   "payment_status": "paid",
#   "sale_status": "completed",
#   "billing_status": null,
#   "billing_status_reason": null,
#   "pdf_url_a4": "https://x.facturando.com/pdf/Ab3dE9",
#   "pdf_url_ticket": "https://x.facturando.com/pdft/Ab3dE9",
#   "items": [ ... ]
# }

# Crear venta en USD (cotizacion la pone el sistema desde currencies del tenant)
curl -X POST "https://x.facturando.com/x/api/rest-api/sales" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "019e1a90-622b-73c7-ab65-8e65b4d55be7",
    "biller_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0001",
    "warehouse_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0002",
    "currency": "USD",
    "items": [
      {
        "product_name": "Consultoria",
        "quantity": 5,
        "unit_price": 80.00,
        "tax_method": "exclusive"
      }
    ]
  }'

# PDF: pdf_url_a4 / pdf_url_ticket abren una pagina para verlo en el navegador.
# Para descargar el ARCHIVO PDF (ej. adjuntarlo a un correo) usa el codigo del
# final de esa URL en la API:
curl -o comprobante.pdf "https://x.facturando.com/x/api/pdf/Ab3dE9"      # A4
curl -o ticket.pdf      "https://x.facturando.com/x/api/pdft/Ab3dE9"     # ticket

# Estado en DGI: si DGI rechaza el comprobante despues de emitido, GET /sales/:id
# devuelve "sale_status": "rechazado_dgi", "billing_status": "rejected" y el
# motivo en "billing_status_reason". Cada venta se envia a DGI con su propio
# identificador, asi que se pueden crear ventas en paralelo.

Notas de Crédito /credit-notes

  • GET/credit-notesListar notas de crédito emitidas
  • GET/credit-notes/:idObtener una nota de crédito por ID
  • POST/credit-notesEmitir una nota de crédito (parcial o por cualquier importe). Se pueden emitir varias NC parciales contra la misma venta (una por cada anulación parcial)
  • POST/sales/:id/voidAnular una venta completa: emite la NC por el total y repone el stock (una sola vez por venta: después responde "Esta venta ya tiene una nota de crédito asociada")

Campos

CampoTipoDescripción
customer_iduuidID del cliente (requerido)
biller_iduuidID del emisor (requerido)
warehouse_iduuidID de la sucursal (requerido)
itemsarrayÍtems a acreditar, con importes en POSITIVO (requerido). Cada ítem necesita su tax_rate_id — ver GET /tax-rates
reference_sale_iduuidVenta del sistema que se acredita: toma su tipo, serie, número y fecha, y la NC descuenta el saldo de esa factura. Se pueden emitir varias NC parciales con la misma venta. Si DGI todavía no aceptó esa venta, responde 422 ("aún no fue aceptada por DGI"): reintentá más tarde.
referenceobjectReferencia manual a un comprobante que no está en el sistema: { doc_type, serie, numero, date }
reasonstringRazón. Sin reference_sale_id ni reference se emite como referencia global (sin documento)
datestringFecha ISO (default: la de la venta referenciada, o la fecha actual)
currencystringCódigo de moneda ISO (default: el de la venta referenciada, o UYU)
notestringNota o comentario del comprobante
pdf_formatstringticket o a4 (default: a4)

Ejemplo cURL

/credit-notes
# 1) NC relacionada a una factura del sistema (descuenta su saldo)
curl -X POST "https://x.facturando.com/x/api/rest-api/credit-notes" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "019e1a90-622b-73c7-ab65-8e65b4d55be7",
    "biller_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0001",
    "warehouse_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0002",
    "reference_sale_id": "019f12a3-7c4d-71b2-8d3e-aaaaaaaaaaaa",
    "reason": "Devolucion de 1 unidad",
    "note": "Nota de credito manual",
    "items": [
      {
        "product_name": "Coca-Cola 1.5L",
        "quantity": 1,
        "unit_price": 95.00,
        "tax_rate_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d30",
        "tax_method": "inclusive"
      }
    ]
  }'

# 2) NC contra un comprobante que no esta en el sistema (referencia manual)
curl -X POST "https://x.facturando.com/x/api/rest-api/credit-notes" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "019e1a90-622b-73c7-ab65-8e65b4d55be7",
    "biller_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0001",
    "warehouse_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0002",
    "reference": { "doc_type": "111", "serie": "A", "numero": "8561", "date": "2026-06-08" },
    "note": "Nota de credito manual",
    "items": [
      { "product_name": "Ajuste de precio", "quantity": 1, "unit_price": 641.82, "tax_method": "inclusive" }
    ]
  }'

# 3) NC con razon global (sin documento de referencia)
curl -X POST "https://x.facturando.com/x/api/rest-api/credit-notes" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "019e1a90-622b-73c7-ab65-8e65b4d55be7",
    "biller_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0001",
    "warehouse_id": "019e1a90-622b-73c7-aaaa-bbbbcccc0002",
    "reason": "Bonificacion comercial acordada",
    "note": "Nota de credito manual",
    "items": [
      { "product_name": "Bonificacion", "quantity": 1, "unit_price": 1200.00, "tax_method": "inclusive" }
    ]
  }'

# Respuesta HTTP 201 (la NC ya quedo emitida ante DGI, importes en negativo):
# {
#   "id": "019f2b40-1122-7333-9aaa-bbbbbbbbbbbb",
#   "reference_no": "NC-00042",
#   "cfe_name": "Nota de Credito de e-Factura",
#   "serie": "A",
#   "numero": 684,
#   "grand_total": -95.00,
#   "pdf_url_a4": "https://x.facturando.com/sale/019f2b40.../pdf/a4"
# }

# 4) ANULAR UNA VENTA COMPLETA — equivale al boton "Anular venta"
#    Emite la NC por el total, referencia el CFE original, repone el stock
#    y deja la venta marcada como anulada. No lleva body.
curl -X POST "https://x.facturando.com/x/api/rest-api/sales/019f12a3-7c4d-71b2-8d3e-aaaaaaaaaaaa/void" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Respuesta HTTP 201:
# {
#   "voided_sale_id": "019f12a3-7c4d-71b2-8d3e-aaaaaaaaaaaa",
#   "credit_note": {
#     "id": "019f2b41-...", "reference_no": "NC-00043",
#     "cfe_name": "Nota de Credito de e-Ticket", "serie": "A", "numero": 685,
#     "grand_total": -640.00
#   }
# }

# Errores frecuentes:
#   404  La venta de reference_sale_id no existe
#   422  Esta venta ya tiene una nota de credito asociada, esta devuelta o rechazada por DGI
#   422  El emisor no tiene la facturacion electronica activa
#   403  DELETE no esta permitido: las NC no se borran, se anulan

Items de Venta /sale-items

  • GET/sale-itemsListar items de ventas
  • GET/sale-items/:idObtener un item por ID

Campos

CampoTipoDescripción
sale_iduuidID de la venta
product_iduuidID del producto (null si es manual)
product_codestringCódigo del producto
product_namestringNombre del producto
quantitynumberCantidad vendida
unit_pricenumberPrecio unitario
discountstringDescuento aplicado (valor fijo o porcentaje con %)
item_taxnumberImpuesto calculado del item
subtotalnumberSubtotal del item
tax_rate_iduuidID de la tasa de impuesto
tax_methodstringexclusive o inclusive (default: exclusive)

Ejemplo cURL

/sale-items
# Listar los items de una venta especifica
curl -X GET "https://x.facturando.com/x/api/rest-api/sale-items?sale_id=019f12a3-7c4d-71b2-8d3e-aaaaaaaaaaaa" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Sucursales (solo lectura) /warehouses

  • GET/warehousesListar sucursales
  • GET/warehouses/:idObtener una sucursal por ID

Campos

CampoTipoDescripción
codestringCódigo de la sucursal
namestringNombre de la sucursal
addressstringDirección

Ejemplo cURL

/warehouses
curl -X GET "https://x.facturando.com/x/api/rest-api/warehouses" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Respuesta:
# {
#   "data": [
#     { "id": "019e1a90-...-0002", "code": "MVD", "name": "Casa Central", "address": "AV. ITALIA 1234" },
#     { "id": "019e1a90-...-0003", "code": "PUN", "name": "Sucursal Punta del Este", "address": "Av. Roosevelt s/n" }
#   ],
#   "meta": { "total": 2, "page": 1, "per_page": 25 }
# }

Stock por Sucursal (solo lectura) /stock

  • GET/stockListar stock de productos por sucursal

Campos

CampoTipoDescripción
product_iduuidID del producto
warehouse_iduuidID de la sucursal
quantitynumberCantidad en stock

Ejemplo cURL

/stock
# Stock de todos los productos en todas las sucursales
curl -X GET "https://x.facturando.com/x/api/rest-api/stock?page=1&per_page=100" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Stock de un producto en particular
curl -X GET "https://x.facturando.com/x/api/rest-api/stock?product_id=019d9c10-a3f1-7012-bc34-58e9aa1f5d40" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Monedas (solo lectura) /currencies

  • GET/currenciesListar todas las monedas
  • GET/currencies/:idObtener una moneda por ID

Campos

CampoTipoDescripción
codestringCódigo de la moneda (ej: UYU, USD)
namestringNombre de la moneda
symbolstringSimbolo de la moneda (ej: $, US$)
ratenumberTasa de cambio
is_defaultbooleanSi es la moneda por defecto

Ejemplo cURL

/currencies
curl -X GET "https://x.facturando.com/x/api/rest-api/currencies" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Respuesta:
# {
#   "data": [
#     { "id": "...", "code": "UYU", "name": "Peso Uruguayo", "symbol": "$", "rate": 1.0, "is_default": true },
#     { "id": "...", "code": "USD", "name": "Dolar Estadounidense", "symbol": "US$", "rate": 39.85, "is_default": false }
#   ],
#   "meta": { "total": 2, "page": 1, "per_page": 25 }
# }

Impuestos (solo lectura) /tax-rates

  • GET/tax-ratesListar todas las tasas de impuesto
  • GET/tax-rates/:idObtener una tasa de impuesto por ID

Campos

CampoTipoDescripción
codestringCódigo de la tasa de impuesto
namestringNombre del impuesto (ej: IVA 22%)
ratenumberPorcentaje del impuesto
ind_fact_idstringIndicador de facturación (para CFE)

Ejemplo cURL

/tax-rates
curl -X GET "https://x.facturando.com/x/api/rest-api/tax-rates" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Respuesta tipica para UY:
# {
#   "data": [
#     { "id": "...d30", "code": "BASICO", "name": "IVA Basico", "rate": 22, "ind_fact_id": 3 },
#     { "id": "...d31", "code": "MINIMO", "name": "IVA Minimo", "rate": 10, "ind_fact_id": 2 },
#     { "id": "...d32", "code": "EXENTO", "name": "Exento", "rate": 0, "ind_fact_id": 1 }
#   ],
#   "meta": { "total": 3, "page": 1, "per_page": 25 }
# }

Unidades (solo lectura) /units

  • GET/unitsListar todas las unidades de medida
  • GET/units/:idObtener una unidad por ID

Campos

CampoTipoDescripción
codestringCódigo de la unidad
namestringNombre de la unidad (ej: Kilogramo, Litro)
base_unitstringUnidad base de referencia
operatorstringOperador de conversion (* o /)
operation_valuenumberValor de conversion

Ejemplo cURL

/units
curl -X GET "https://x.facturando.com/x/api/rest-api/units" \
  -H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Respuesta:
# {
#   "data": [
#     { "id": "...", "code": "UN", "name": "Unidad", "base_unit": null },
#     { "id": "...", "code": "KG", "name": "Kilogramo", "base_unit": "UN", "operator": "*", "operation_value": 1 },
#     { "id": "...", "code": "LT", "name": "Litro", "base_unit": "UN", "operator": "*", "operation_value": 1 }
#   ],
#   "meta": { "total": 3, "page": 1, "per_page": 25 }
# }

Códigos de estado HTTP

CódigoSignificado
200Solicitud exitosa
201Recurso creado exitosamente
400Error en la solicitud (datos inválidos o campo requerido faltante)
401Token inválido, inactivo o expirado
403Operación no permitida en este recurso
404Recurso o registro no encontrado
405Método HTTP no soportado (por ejemplo, POST sobre un recurso de solo lectura)
422El emisor no tiene la facturación electrónica activa: la venta no se crea
502La facturación electrónica respondió con error: la venta se elimina y se devuelve el detalle
500Error interno. La respuesta incluye un request_id para citar al soporte

Límites y buenas prácticas

  • Máximo 100 resultados por página en los listados.
  • Todas las solicitudes quedan registradas para auditoría (endpoint, código y duración).
  • Usá un token por integración y ponele fecha de expiración; revocalo si se filtra.
  • Antes de crear un cliente, buscalo por RUC: el endpoint no duplica y te devuelve el existente.
  • Guardá el id de la venta y las URLs de PDF que devuelve el POST /sales; son tu comprobante de la operación.
  • Ante un 502 revisá el detalle antes de reintentar: suele ser un dato del cliente o del ítem que SET rechaza.

Soporte

¿Algo no cierra o necesitás un campo que no está acá? Escribinos a [email protected] con el request_id si lo tenés, o hablanos por WhatsApp al 0973 781188.

← Volver a la presentación de la API