> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Ventas (DTE)

> Emitir y consultar documentos de venta electrónicos

**Permiso requerido:** `sales`

## Crear venta

```http theme={null}
POST /sales
```

Emite un documento de venta y lo transmite a Hacienda cuando corresponde (facturación electrónica de El Salvador).

<Warning>
  El sistema externo debe **calcular los desgloses fiscales** por línea y los totales del documento. FileXpress no los recalcula: valida y emite con los montos recibidos.
</Warning>

```json theme={null}
{
  "branch_id": "uuid",
  "customer_id": "uuid",
  "document_type": "fc",
  "date": "2026-10-01T10:00:00",
  "observation": "Entrega en bodega central",
  "is_credit": false,
  "credit_days": 0,
  "payment_details": [
    { "code": "01", "payment_method": "Efectivo", "amount": 22.60, "reference": "" }
  ],
  "products": [
    {
      "id": "uuid-del-producto",
      "sku": "PRD-001",
      "name": "Producto A",
      "quantity": 2,
      "price_before_taxes": 10.00,
      "sale_not_suject": 0,
      "sale_exent": 0,
      "sale_taxed": 20.00,
      "subtotal": 20.00,
      "discount": 0,
      "type": "phisical"
    }
  ],
  "totals": {
    "netTotals": 20.00,
    "saleTotalNotSuject": 0,
    "saleTotalExent": 0,
    "saleTotalTax": 20.00,
    "totalTax": 2.60,
    "totalRetein": 0,
    "totalRent": 0,
    "freight": 0,
    "insurance": 0,
    "saleTotalToPayment": 22.60
  }
}
```

### Campos

| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `branch_id` | uuid | Sí | Sucursal emisora. Ver `GET /branches`. |
| `customer_id` | uuid | Sí | Cliente receptor. Ver [Clientes](/docs/api/facturacion/clientes). |
| `document_type` | string | Sí | El Salvador: `fc` (Factura Consumidor Final), `ccf` (Comprobante de Crédito Fiscal), `fex` (Exportación), `nc` (Nota de Crédito), `nd` (Nota de Débito), `nr` (Nota de Remisión). Estados Unidos: `inv` (Invoice), `cm` (Credit Memo), `dm` (Debit Memo). |
| `date` | datetime | No | Fecha y hora de emisión (ISO 8601). Por defecto, el momento de la solicitud. |
| `observation` | string | No | Observaciones del documento. |
| `is_credit` | boolean | No | Venta al crédito. Por defecto `false`. |
| `credit_days` | integer | No | Días de crédito cuando `is_credit` es `true`. |
| `payment_details` | array | Sí | Formas de pago (mínimo 1). |
| `products` | array | Sí | Líneas del documento (mínimo 1). |
| `totals` | object | Sí | Totales del documento. |
| `project_id` | uuid | No | Proyecto al que se asocia la venta. |
| `incoterm_id` | uuid | No | Incoterm (exportaciones). Ver `GET /incoterms`. |
| `related_documents` | array | No | Documentos relacionados (notas de crédito/débito). |

### `payment_details[]`

| Campo | Tipo | Descripción |
| - | - | - |
| `code` | string | Código de la forma de pago (`GET /payment-methods`). Por defecto `01` (efectivo). |
| `payment_method` | string | Nombre de la forma de pago. |
| `amount` | number | Monto pagado con esta forma. |
| `reference` | string | Referencia (número de cheque, autorización de tarjeta, etc.). |

### `products[]`

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | uuid | ID del producto en FileXpress (recomendado para descontar inventario). |
| `sku` | string | Código del producto. |
| `name` | string | Descripción tal como aparece en el documento. |
| `quantity` | number | Cantidad. |
| `price_before_taxes` | number | Precio unitario sin impuestos. |
| `sale_not_suject` | number | Monto no sujeto de la línea. |
| `sale_exent` | number | Monto exento de la línea. |
| `sale_taxed` | number | Monto gravado de la línea. |
| `subtotal` | number | Total de la línea sin impuestos. |
| `discount` | number | Descuento de la línea (monto). |
| `type` | string | `phisical` (bien) o `service` (servicio). |

### `totals`

| Campo | Descripción |
| - | - |
| `netTotals` | Suma de subtotales sin impuestos. |
| `saleTotalNotSuject` | Total no sujeto. |
| `saleTotalExent` | Total exento. |
| `saleTotalTax` | Total gravado (base imponible). |
| `totalTax` | IVA total. |
| `totalRetein` | IVA retenido (0 si no aplica). |
| `totalRent` | Renta retenida (0 si no aplica). |
| `freight` | Flete (exportación). |
| `insurance` | Seguro (exportación). |
| `saleTotalToPayment` | Total a pagar. |

### Respuesta `200`

```json theme={null}
{
  "status": true,
  "message": "Invoice created successfully",
  "data": {
    "sale_id": "uuid",
    "generation_code": "6F1E2D3C-...",
    "control_number": "DTE-01-M001P001-000000000000001",
    "status": "processed",
    "issue_time": "2026-10-01 10:30:00",
    "stamp": "2026A1B2...",
    "total": 22.60
  }
}
```

Si la emisión falla (por ejemplo, un rechazo de Hacienda), se devuelve el error del proceso de emisión con su código HTTP y el campo `message`.

## Consultar venta

```http theme={null}
GET /sales/{sale_id}
```

```json theme={null}
{
  "status": true,
  "data": {
    "sale_id": "uuid",
    "generation_code": "6F1E2D3C-...",
    "control_number": "DTE-01-M001P001-000000000000001",
    "document_type": "fc",
    "status": "processed",
    "issue_time": "2026-10-01 10:30:00",
    "stamp": "2026A1B2...",
    "payment_status": "paid",
    "is_credit": false,
    "customer": { "id": "uuid", "legal_name": "Razón Social S.A. de C.V.", "customer_name": "Nombre Comercial" },
    "totals": { "sale_total": 22.60, "sale_to_payment": 22.60 },
    "products": [
      { "name": "Producto A", "quantity": 2, "individual_price": 10.00, "subtotal": 20.00 }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.