API Facturación

Comprobante de Crédito Fiscal (CCF)

Esta sección describe cómo emitir y gestionar Comprobantes de Crédito Fiscal (CCF) mediante la API.

Autenticación

Todos los endpoints requieren autenticación JWT. Consulta la sección de Autenticación para más detalles.

Catálogos de referencia

Para la correcta emisión de créditos fiscales, debes utilizar los códigos de los catálogos oficiales. Consulta la sección de Catálogos para todos los valores permitidos.

Crear Comprobante de Crédito Fiscal

POST /api/v1/dte/ccf

Crea y emite un Comprobante de Crédito Fiscal

Este endpoint permite crear y emitir un Comprobante de Crédito Fiscal (CCF) electrónico.

Ejemplo de Solicitud

Request 

{
  "items": [
    {
      "type": 1,
      "description": "Venta gravada",
      "quantity": 1,
      "unit_measure": 59,
      "unit_price": 2000.00,
      "taxed_sale": 2000.00,
      "exempt_sale": 0,
      "non_subject_sale": 0,
      "taxes": [
        "20"
      ]
    }
  ],
  "receiver": {
    "nrc": "0000",
    "nit": "00000000000000",
    "name": "CLIENTE DE PRUEBA",
    "commercial_name": "EJEMPLO S.A de S.V",
    "activity_code": "00000",
    "activity_description": "ACTIVIDAD ECONOMICA DE EJEMPLO",
    "address": {
      "department": "06",
      "municipality": "22",
      "complement": "Dirección de Prueba 1, N° 1234"
    },
    "phone": "21212828",
    "email": "cliente@gmail.com"
  },
  "summary": {
    "operation_condition": 1,
    "total_taxed": 2000.00,
    "total_exempt": 0,
    "total_non_taxed": 0,
    "total_non_subject": 0,
    "sub_total_sales": 2000.00,
    "sub_total": 2000.00,
    "iva_perception": 0,
    "iva_retention": 0,
    "income_retention": 0,
    "total_operation": 2260.00,
    "total_to_pay": 2260.00,
    "taxes": [
      {
        "code": "20",
        "description": "IVA 13%",
        "value": 260.00
      }
    ],
    "payment_types": [
      {
        "code": "01",
        "amount": 2260.00
      }
    ]
  },

  // Nota, estos campos si NO seran ocupados, no es necesario enviarlos, los muestra acá unicamente como referencia
  "third_party_sale": null,
  "related_docs": null,
  "other_docs": null,
  "appendixes": null
}

Ejemplo de Respuesta

Response 

