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
- Generá un token en x.facturando.com → Configuración → API.
- Consultá
GET /billers, GET /warehouses y GET /tax-rates para obtener los IDs de emisor, sucursal e impuestos. - Creá o buscá el cliente en
/customers (con el RUC alcanza: se completa desde SET). - 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.
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".
Incluí el token en el header Authorization de cada solicitud:
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.
curl -X GET "https://x.facturando.com/x/api/rest-api/products?page=1&per_page=10" \
-H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
Todas las respuestas son JSON. Los listados vienen envueltos en data con un bloque pagination:
{
"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": "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": "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.
Los endpoints de listado (GET /recurso) aceptan estos parámetros de consulta:
| Parámetro | Tipo | Descripción |
|---|
page | integer | Número de página (default: 1) |
per_page | integer | Resultados por página, máximo 100 (default: 50) |
sort_by | string | Campo para ordenar (default: created_at) |
sort_dir | string | Dirección del orden: asc o desc (default: desc) |
search | string | Búsqueda por nombre en products, customers y suppliers |
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"
Para crear una venta y emitir su comprobante se realiza un solo POST /sales, que ejecuta todo el proceso automáticamente:
- Valida que el cliente, el emisor y la sucursal existan en tu cuenta.
- Calcula impuestos por cada ítem según su
tax_rate_id y tax_method. - Aplica descuentos por ítem (valor fijo o porcentaje con
%). - Crea la venta con todos los totales calculados y sus ítems.
- Registra el pago si el monto pagado es mayor a 0.
- Emite el comprobante electrónico ante SET a través del emisor indicado.
- Devuelve la venta con la respuesta de facturación y las URLs del PDF.
# 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.
| Campo | Tipo | Requerido | Descripción |
|---|
customer_id | uuid | Sí | ID del cliente (ver /customers) |
biller_id | uuid | Sí | ID del emisor (ver /billers). Debe tener la facturación electrónica activa |
warehouse_id | uuid | Sí | ID de la sucursal (ver /warehouses) |
items | array | Sí | Ítems de la venta, al menos uno (ver estructura abajo) |
date | string | No | Fecha ISO (default: fecha actual) |
payment_method | string | No | cash, transfer, card, cheque u other (default: cash) |
paid | number | No | Monto pagado (default: el total de la venta) |
currency | string | No | Código de moneda ISO (default: PYG). En otra moneda, la cotización la toma el sistema de /currencies |
note | string | No | Nota o comentario |
pdf_format | string | No | ticket o a4 (default: a4) |
reference_no | string | No | Número de referencia. Si no se envía se genera (VENTA-00001) |
| Campo | Tipo | Requerido | Descripción |
|---|
product_id | uuid | No | ID del producto. Si es null, se trata como ítem manual |
product_code | string | No | Código del producto |
product_name | string | Sí | Nombre del producto o servicio |
quantity | number | Sí | Cantidad (default: 1) |
unit_price | number | Sí | Precio unitario |
discount | string | No | Descuento: "100" (fijo) o "10%" (porcentaje) |
tax_rate_id | uuid | No | ID de la tasa de impuesto a aplicar (ver /tax-rates) |
tax_method | string | No | "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.
- 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).
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.
La respuesta incluye el ID de la venta, la respuesta de facturación electrónica (billing_response) y las URLs públicas del PDF:
{
"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"
}
| Campo | Descripción |
|---|
billing_response.CfeId | Tipo de CFE (101 e-Ticket, 111 e-Factura, etc.) |
billing_response.Serie | Serie del comprobante |
billing_response.Número | Número asignado dentro de la serie |
billing_response.CfeName | Nombre del tipo de comprobante |
DataToGeneratePDF.CAE | Constancia de Autorización de Emisión utilizada (número y vencimiento) |
DataToGeneratePDF.URLDGI | URL de verificación del comprobante en SET |
DataToGeneratePDF.DocCodSeg | Código de seguridad del comprobante |
pdf_url_a4 | PDF en formato A4, público, listo para enviar al cliente |
pdf_url_ticket | PDF en formato ticket |
- 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.
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.
- 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
| Campo | Tipo | Descripción |
|---|
code | string | Código único del producto |
name | string | Nombre del producto |
price | number | Precio de venta |
cost | number | Costo del producto |
quantity | number | Cantidad en stock |
category_id | uuid | ID de la categoria |
barcode | string | Código de barras |
tax_rate_id | uuid | ID de la tasa de impuesto |
Ejemplo cURL
# 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"
}'
- 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
| Campo | Tipo | Descripción |
|---|
code | string | Código de la categoria |
name | string | Nombre de la categoria |
parent_id | uuid | ID de la categoria padre (opcional) |
description | string | Descripción de la categoria |
Ejemplo cURL
# 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"
}'
- 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
| Campo | Tipo | Descripción |
|---|
name | string | Nombre 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_social | string | Razón social: es el nombre que va en el comprobante (auto-completado desde RUT; si no lo enviás se usa name) |
nombre_fantasia | string | Nombre fantasía (auto-completado desde RUT) |
rut | string | RUT 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. |
email | string | Correo electrónico (auto-completado desde RUT si no lo envías) |
phone | string | Teléfono (auto-completado desde RUT) |
address | string | Dirección (auto-completado desde RUT) |
giro | string | Giro/actividad (auto-completado desde RUT) |
country | string | Nombre del país (default: país de la empresa) |
codigo_pais | string | Có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. |
city | string | Ciudad: nombre exacto de una ciudad de Uruguay (ej. "Montevideo"). Si no coincide con ninguna queda vacía. Recomendado para e-Factura. |
state | string | Departamento: nombre exacto de un departamento de Uruguay (ej. "Canelones"). Si no coincide con ninguno queda vacío. Recomendado para e-Factura. |
tipo_documento | string | "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_documento | string | Nú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
# 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"
}'
- 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
| Campo | Tipo | Descripción |
|---|
name | string | Nombre del proveedor (auto-completado desde RUT) |
razon_social | string | Razón social (auto-completado desde RUT) |
rut | string | RUT del proveedor — dedup automático: si ya existe, devuelve `{already_exists: true, id, data}` con HTTP 200. |
email | string | Correo electrónico (auto-completado desde RUT) |
phone | string | Teléfono (auto-completado desde RUT) |
address | string | Dirección (auto-completado desde RUT) |
Al enviar `rut`, mismo comportamiento que /customers: auto-enrich con datos de DGI + dedup por RUT.
Ejemplo cURL
# 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"
- GET
/billersListar emisores (solo lectura) - GET
/billers/:idObtener un emisor por ID (solo lectura)
Campos
| Campo | Tipo | Descripción |
|---|
id | uuid | UUID del emisor (usar en biller_id al crear ventas) |
name | string | Nombre comercial |
razon_social | string | Razon social |
rut | string | RUT del emisor |
Ejemplo cURL
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 }
# }
- 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
| Campo | Tipo | Descripción |
|---|
customer_id | uuid | ID 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_id | uuid | ID del facturador (requerido al crear) |
warehouse_id | uuid | ID de la sucursal (requerido al crear) |
reference_no | string | Número de referencia (auto-generado si vacío) |
date | string | Fecha ISO (default: fecha actual) |
payment_method | string | cash, transfer, card, cheque, other (default: cash) |
paid | number | Monto pagado (default: grand_total) |
currency | string | Código de moneda ISO (default: UYU) |
note | string | Nota o comentario |
pdf_format | string | ticket o a4 (default: a4) |
items | array | Array de items de la venta (requerido al crear). Cada item necesita su tax_rate_id — ver GET /tax-rates |
Ejemplo 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.
- 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
| Campo | Tipo | Descripción |
|---|
customer_id | uuid | ID del cliente (requerido) |
biller_id | uuid | ID del emisor (requerido) |
warehouse_id | uuid | ID de la sucursal (requerido) |
items | array | Ítems a acreditar, con importes en POSITIVO (requerido). Cada ítem necesita su tax_rate_id — ver GET /tax-rates |
reference_sale_id | uuid | Venta 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. |
reference | object | Referencia manual a un comprobante que no está en el sistema: { doc_type, serie, numero, date } |
reason | string | Razón. Sin reference_sale_id ni reference se emite como referencia global (sin documento) |
date | string | Fecha ISO (default: la de la venta referenciada, o la fecha actual) |
currency | string | Código de moneda ISO (default: el de la venta referenciada, o UYU) |
note | string | Nota o comentario del comprobante |
pdf_format | string | ticket o a4 (default: a4) |
Ejemplo cURL
# 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
- GET
/sale-itemsListar items de ventas - GET
/sale-items/:idObtener un item por ID
Campos
| Campo | Tipo | Descripción |
|---|
sale_id | uuid | ID de la venta |
product_id | uuid | ID del producto (null si es manual) |
product_code | string | Código del producto |
product_name | string | Nombre del producto |
quantity | number | Cantidad vendida |
unit_price | number | Precio unitario |
discount | string | Descuento aplicado (valor fijo o porcentaje con %) |
item_tax | number | Impuesto calculado del item |
subtotal | number | Subtotal del item |
tax_rate_id | uuid | ID de la tasa de impuesto |
tax_method | string | exclusive o inclusive (default: exclusive) |
Ejemplo cURL
# 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"
- GET
/warehousesListar sucursales - GET
/warehouses/:idObtener una sucursal por ID
Campos
| Campo | Tipo | Descripción |
|---|
code | string | Código de la sucursal |
name | string | Nombre de la sucursal |
address | string | Dirección |
Ejemplo cURL
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 }
# }
- GET
/stockListar stock de productos por sucursal
Campos
| Campo | Tipo | Descripción |
|---|
product_id | uuid | ID del producto |
warehouse_id | uuid | ID de la sucursal |
quantity | number | Cantidad en stock |
Ejemplo cURL
# 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"
- GET
/currenciesListar todas las monedas - GET
/currencies/:idObtener una moneda por ID
Campos
| Campo | Tipo | Descripción |
|---|
code | string | Código de la moneda (ej: UYU, USD) |
name | string | Nombre de la moneda |
symbol | string | Simbolo de la moneda (ej: $, US$) |
rate | number | Tasa de cambio |
is_default | boolean | Si es la moneda por defecto |
Ejemplo cURL
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 }
# }
- GET
/tax-ratesListar todas las tasas de impuesto - GET
/tax-rates/:idObtener una tasa de impuesto por ID
Campos
| Campo | Tipo | Descripción |
|---|
code | string | Código de la tasa de impuesto |
name | string | Nombre del impuesto (ej: IVA 22%) |
rate | number | Porcentaje del impuesto |
ind_fact_id | string | Indicador de facturación (para CFE) |
Ejemplo cURL
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 }
# }
- GET
/unitsListar todas las unidades de medida - GET
/units/:idObtener una unidad por ID
Campos
| Campo | Tipo | Descripción |
|---|
code | string | Código de la unidad |
name | string | Nombre de la unidad (ej: Kilogramo, Litro) |
base_unit | string | Unidad base de referencia |
operator | string | Operador de conversion (* o /) |
operation_value | number | Valor de conversion |
Ejemplo cURL
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ódigo | Significado |
|---|
200 | Solicitud exitosa |
201 | Recurso creado exitosamente |
400 | Error en la solicitud (datos inválidos o campo requerido faltante) |
401 | Token inválido, inactivo o expirado |
403 | Operación no permitida en este recurso |
404 | Recurso o registro no encontrado |
405 | Método HTTP no soportado (por ejemplo, POST sobre un recurso de solo lectura) |
422 | El emisor no tiene la facturación electrónica activa: la venta no se crea |
502 | La facturación electrónica respondió con error: la venta se elimina y se devuelve el detalle |
500 | Error interno. La respuesta incluye un request_id para citar al soporte |
- 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.
¿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