---
title: "Crear nueva factura"
method: POST
path: "/invoices"
tags: ["Facturas"]
---

# Crear nueva factura

`POST /invoices`

## Request

- Base URL: `https://api.pirpos.com`
- URL: `https://api.pirpos.com/invoices`
- Auth: HTTP bearer

Crea una nueva factura a partir de pedidos existentes u órdenes específicas.

**Autenticación requerida:** Este endpoint requiere autenticación Bearer Token.
Usar el campo `tokenCurrent` obtenido del servicio de login (/login) en el header:
`Authorization: Bearer {tokenCurrent}`

**Proceso de facturación:**
- Convierte pedidos en factura oficial
- Calcula impuestos y totales automáticamente
- Soporta facturación electrónica (DIAN)
- Integra con sistemas contables (Siigo, Loggro)
- Actualiza inventario y caja registradora

**Requisitos de caja:** Requiere caja registradora activa para el usuario.

## Descuentos

Una factura puede combinar **tres tipos de descuento**, que se aplican en este orden sobre cada línea:

1. **Descuento de promoción (por producto, monto fijo):** proviene del objeto `promo` del pedido/producto (`promo.discount`). Se **resta** del subtotal de la línea (`cantidad × precio − promo.discount`).
2. **Descuento de línea (por producto, porcentaje):** porcentaje configurado en el producto/pedido.
3. **Descuento adicional de factura (porcentaje):** el campo `discount` del cuerpo de la petición, que aplica a **toda** la factura.

Los porcentajes de línea y de factura se **suman** y se aplican sobre el subtotal ya rebajado por la promoción. El **impuesto se calcula después** de todos los descuentos. Resultados:
- `discountAdditional`: porcentaje adicional almacenado (igual al `discount` enviado).
- `discountAdditionalTotal`: monto total descontado, **calculado por el servidor**.
- `products[].totalDiscount`: descuento calculado por línea; `products[].subTotal`/`subTotal`: base ya rebajada.

> **Nota:** no existe un límite máximo de descuento ni una validación de permiso específica para aplicar descuentos; el control queda a cargo del cliente que consume la API.

## Casos de Uso y Ejemplos

### Caso de Uso: Facturar mesa de restaurante
**Escenario:** Un mesero ha tomado varios pedidos en una mesa y necesita generar la factura final.

**Proceso:**
1. Los pedidos se han creado previamente con estado "Espera" o "Entregado"
2. Se seleccionan todos los pedidos de la mesa para facturar
3. Se especifica método de pago y cliente (opcional)
4. Se genera factura con cálculo automático de impuestos

### 1. Factura básica de mesa
```json
{
  "_id": "507f1f77bcf86cd799439020",
  "orderProducts": [
    { "order": "507f1f77bcf86cd799439011" },
    { "order": "507f1f77bcf86cd799439012" }
  ],
  "table": "507f1f77bcf86cd799439014",
  "client": {
    "name": "Juan Pérez",
    "phone": "+57 300 123 4567",
    "email": "juan@email.com"
  },
  "paymentMethod": "507f1f77bcf86cd799439018",
  "isPaid": true,
  "total": 45000,
  "discountAdditionalTotal": 5000
}
```

### 2. Factura electrónica con DIAN
```json
{
  "_id": "507f1f77bcf86cd799439021",
  "isEInvoice": true,
  "orderProducts": [
    { "order": "507f1f77bcf86cd799439013" }
  ],
  "client": {
    "name": "María González",
    "idType": "CC",
    "idNumber": "123456789",
    "email": "maria@empresa.com"
  },
  "isPaid": true,
  "total": 30000,
  "sendInvoiceEmail": true
}
```

### 3. Factura a crédito
```json
{
  "_id": "507f1f77bcf86cd799439022",
  "orderProducts": [
    { "order": "507f1f77bcf86cd799439014" },
    { "order": "507f1f77bcf86cd799439015" }
  ],
  "client": {
    "name": "Empresa ABC",
    "idType": "NIT",
    "idNumber": "900123456-1"
  },
  "isCredit": true,
  "creditDays": 30,
  "total": 75000,
  "status": "Pendiente"
}
```

### 4. Factura con entrega a domicilio
```json
{
  "_id": "507f1f77bcf86cd799439023",
  "orderProducts": [
    { "order": "507f1f77bcf86cd799439016" }
  ],
  "delivery": {
    "isDelivery": true,
    "deliveryProvider": "507f1f77bcf86cd799439017",
    "deliveryGuy": {
      "internalId": "507f1f77bcf86cd799439025"
    },
    "address": "Calle 123 #45-67, Bogotá"
  },
  "deliveryCost": 8000,
  "isPaid": true,
  "total": 38000
}
```

## Request body

