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 DGII, 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 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

  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 RNC alcanza: se completa desde DGII).
  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 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".

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 DGII.

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 DGII 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": "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.

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: DOP). 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": {
    "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"
}
CampoDescripción
billing_response.CfeIdTipo 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.SerieSerie y tipo del e-NCF (E + tipo de e-CF)
billing_response.NumeroSecuencia del e-NCF (10 dígitos)
billing_response.encfe-NCF completo (serie + secuencia)
billing_response.CfeNameNombre del e-CF (Factura de Crédito Fiscal Electrónica, Factura de Consumo Electrónica…)
DataToGeneratePDF.CAERango de secuencias e-NCF autorizado por DGII que se usó (desde, hasta y vencimiento)
DataToGeneratePDF.URLDGIURL del código QR de DGII para verificar el e-CF
DataToGeneratePDF.DocCodSegCódigo de seguridad del e-CF (6 caracteres)
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 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.

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 e-CF (auto-completado desde el RNC si lo enviás)
razon_socialstringRazó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_fantasiastringNombre comercial
rutstringRNC 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.
emailstringCorreo electrónico
phonestringTeléfono
addressstringDirección
girostringActividad económica
countrystringNombre del país (default: país de la empresa)
codigo_paisstringCó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.
citystringMunicipio o ciudad (opcional)
statestringProvincia (opcional)
tipo_documentostring"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_documentostringNú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

/customers
# 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"
  }'

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 el RNC)
razon_socialstringRazón social (auto-completado desde el RNC)
rutstringRNC del proveedor — dedup automático: si ya existe, devuelve `{already_exists: true, id, data}` con HTTP 200.
emailstringCorreo electrónico
phonestringTeléfono
addressstringDirección
Al enviar el RNC en `rut`, mismo comportamiento que /customers: razón social completada consultando a DGII + dedup por RNC.

Ejemplo cURL

/suppliers
# 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"

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
rutstringRNC 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": "MI EMPRESA SRL",
#       "rut": "130555555"
#     }
#   ],
#   "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 DGII 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). 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_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: DOP)
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": "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.

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, 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.
referenceobjectReferencia manual a un comprobante que no está en el sistema: { doc_type, serie, numero, date }
reasonstringMotivo de la nota de crédito (devolución, descuento, bonificación…)
datestringFecha ISO (default: la de la venta referenciada, o la fecha actual)
currencystringCódigo de moneda ISO (default: el de la venta referenciada, o DOP)
notestringNota o comentario del comprobante
pdf_formatstringticket 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

/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": "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

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: DOP, 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 (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 }
# }

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: ITBIS 18% (DO))
ratenumberPorcentaje del impuesto
ind_fact_idstringIndicador de facturación de DGII: 1 = ITBIS 18 %, 2 = ITBIS 16 %, 3 = ITBIS 0 %, 4 = exento

Ejemplo cURL

/tax-rates
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 }
# }

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
502DGII rechazó el e-CF: 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 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.

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 +1 829 954 8371.

← Volver a la presentación de la API