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 DGII, 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 e-CF ante DGII y devuelve el e-NCF, el código de seguridad y las URLs públicas del PDF. La venta solo se confirma si DGII la recibe; 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 RNC alcanza: se completa desde DGII). - 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 DGII. 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 DGII.
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 DGII 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": "DOP",
"note": "Venta mostrador",
"pdf_format": "a4",
"items": [
{
"product_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d40",
"product_code": "PROD-001",
"product_name": "Cafe molido 1 lb",
"quantity": 2,
"unit_price": 350,
"tax_rate_id": "d0a5e10a-0000-4000-8000-000000000118",
"tax_method": "inclusive"
},
{
"product_name": "Servicio de envio",
"quantity": 1,
"unit_price": 500,
"discount": "10%",
"tax_rate_id": "d0a5e10a-0000-4000-8000-000000000118",
"tax_method": "inclusive"
}
]
}'
# Respuesta HTTP 201 — la venta ya quedo facturada (e-CF aceptado por DGII):
# {
# "id": "019f12a3-7c4d-71b2-8d3e-aaaaaaaaaaaa",
# "reference_no": "VENTA-A1B2C3",
# "cfe_name": "Factura de Consumo Electrónica",
# "serie": "E32",
# "numero": "0000000123",
# "grand_total": 1150,
# "total": 1150,
# "total_tax": 175.42,
# "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_rate_id": "d0a5e10a-0000-4000-8000-000000000118",
"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 DGII: si DGII 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 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: DOP). 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": {
"Id": "7d2e4f6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"CfeId": "32",
"Serie": "E32",
"Numero": "0000000123",
"CfeName": "Factura de Consumo Electrónica",
"FecEmis": "2026-11-18T14:32:10.000Z",
"encf": "E320000000123",
"estado": "Aprobado",
"DataToGeneratePDF": {
"CAE": {
"DNro": "1",
"HNro": "5000",
"CAE_ID": "5b8f0c2e-...",
"FecVenc": "2027-12-31"
},
"URLDGI": "https://ecf.dgii.gov.do/ecf/consultatimbre?RncEmisor=130555555&ENCF=E320000000123&...",
"DocCodSeg": "Ab12Cd"
}
},
"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 e-CF de DGII (31 Crédito Fiscal, 32 Consumo, 33 Nota de Débito, 34 Nota de Crédito, 44 Regímenes Especiales, 45 Gubernamental…) |
billing_response.Serie | Serie y tipo del e-NCF (E + tipo de e-CF) |
billing_response.Numero | Secuencia del e-NCF (10 dígitos) |
billing_response.encf | e-NCF completo (serie + secuencia) |
billing_response.CfeName | Nombre del e-CF (Factura de Crédito Fiscal Electrónica, Factura de Consumo Electrónica…) |
DataToGeneratePDF.CAE | Rango de secuencias e-NCF autorizado por DGII que se usó (desde, hasta y vencimiento) |
DataToGeneratePDF.URLDGI | URL del código QR de DGII para verificar el e-CF |
DataToGeneratePDF.DocCodSeg | Código de seguridad del e-CF (6 caracteres) |
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 e-CF corresponde (Crédito Fiscal o Consumo), qué tasa de ITBIS lleva cada ítem o cómo tratar una operación exenta 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 e-CF (auto-completado desde el RNC si lo enviás) |
razon_social | string | Razón social: es el nombre que va en el e-CF (auto-completado consultando el RNC en DGII; si no lo enviás se usa name) |
nombre_fantasia | string | Nombre comercial |
rut | string | RNC del cliente (9 dígitos) o cédula del comprador (11 dígitos); guiones se quitan. El RNC también se puede enviar como tipo_documento "RNC" + numero_documento. Si ya existe un cliente con ese número, NO se duplica: la API devuelve 200 con { already_exists: true, id, data } y el UUID del existente. |
email | string | Correo electrónico |
phone | string | Teléfono |
address | string | Dirección |
giro | string | Actividad económica |
country | string | Nombre del país (default: país de la empresa) |
codigo_pais | string | Código ISO del país: "DO" para República Dominicana (default: país de la empresa). Para un cliente del exterior, el código de su país. |
city | string | Municipio o ciudad (opcional) |
state | string | Provincia (opcional) |
tipo_documento | string | "RNC" para una empresa o persona con RNC: numero_documento se toma como RNC. La cédula del comprador se envía directamente en rut (11 dígitos). |
numero_documento | string | Número de documento, solo dígitos (si se envían guiones se quitan). |
Al enviar el RNC en `rut`, el endpoint consulta automáticamente a DGII y completa la razón social si viene vacía en el payload. Si ya existe un cliente con ese número (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. Con un cliente con RNC la venta sale como Factura de Crédito Fiscal Electrónica (e-CF 31); sin RNC, como Factura de Consumo Electrónica (e-CF 32).
Ejemplo cURL
# Crear cliente solo con RNC — el sistema completa la razon social
# consultando a DGII 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": "131234567"}'
# Respuesta HTTP 201 (creado):
# {
# "id": "019f12a3-7c4d-71b2-8d3e-4a5b6c7d8e9f",
# "name": "COMERCIAL EJEMPLO SRL",
# "razon_social": "COMERCIAL EJEMPLO SRL",
# "rut": "131234567",
# "country": "DO",
# "codigo_pais": "DO",
# ...
# }
# Respuesta HTTP 200 (el RNC 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": "131234567", ... }
# }
# Crear cliente persona con cedula (comprador identificado):
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",
"rut": "00112345678",
"email": "[email protected]",
"phone": "8095551234",
"address": "Calle El Conde 123, Santo Domingo"
}'
- 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 el RNC) |
razon_social | string | Razón social (auto-completado desde el RNC) |
rut | string | RNC del proveedor — dedup automático: si ya existe, devuelve `{already_exists: true, id, data}` con HTTP 200. |
email | string | Correo electrónico |
phone | string | Teléfono |
address | string | Dirección |
Al enviar el RNC en `rut`, mismo comportamiento que /customers: razón social completada consultando a DGII + dedup por RNC.
Ejemplo cURL
# Crear proveedor por RNC (auto-completa la razon social)
curl -X POST "https://x.facturando.com/x/api/rest-api/suppliers" \
-H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
-H "Content-Type: application/json" \
-d '{"rut": "101987654"}'
# 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 | RNC 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": "MI EMPRESA SRL",
# "rut": "130555555"
# }
# ],
# "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 DGII 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). Con RNC la venta sale como Factura de Crédito Fiscal (e-CF 31); sin RNC, como Factura de Consumo (e-CF 32). Para facturas de consumo de RD$ 250.000 o más el comprador tiene que estar identificado: 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: DOP) |
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": "DOP",
"note": "Venta mostrador",
"pdf_format": "a4",
"items": [
{
"product_id": "019d9c10-a3f1-7012-bc34-58e9aa1f5d40",
"product_code": "PROD-001",
"product_name": "Cafe molido 1 lb",
"quantity": 2,
"unit_price": 350,
"tax_rate_id": "d0a5e10a-0000-4000-8000-000000000118",
"tax_method": "inclusive"
},
{
"product_name": "Servicio de envio",
"quantity": 1,
"unit_price": 500,
"discount": "10%",
"tax_rate_id": "d0a5e10a-0000-4000-8000-000000000118",
"tax_method": "inclusive"
}
]
}'
# Respuesta HTTP 201 — la venta ya quedo facturada (e-CF aceptado por DGII):
# {
# "id": "019f12a3-7c4d-71b2-8d3e-aaaaaaaaaaaa",
# "reference_no": "VENTA-A1B2C3",
# "cfe_name": "Factura de Consumo Electrónica",
# "serie": "E32",
# "numero": "0000000123",
# "grand_total": 1150,
# "total": 1150,
# "total_tax": 175.42,
# "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_rate_id": "d0a5e10a-0000-4000-8000-000000000118",
"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 DGII: si DGII 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 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, e-NCF y fecha (NCF modificado) y la NC descuenta el saldo de esa factura. Se pueden emitir varias NC parciales con la misma venta. Si DGII todavía no aceptó esa venta, responde 422: reintentá más tarde. |
reference | object | Referencia manual a un comprobante que no está en el sistema: { doc_type, serie, numero, date } |
reason | string | Motivo de la nota de crédito (devolución, descuento, bonificación…) |
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 DOP) |
note | string | Nota o comentario del comprobante |
pdf_format | string | ticket o a4 (default: a4) |
En República Dominicana la Nota de Crédito Electrónica (e-CF 34) siempre modifica un e-NCF anterior: usá `reference_sale_id` (o `POST /sales/:id/void` para anularla completa).
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": "Cafe molido 1 lb",
"quantity": 1,
"unit_price": 350,
"tax_rate_id": "d0a5e10a-0000-4000-8000-000000000118",
"tax_method": "inclusive"
}
]
}'
# Respuesta HTTP 201 (la NC ya quedo emitida ante DGII, importes en negativo):
# {
# "id": "019f2b40-1122-7333-9aaa-bbbbbbbbbbbb",
# "reference_no": "NC-00042",
# "cfe_name": "Nota de Crédito Electrónica",
# "serie": "E34",
# "numero": "0000000042",
# "grand_total": -350,
# "pdf_url_a4": "https://x.facturando.com/sale/019f2b40.../pdf/a4"
# }
# 2) ANULAR UNA VENTA COMPLETA — equivale al boton "Anular venta"
# Emite la NC por el total, asocia la factura 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 Crédito Electrónica", "serie": "E34", "numero": "0000000043",
# "grand_total": -1150
# }
# }
# 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 DGII
# 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: DOP, 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 (la moneda principal de tu cuenta es DOP):
# {
# "data": [
# { "id": "...", "code": "DOP", "name": "Peso Dominicano", "symbol": "RD$", ... },
# { "id": "...", "code": "USD", "name": "Dolar Estadounidense", "symbol": "US$", ... }
# ],
# "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: ITBIS 18% (DO)) |
rate | number | Porcentaje del impuesto |
ind_fact_id | string | Indicador de facturación de DGII: 1 = ITBIS 18 %, 2 = ITBIS 16 %, 3 = ITBIS 0 %, 4 = exento |
Ejemplo cURL
curl -X GET "https://x.facturando.com/x/api/rest-api/tax-rates" \
-H "Authorization: Bearer fct_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
# Respuesta para República Dominicana (los IDs son fijos para todas las cuentas):
# {
# "data": [
# { "id": "d0a5e10a-0000-4000-8000-000000000118", "code": "DO ITBIS18", "name": "ITBIS 18% (DO)", "rate": 18, "ind_fact_id": 1 },
# { "id": "d0a5e10a-0000-4000-8000-000000000116", "code": "DO ITBIS16", "name": "ITBIS 16% (DO)", "rate": 16, "ind_fact_id": 2 },
# { "id": "d0a5e10a-0000-4000-8000-000000000100", "code": "DO ITBIS0", "name": "ITBIS 0% (DO)", "rate": 0, "ind_fact_id": 3 },
# { "id": "d0a5e10a-0000-4000-8000-000000000104", "code": "DO EXE", "name": "Exento (DO)", "rate": 0, "ind_fact_id": 4 }
# ],
# "meta": { "total": 4, "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 | DGII rechazó el e-CF: 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 RNC: 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 DGII 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 +1 829 954 8371.
← Volver a la presentación de la API