{
  "success": true,
  "reception_stamp": "202533D8A3CB39484D...",
  "qr_link": "https://admin.factura.gob.sv/consultaPublica?ambiente=00&codGen=UUID-GENERADO&fechaEmi=FECHA-EMISION",
  "data": {
    "identificacion": {
      "version": 3,
      "ambiente": "00",
      "tipoDte": "03",
      "numeroControl": "DTE-03-C0020000-000000000000001",
      "codigoGeneracion": "96B3D5DD-EE92-4...",
      "tipoModelo": 1,
      "tipoOperacion": 1,
      "tipoContingencia": null,
      "motivoContin": null,
      "fecEmi": "2025-04-12",
      "horEmi": "19:38:32",
      "tipoMoneda": "USD"
    },
    "emisor": {
      "nit": "00000000000000",
      "nrc": "0000000",
      "nombre": "EMPRESA DE PRUEBAS SA DE CV 2",
      "codActividad": "00000",
      "descActividad": "Venta al por mayor de otros productos",
      "tipoEstablecimiento": "01",
      "direccion": {
        "departamento": "06",
        "municipio": "20",
        "complemento": "BOULEVARD SANTA ELENA SUR, SANTA TECLA"
      },
      "telefono": "21212121",
      "correo": "facturacion@empresa.com.sv",
      "nombreComercial": "EJEMPLO",
      "codEstableMH": null,
      "codEstable": "C002",
      "codPuntoVentaMH": null,
      "codPuntoVenta": null
    },
    "receptor": {
      "nombre": "CLIENTE DE PRUEBA",
      "nrc": "0000",
      "nit": "00000000000000",
      "codActividad": "00000",
      "descActividad": "ACTIVIDAD ECONOMICA DE EJEMPLO",
      "direccion": {
        "departamento": "06",
        "municipio": "22",
        "complemento": "Dirección de Prueba 1, N° 1234"
      },
      "telefono": "21212828",
      "correo": "cliente@gmail.com",
      "nombreComercial": "EJEMPLO S.A de S.V"
    },
    "cuerpoDocumento": [
      {
        "numItem": 1,
        "tipoItem": 1,
        "numeroDocumento": null,
        "codigo": null,
        "codTributo": null,
        "descripcion": "Venta gravada",
        "cantidad": 1,
        "uniMedida": 59,
        "precioUni": 2000,
        "montoDescu": 0,
        "ventaNoSuj": 0,
        "ventaExenta": 0,
        "ventaGravada": 2000,
        "tributos": [
          "20"
        ],
        "psv": 0,
        "noGravado": 0
      }
    ],
    "resumen": {
      "totalNoSuj": 0,
      "totalExenta": 0,
      "totalGravada": 2000,
      "subTotalVentas": 2000,
      "descuNoSuj": 0,
      "descuExenta": 0,
      "descuGravada": 0,
      "porcentajeDescuento": 0,
      "totalDescu": 0,
      "tributos": [
        {
          "codigo": "20",
          "descripcion": "IVA 13%",
          "valor": 260
        }
      ],
      "subTotal": 2000,
      "ivaRete1": 0,
      "ivaPerci1": 0,
      "reteRenta": 0,
      "montoTotalOperacion": 2260,
      "totalNoGravado": 0,
      "totalPagar": 2260,
      "totalLetras": "DOS MIL DOSCIENTOS SESENTA 00/100",
      "saldoFavor": 0,
      "condicionOperacion": 1,
      "pagos": [
        {
          "codigo": "01",
          "montoPago": 2260,
          "referencia": null,
          "plazo": null,
          "periodo": null
        }
      ],
      "numPagoElectronico": null
    },
    "documentoRelacionado": null,
    "otrosDocumentos": null,
    "ventaTercero": null,
    "extension": null,
    "apendice": [
      {
        "campo": "Datos del documento",
        "etiqueta": "Sello de recepción",
        "valor": "202533D8A3CB39484D..."
      }
    ]
  }
}

Campos principales

Campos necesarios para crear un CCF

items

Requerido
array
Lista de productos o servicios

items[].type

Requerido
number
Tipo de ítem (1: Producto, 2: Servicio, 3: Ambos, 4: Impuesto)

items[].description

Requerido
string
Descripción del producto o servicio (1-1000 caracteres)

items[].quantity

Requerido
number
Cantidad (> 0)

items[].unit_measure

Requerido
number
Unidad de medida (1-99)

items[].unit_price

Requerido
number
Precio unitario (≥ 0)

items[].discount

Opcional
number
Descuento (≥ 0)

items[].code

Opcional
string
Código del producto (1-25 caracteres)

items[].non_subject_sale

Requerido
number
Venta no sujeta (≥ 0)

items[].exempt_sale

Requerido
number
Venta exenta (≥ 0)

items[].taxed_sale

Requerido
number
Venta gravada (≥ 0)

items[].suggested_price

Opcional
number
Precio sugerido (≥ 0)

items[].non_taxed

Opcional
number
Monto no gravado (≥ 0)

items[].iva_item

Opcional
number
IVA del ítem

receiver

Requerido
object
Información del receptor

receiver.nrc

Requerido
string
Número de registro fiscal del receptor

receiver.nit

Requerido
string
NIT del receptor

receiver.name

Requerido
string
Nombre completo o razón social del receptor

receiver.activity_code

Requerido
string
Código de actividad económica

receiver.activity_description

Requerido
string
Descripción de actividad económica

receiver.commercial_name

Requerido
string
Nombre comercial del receptor

receiver.address

Requerido
object
Dirección del receptor

receiver.address.department

Requerido
string
Código del departamento

receiver.address.municipality

Requerido
string
Código del municipio

receiver.address.complement

Requerido
string
Dirección completa

receiver.phone

Requerido
string
Teléfono del receptor

receiver.email

Requerido
string
Correo electrónico del receptor

summary

Requerido
object
Resumen de totales

summary.total_non_subject

Requerido
number
Total ventas no sujetas

summary.total_exempt

Requerido
number
Total ventas exentas

summary.total_taxed

Requerido
number
Total ventas gravadas

