sales
Crear venta
POST /sales
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.
{
"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. |
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
{
"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
}
}
message.
Consultar venta
GET /sales/{sale_id}
{
"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 }
]
}
}