Factura Consumidor Final (DTE 01)

El DTE tipo 01 se utiliza para ventas a personas naturales que no requieren crédito fiscal.

Endpoint

POST /dte/dte01

(Consulta la guía de Endpoints y Entornos para obtener la URL base según el ambiente).

Estructura del Payload (JSON)

La API de FEL System permite enviar la información del receptor de dos maneras diferentes según las necesidades de tu facturación:

Opción A: Estructura Mínima (Recomendada)

Ideal para facturar de manera rápida y ágil. Solo requiere los datos básicos del cliente. Los campos de tipo y número de documento se autocompletan internamente si se omiten.

{
  "receptor": {
    "nombre": "CARLOS HERNANDEZ",
    "numDocumento": "123456789",
    "tipoDocumento": "13",
    "correo": "[email protected]"
  },
  "items": [
    {
      "descripcion": "Corte de cabello",
      "cantidad": 1,
      "precioUnitario": 5.0,
      "montoDescu": 0,
      "tipoImpuesto": "GRAVADO"
    }
  ],
  "condicionOperacion": 1,
  "observaciones": "Pago en ventanilla",
  "testContingencia": false
}

Opción B: Estructura Completa

Ideal si necesitas registrar la dirección física detallada del receptor (departamento, municipio, distrito, complemento), teléfono y otros datos. Cualquier campo no soportado para este DTE (como nrc o nit) no causará error, pero la API los filtrará y omitirá para este DTE de tipo Consumidor Final.

{
  "receptor": {
    "tipoDocumento": "13",
    "numDocumento": "061412345",
    "nombre": "CLIENTE EJEMPLO S.A. DE C.V.",
    "direccion": {
      "departamento": "02",
      "municipio": "14",
      "distrito": "07",
      "complemento": "Calle de pruebas, Colonia Ejemplo, San Salvador"
    },
    "telefono": "60606060",
    "correo": "[email protected]"
  },
  "items": [
    {
      "descripcion": "Corte de cabello",
      "cantidad": 5,
      "precioUnitario": 1.0,
      "montoDescu": 0,
      "tipoImpuesto": "GRAVADO"
    }
  ],
  "condicionOperacion": 1,
  "observaciones": "Pago en ventanilla",
  "testContingencia": false
}

Campos Globales y del Receptor

Campo	Tipo	Requerido	Descripción
`receptor`	object	Sí	Datos del cliente (nombre, documento, correo).
`condicionOperacion`	number	Sí	Condición de la venta: `1` (Contado), `2` (Crédito), `3` (Otro). Ver Condición de Operación y Métodos de Pago.
`pago`	object	Según aplique	Requerido si `condicionOperacion` es `2` o `3`. Especifica el método y condiciones de pago.
`observaciones`	string	No	Comentarios adicionales en el documento.
`testContingencia`	boolean	No	`true` para simular una falla de transmisión (solo pruebas).

Campos de Items

Campo	Tipo	Requerido	Descripción
`cantidad`	number	Sí	Cantidad del producto/servicio.
`precioUnitario`	number	Sí	Precio unitario CON IVA incluido.
`descripcion`	string	Sí	Detalle del item.
`uniMedida`	number	No	Código de unidad de medida (default: 59 - Unidad).

Condición de Operación y Métodos de Pago

El campo condicionOperacion define la forma en que se realiza la venta y determina cómo debe enviarse la información de pago.

Valor	Descripción
`1`	Contado
`2`	Crédito
`3`	Otro

Venta al Contado (condicionOperacion = 1)

Para operaciones al contado no es necesario enviar información adicional de pago. El sistema registrará automáticamente el pago en efectivo (01).

{
  "condicionOperacion": 1
}

Venta al Crédito (condicionOperacion = 2)

Para operaciones al crédito debe enviarse el objeto pago, indicando el método de pago y las condiciones pactadas.

{
  "condicionOperacion": 2,
  "pago": {
    "codigo": "04",
    "plazo": "01",
    "periodo": 30,
    "referencia": "CR-0001"
  }
}

Otra Condición de Operación (condicionOperacion = 3)

Cuando la operación corresponda a una modalidad distinta de contado o crédito, debe enviarse el objeto pago especificando el método utilizado y las condiciones de plazo si aplican.

{
  "condicionOperacion": 3,
  "pago": {
    "codigo": "02",
    "plazo": "01",
    "periodo": 30,
    "referencia": "POS-0001"
  }
}

Objeto Pago

Campo	Tipo	Requerido	Descripción
`codigo`	string	Sí	Código del método de pago.
`plazo`	string	Según aplique	Código del plazo otorgado para operaciones a crédito u otras modalidades.
`periodo`	number	Según aplique	Cantidad de períodos otorgados para la operación.
`referencia`	string	No	Referencia interna de la operación o pago.

Métodos de Pago Comunes

Código	Método
`01`	Efectivo
`02`	Tarjeta
`03`	Cheque
`04`	Transferencia bancaria
`05`	Depósito en cuenta

[!NOTE] Los códigos válidos para métodos de pago, plazos y períodos están sujetos a los catálogos oficiales publicados por el Ministerio de Hacienda. El envío de valores no permitidos provocará el rechazo del DTE.