summary.sub_total

Requerido
number
Subtotal

summary.total_discount

Opcional
number
Total descuentos

summary.sub_total_sales

Requerido
number
Subtotal de ventas

summary.total_operation

Requerido
number
Total operación

summary.total_to_pay

Requerido
number
Total a pagar

summary.operation_condition

Requerido
number
Condición de operación (1: Contado, 2: Crédito, 3: Otro)

summary.iva_retention

Opcional
number
IVA retenido

summary.total_iva

Opcional
number
Total IVA

summary.payment_types

Requerido
array
Tipos de pago

summary.payment_types[].code

Requerido
string
Código forma de pago

summary.payment_types[].amount

Requerido
number
Monto

summary.payment_types[].term

Opcional
string
Plazo (requerido para crédito)

summary.payment_types[].period

Opcional
number
Período
Sí Indica campo obligatorio

Validaciones específicas para CCF

  • El receptor es OBLIGATORIO y debe incluir NRC, NIT, código de actividad, descripción de actividad y nombre comercial
  • Para ítems tipo 4 (impuesto), la unidad de medida debe ser 99
  • Solo se permite impuesto IVA (código "20") para ítems tipo 4
  • Si hay documentos relacionados, cada ítem debe tener un documento relacionado válido
  • El cálculo de IVA debe ser exactamente 13% sobre (venta gravada - descuento gravado)
  • La suma de todos los tipos de pago debe ser igual al total a pagar
  • Los descuentos no pueden superar el subtotal
  • Si la condición de operación es crédito, los campos term y period son obligatorios

Diferencias entre CCF y Factura

  • Para CCF, los items con taxed_sale > 0 y type = 1 deben incluir impuestos con código "20" (IVA 13%)
  • No se permite mezclar ventas gravadas y no gravadas en un mismo ítem
  • El receptor es obligatorio y debe incluir información completa del contribuyente

Campos Opcionales

Estos campos complementan la información principal de la factura electrónica, permitiendo casos de uso más específicos.

1. Appendixes (Apéndices)

Los apéndices son campos adicionales que proporcionan información complementaria al documento principal.

Estructura de Apéndices 

"appendixes": [
    {
      "field": "string",
      "label": "string",
      "value": "string"
    },
]

Campos de Apéndices

Validaciones para el objeto appendixes

field

Requerido
string
Nombre del campo adicional (2-25 caracteres)

label

Requerido
string
Etiqueta o título del campo (3-50 caracteres)

value

Requerido
string
Valor del campo (1-150 caracteres)
Sí Indica campo obligatorio

Consideraciones importantes:

  • Los apéndices son opcionales en la factura electrónica.
  • Si se incluyen, todos los campos son obligatorios.
  • El sistema puede agregar automáticamente un apéndice conteniendo el "sello de recepción".

2. Extension (Extensión)

La extensión contiene información sobre entrega y recepción de bienes o servicios.

Ejemplo de extensión requerida 

{
  "extension": {
    "delivery_name": "string",
    "delivery_document": "string",
    "receiver_name": "string",
    "receiver_document": "string",
    "observation": "string"
    "vehicule_plate": "string"
  }
}

Campos de Extensión

Validaciones para el objeto extension

delivery_name

Requerido
string
Nombre de quien entrega (1-100 caracteres)

delivery_document

Requerido
string
Documento de quien entrega (1-25 caracteres, DUI o NIT por ejemplo)

receiver_name

Requerido
string
Nombre de quien recibe (1-100 caracteres)

receiver_document

Requerido
string
Documento de quien recibe (1-25 caracteres, DUI o NIT por ejemplo)

observation

Opcional
string
Observaciones adicionales (Máximo 3000 caracteres)

vehicule_plate

Opcional
string
Placa del vehículo (1-10 caracteres)
Sí Indica campo obligatorio

Consideraciones importantes:

  • La extensión es opcional por defecto, pero se vuelve obligatoria si el total de la operación es ≥ $1,095.00 USD.
  • Si se incluye la extensión, los primeros 4 campos son obligatorios.

3. Other Documents (Otros Documentos)

Los otros documentos incluyen documentos asociados a la operación, como documentos de transporte o médicos.

Estructura de Otros Documentos 

"other_docs": [
        {
            "document_code": 0,
            "description": "string",
            "detail": "string",
            "doctor": {
                "name": "string",
                "nit": "string",
                "identification": "string",
                "service_type": 0
            }
        }
    ]

