Comprobante de Crédito Fiscal (DTE 03)

El DTE tipo 03 se utiliza para transacciones entre contribuyentes del IVA.

Endpoint

POST /dte/dte03

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

Estructura del Payload (JSON)

{
  "receptor": {
    "tipoDocumento": "13",
    "numDocumento": "01234567891011",
    "nit": "06141234561013",
    "nrc": "1234567",
    "nombre": "CLIENTE DE PRUEBA S.A. DE C.V.",
    "codActividad": "49226",
    "descActividad": "Servicios de transporte de personal",
    "nombreComercial": null,
    "direccion": {
      "departamento": "02",
      "municipio": "14",
      "distrito": "07",
      "complemento": "Calle de pruebas, Colonia Ejemplo, San Salvador"
    },
    "telefono": null,
    "correo": "[email protected]"
  },
  "items": [
    {
      "descripcion": "Pasta de ajo",
      "cantidad": 2,
      "codigo": "AB1",
      "precioUnitario": 20.0,
      "montoDescu": 0,
      "tipoImpuesto": "GRAVADO",
      "uniMedida": 99,
      "tipoItem": 1
    }
  ],
  "condicionOperacion": 1,
  "observaciones": "Pago en ventanilla",
  "isRetenIva": false
}

Campos Específicos de Crédito Fiscal

Campo	Tipo	Requerido	Descripción
isRetenIva	boolean	No	Indica si se debe aplicar la retención del 1% de IVA (solo si aplica).
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.

Retención del 1% de IVA (isRetenIva)

El campo isRetenIva controla si al Comprobante de Crédito Fiscal (DTE-03) debe aplicarse la retención del 1% de IVA.

¿Cuándo debe enviarse como true?

Debe establecerse en true cuando el receptor de la operación sea un agente de retención autorizado por el Ministerio de Hacienda y corresponda efectuar la retención del 1% del IVA conforme a la normativa tributaria vigente.

Ejemplo:

{
  "isRetenIva": true
}

¿Cuándo debe enviarse como false?

Debe establecerse en false o omitirse cuando la operación no esté sujeta a retención del 1% de IVA.

Ejemplo:

{
  "isRetenIva": false
}

Efecto sobre el DTE

Cuando isRetenIva es true, el sistema debe calcular y registrar la retención correspondiente en el campo ivaRete del resumen del Comprobante de Crédito Fiscal (DTE-03).

Ejemplo:

{
  "resumen": {
    "totalGravada": 100.0,
    "ivaRete": 1.0,
    "totalPagar": 99.0
  }
}

Consideraciones

• Aplica únicamente para Comprobantes de Crédito Fiscal (DTE-03).
• No todas las empresas están obligadas a practicar esta retención.
• La aplicación de la retención depende de la calidad tributaria del receptor y de las condiciones establecidas por la Administración Tributaria.
• Si no existe obligación de retener, el valor debe mantenerse en false o no enviarse.

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.

Validación de Receptor

La API retornará un error 400 (RECEPTOR_VALIDATION_ERROR) si faltan campos obligatorios para el crédito fiscal.