Respuestas de la API

El endpoint retorna el detalle completo del documento creado en base de datos junto con la respuesta de firma y el resultado directo del Ministerio de Hacienda.

Respuesta Exitosa (201 Created)

Se retorna cuando el documento es firmado correctamente y aceptado por el Ministerio de Hacienda (estado: "PROCESSED").

{
  "status": "success",
  "data": {
    "id": 999,
    "tipo": "FACTURA_CONSUMIDOR_FINAL",
    "codigoGeneracion": "B25B43FD-C114-4B36-8C12-27DE364E2999",
    "numeroControl": "DTE-01-S001P003-000000000000003",
    "estado": "PROCESSED",
    "ambiente": "TEST",
    "total": "5",
    "dteJson": {
      // ... (Estructura interna del DTE firmado enviado a Hacienda)
    },
    "dteFirmado": "eyJhbGciOiJSUzUxMiJ9.eyJpZGVudGlmaWNhY2lvbiI6ey...",
    "selloRecibido": "20264E6FE10D7DB4441FA9FCCEA005F2077D5VEQ",
    "respuestaMh": {
      "estado": "PROCESSED",
      "version": 2,
      "ambiente": "00",
      "codigoMsg": "001",
      "versionApp": 2,
      "clasificaMsg": "10",
      "observaciones": [],
      "selloRecibido": "20264E6FE10D7DB4441FA9FCCEA005F2077D5VEQ",
      "descripcionMsg": "RECIBIDO",
      "fhProcesamiento": "08/06/2026 22:34:57",
      "codigoGeneracion": "B25B43FD-C114-4B36-8C12-27DE364E2999"
    },
    "dteJsonUrl": "emisores/empresa-pruebas/DTES/TEST/2026/06/08/DTE01/json/B25B43FD-C114-4B36-8C12-27DE364E2999.json",
    "dtePdfUrl": "emisores/empresa-pruebas/DTES/TEST/2026/06/08/DTE01/pdf/B25B43FD-C114-4B36-8C12-27DE364E2999.pdf",
    "sequenceNumber": "3",
    "sequenceId": 53,
    "serie": "P003",
    "emisorId": 1,
    "branchId": 1,
    "pointOfSaleId": 8,
    "tokenId": 21,
    "errorTecnico": null,
    "createdAt": "2026-06-08T22:34:57.000Z",
    "analisisHacienda": {
      "estadoDocumento": "PROCESSED",
      "aceptadoPorMH": true,
      "tieneObservaciones": false,
      "observaciones": [],
      "erroresValidacion": [],
      "mensaje": "Documento procesado exitosamente"
    }
  }
}

Respuesta de Error / Rechazo (201 Created con estado REJECTED)

Se retorna si el DTE es firmado correctamente pero es rechazado por Hacienda debido a un fallo en las reglas de validación (por ejemplo, enviar un código de distrito no permitido).

{
  "status": "success",
  "data": {
    "id": 1000,
    "tipo": "FACTURA_CONSUMIDOR_FINAL",
    "codigoGeneracion": "13927AC8-37ED-4CFE-A80C-F3466151AFFA",
    "numeroControl": "DTE-01-S001P003-000000000000004",
    "estado": "REJECTED",
    "ambiente": "TEST",
    "total": "5",
    "dteJson": {
      // ... (Estructura interna del DTE firmado enviado a Hacienda)
    },
    "dteFirmado": "eyJhbGciOiJSUzUxMiJ9.eyJpZGVudGlmaWNhY2lvbiI6ey...",
    "selloRecibido": null,
    "respuestaMh": {
      "estado": "RECHAZADO",
      "version": 2,
      "ambiente": "00",
      "codigoMsg": "007",
      "versionApp": 2,
      "clasificaMsg": "13",
      "observaciones": [],
      "selloRecibido": null,
      "descripcionMsg": "[receptor.direccion.distrito] VALOR NO ES PERMITIDO",
      "fhProcesamiento": "08/06/2026 22:37:11",
      "codigoGeneracion": "13927AC8-37ED-4CFE-A80C-F3466151AFFA"
    },
    "dteJsonUrl": null,
    "dtePdfUrl": null,
    "sequenceNumber": "4",
    "sequenceId": 53,
    "serie": "P003",
    "emisorId": 1,
    "branchId": 1,
    "pointOfSaleId": 8,
    "tokenId": 21,
    "errorTecnico": "Rechazado por Hacienda: Documento rechazado: [receptor.direccion.distrito] VALOR NO ES PERMITIDO",
    "createdAt": "2026-06-08T22:37:11.000Z",
    "analisisHacienda": {
      "estadoDocumento": "REJECTED",
      "aceptadoPorMH": false,
      "tieneObservaciones": false,
      "observaciones": [],
      "erroresValidacion": [
        "Documento rechazado: [receptor.direccion.distrito] VALOR NO ES PERMITIDO"
      ],
      "mensaje": "Documento rechazado: [receptor.direccion.distrito] VALOR NO ES PERMITIDO"
    }
  }
}