Campos de Otros Documentos

Validaciones para el objeto other_docs

document_code

Requerido
integer
Código del documento (1-4)

description

Opcional
string
Descripción del documento. Obligatorio si document_code ≠ 3

detail

Opcional
string
Detalle del documento. Obligatorio si document_code ≠ 3

doctor

Opcional
object
Información del médico. Obligatorio si document_code = 3
Sí Indica campo obligatorio

Campos del objeto doctor

Validaciones para el objeto doctor dentro de other_docs

name

Requerido
string
Nombre del médico (1-100 caracteres)

service_type

Requerido
integer
Tipo de servicio médico (1-6)

nit

Opcional
string
NIT del médico. Requerido si identification no se proporciona

identification

Opcional
string
Identificación del médico. Requerido si nit no se proporciona
Sí Indica campo obligatorio

Códigos de Documentos:

  1. Documento de Emisor
  2. Documento de Receptor
  3. Documento Médico
  4. Documento de Transporte

Consideraciones importantes:

  • La sección es opcional, pero si se incluye, debe contener entre 1 y 10 documentos.
  • Validaciones específicas:
    • description: 1-100 caracteres
    • detail: 1-300 caracteres
  • Cuando document_code = 3 (Documento Médico), el objeto doctor es obligatorio y los campos description y detail deben estar ausentes.
  • Para los otros códigos, description y detail son obligatorios y doctor debe estar ausente.
  • En doctor, debe proporcionarse o bien nit o bien identification, pero no ambos.

4. Related Documents (Documentos Relacionados)

Los documentos relacionados vinculan el DTE actual con documentos previos.

Estructura de Documentos Relacionados 

"related_docs": [
    {
      "document_number": "string",
      "document_type": "string",
      "emission_date": "string",
      "generation_type": 0
    }
  ],
}

Campos de Documentos Relacionados

Validaciones para el objeto related_docs

document_type

Requerido
string
Tipo de documento ('04': Nota de Remisión, '09': Doc. Contable Liquidación)

generation_type

Requerido
integer
Tipo de generación (1: Normal, 2: Contingencia)

document_number

Requerido
string
Número de documento (formato según generation_type)

emission_date

Requerido
string
Fecha de emisión en formato 'YYYY-MM-DD'
Sí Indica campo obligatorio

Consideraciones importantes:

  • La sección es opcional, pero si existe, puede contener hasta 50 documentos.
  • Validaciones específicas:
    • Si generation_type = 1: document_number puede tener máximo 20 caracteres
    • Si generation_type = 2: document_number debe tener formato UUID
    • emission_date: No puede ser una fecha futura. Si generation_type es 2 no es necesario enviarlo
  • Si hay documentos relacionados, entonces los ítems que referencian estos documentos deben incluir el campo related_doc con el número de documento correspondiente.
  • No se permiten tipos de documentos mixtos en la misma lista.
  • Todos los documentos relacionados deben tener el mismo tipo.

5. Third Party Sale (Venta a Terceros)

Representa ventas realizadas por cuenta de un tercero.

Estructura de Venta a Terceros 

"third_party_sale": {
  "name": "string",
  "nit": "string"
}

Campos de Venta a Terceros

Validaciones para el objeto third_party_sale

nit

Requerido
string
NIT del tercero (formato NIT válido)

name

Requerido
string
Nombre del tercero
Sí Indica campo obligatorio

Consideraciones importantes:

  • La sección es opcional.
  • Si se incluye, todos sus campos son obligatorios.
  • Cuando existe venta a terceros, todos los ítems deben tener su campo related_doc con referencia a un documento relacionado.
  • No se pueden mezclar ventas propias con ventas a terceros en el mismo documento.

Validaciones Comunes para Campos Opcionales

Existen algunas validaciones que aplican a todos los documentos tributarios electrónicos:

  • Relaciones entre Campos: Si existe related_docs, los ítems que lo referencian deben incluir un related_doc válido que apunte a un documento listado.
  • Validación de Extensión: La extensión es obligatoria si el total de la operación es ≥ $1,095.00 USD, de lo contrario es opcional.
  • Campos Opcionales: Aunque un objeto sea opcional, si se incluye, sus campos requeridos se vuelven obligatorios según las reglas específicas de cada sección.