{
  "status": "error",
  "message": "Datos del receptor incompletos",
  "requiredFields": ["tipoDocumento", "numDocumento", "nit", "nombre"]
}

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": 988,
    "tipo": "CREDITO_FISCAL",
    "codigoGeneracion": "0A55AE8E-F6D9-49E9-A9E5-072F0F43EEA0",
    "numeroControl": "DTE-03-S001P003-000000000000005",
    "estado": "PROCESSED",
    "ambiente": "TEST",
    "total": "40",
    "dteJson": {
      // ... (Estructura interna del DTE firmado enviado a Hacienda)
    },
    "dteFirmado": "eyJhbGciOiJSUzUxMiJ9.eyJpZGVudGlmaWNhY2lvbiI6ey...",
    "selloRecibido": "20263E159ACDDCE3403AAC689D02699962D60QMT",
    "respuestaMh": {
      "estado": "PROCESSED",
      "version": 2,
      "ambiente": "00",
      "codigoMsg": "001",
      "versionApp": 2,
      "clasificaMsg": "10",
      "observaciones": [],
      "selloRecibido": "20263E159ACDDCE3403AAC689D02699962D60QMT",
      "descripcionMsg": "RECIBIDO",
      "fhProcesamiento": "08/06/2026 22:43:53",
      "codigoGeneracion": "0A55AE8E-F6D9-49E9-A9E5-072F0F43EEA0"
    },
    "dteJsonUrl": "emisores/empresa-pruebas/DTES/TEST/2026/06/08/DTE03/json/0A55AE8E-F6D9-49E9-A9E5-072F0F43EEA0.json",
    "dtePdfUrl": "emisores/empresa-pruebas/DTES/TEST/2026/06/08/DTE03/pdf/0A55AE8E-F6D9-49E9-A9E5-072F0F43EEA0.pdf",
    "sequenceNumber": "5",
    "sequenceId": 39,
    "serie": "P003",
    "emisorId": 1,
    "branchId": 1,
    "pointOfSaleId": 8,
    "tokenId": 21,
    "errorTecnico": null,
    "createdAt": "2026-06-08T22:43:53.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 actividad inválido).

{
  "status": "success",
  "data": {
    "id": 989,
    "tipo": "CREDITO_FISCAL",
    "codigoGeneracion": "A93CBCD6-803D-47FE-A06C-5D61ED4F153D",
    "numeroControl": "DTE-03-S001P003-000000000000006",
    "estado": "REJECTED",
    "ambiente": "TEST",
    "total": "40",
    "dteJson": {
      // ... (Estructura interna del DTE firmado enviado a Hacienda)
    },
    "dteFirmado": "eyJhbGciOiJSUzUxMiJ9.eyJpZGVudGlmaWNhY2lvbiI6ey...",
    "selloRecibido": null,
    "respuestaMh": {
      "estado": "RECHAZADO",
      "version": 2,
      "ambiente": "00",
      "codigoMsg": "096",
      "versionApp": 2,
      "clasificaMsg": "98",
      "observaciones": [
        "Campo #/receptor/codActividad no cumple el tamaño mínimo permitido",
        "Campo #/receptor/codActividad no cumple el formato requerido"
      ],
      "selloRecibido": null,
      "descripcionMsg": "DOCUMENTO NO CUMPLE CON NORMATIVA DE CUMPLIMIENTO",
      "fhProcesamiento": "08/06/2026 22:44:32",
      "codigoGeneracion": "A93CBCD6-803D-47FE-A06C-5D61ED4F153D"
    },
    "dteJsonUrl": null,
    "dtePdfUrl": null,
    "sequenceNumber": "6",
    "sequenceId": 39,
    "serie": "P003",
    "emisorId": 1,
    "branchId": 1,
    "pointOfSaleId": 8,
    "tokenId": 21,
    "errorTecnico": "Rechazado por Hacienda: Documento rechazado: DOCUMENTO NO CUMPLE CON NORMATIVA DE CUMPLIMIENTO",
    "createdAt": "2026-06-08T22:44:31.000Z",
    "analisisHacienda": {
      "estadoDocumento": "REJECTED",
      "aceptadoPorMH": false,
      "tieneObservaciones": true,
      "observaciones": [
        "Campo #/receptor/codActividad no cumple el tamaño mínimo permitido",
        "Campo #/receptor/codActividad no cumple el formato requerido"
      ],
      "erroresValidacion": [
        "Documento rechazado: DOCUMENTO NO CUMPLE CON NORMATIVA DE CUMPLIMIENTO"
      ],
      "mensaje": "Documento rechazado: DOCUMENTO NO CUMPLE CON NORMATIVA DE CUMPLIMIENTO"
    }
  }
}