- object
  - `_id` string, required: ID único de la factura (generado por el cliente)
  - `orderProducts` object[], required: Lista de pedidos a incluir en la factura
    - `order` string, required: ID del pedido
  - `table` string: ID de la mesa (para facturas de mesa)
  - `client` object: Información del cliente
    - `name` string: Nombre del cliente
    - `phone` string: Teléfono del cliente
    - `email` string: Email del cliente
    - `idType` 'CC' | 'CE' | 'NIT' | 'PAS': Tipo de identificación
    - `idNumber` string: Número de identificación
  - `paymentMethod` string: ID del método de pago
  - `isPaid` boolean: Si la factura está pagada
  - `isCredit` boolean: Si la factura es a crédito
  - `creditDays` number: Días de crédito (solo si isCredit es true)
  - `total` number, required: Total de la factura
  - `discount` number: Descuento adicional en porcentaje (0-100) aplicado a toda la factura. Se almacena en discountAdditional y se aplica a cada línea sobre su subtotal (después del descuento de promoción del ítem y antes de impuestos). Es el principal campo de entrada para aplicar un descuento al facturar. Ver la sección "Descuentos" en la descripción.
  - `discountAdditionalTotal` number: Monto total de descuento adicional. Calculado por el servidor a partir de discount y los descuentos de línea; el valor enviado por el cliente es recalculado.
  - `status` 'Facturada' | 'Pagada' | 'Pendiente' | 'Anulada': Estado de la factura
  - `isEInvoice` boolean: Si es factura electrónica (DIAN)
  - `sendInvoiceEmail` boolean: Enviar factura por email al cliente
  - `delivery` object: Información de entrega a domicilio
    - `isDelivery` boolean: Si incluye entrega
    - `deliveryProvider` string: ID del proveedor de entrega
    - `deliveryGuy` object
      - `internalId` string: ID del repartidor
    - `address` string: Dirección de entrega
  - `deliveryCost` number: Costo de entrega

## Response `200`

Factura creada exitosamente

- Invoice
  - `_id` string: ID único de la factura
  - `businessId` string: ID del negocio al que pertenece la factura
  - `business` object: Información del negocio
    - `name` string: Nombre del negocio
    - `nit` string: NIT del negocio
    - `address` string: Dirección del negocio
  - `number` string: Número de la factura
  - `invoicePrefix` string: Prefijo de la factura
  - `seq` number: Número secuencial de la factura
  - `products` object[]: Lista de productos en la factura
    - `idInternal` string: ID del producto
    - `name` string: Nombre del producto
    - `quantity` number: Cantidad
    - `price` number: Precio unitario
  - `total` number: Total de la factura
  - `totalPaid` number: Total pagado
  - `status` 'Pendiente' | 'Pagada' | 'Anulada': Estado de la factura
  - `type` 'Normal' | 'FacturaElectronica': Tipo de factura
  - `table` object: Información de la mesa
    - `idInternal` string: ID de la mesa
    - `name` string: Nombre de la mesa
  - `client` object: Información del cliente
    - `idInternal` string: ID del cliente
    - `name` string: Nombre del cliente
    - `phone` string: Teléfono del cliente
  - `cashier` object: Información del cajero
    - `idInternal` string: ID del cajero
    - `name` string: Nombre del cajero
  - `paid` object: Información de pago
    - `paymentMethodValue` object
      - `paymentMethod` string: Método de pago utilizado
  - `delivery` object: Información de entrega
    - `isDelivery` boolean: Si es una entrega a domicilio
    - `deliveryProvider` string: Proveedor de entrega
    - `deliveryGuy` object
      - `internalId` string: ID del repartidor
      - `name` string: Nombre del repartidor
  - `deliveryCost` number: Costo de entrega
  - `eInvoice` object: Información de facturación electrónica
    - `DIAN` object
      - `dianState` string: Estado en DIAN
  - `externalIntegration` object: Integraciones externas
    - `siigo` object
      - `statusCode` number: Código de estado en Siigo
    - `loggro` object
      - `statusCode` number: Código de estado en Loggro
  - `credit` object: Información de crédito
    - `dueDate` string, date-time: Fecha de vencimiento del crédito
  - `createdOn` string, date-time: Fecha de creación
  - `modifiedOn` string, date-time: Fecha de última modificación
  - `deletedInfo` object: Información de eliminación
    - `isDeleted` boolean: Si la factura está eliminada

## Other responses

- `400`: Datos de entrada inválidos o errores de configuración
- `401`: No autorizado o sin caja registradora activa
- `403`: Sin permisos para crear facturas
- `500`: Error interno del servidor

---

[API](https://skmtc.dev/loggro/apis/restobar-servicios-del-m-dulo-de-restobar.md) - [All operations](https://skmtc.dev/loggro/apis/restobar-servicios-del-m-dulo-de-restobar/llms.txt) - [OpenAPI document](https://skmtc.dev/loggro/apis/restobar-servicios-del-m-dulo-de-restobar/revisions/9d4431a3cddc?raw)