Saltar al contenido principal

FEL Official Resources & XSD Schemas

📚 Official SAT Resources​

1. SAT XSD Schema Repository​

Official XSD Files:

  • URL: https://cat.desa.sat.gob.gt/xsd/alfa/
  • Purpose: Official XML Schema Definitions (XSD) for FEL documents
  • Contains: Schema definitions for all FEL document types (FACT, NCRE, NDEB, ANULACION, etc.)

Usage:

  • Validate XML structure before sending to certifier
  • Reference for exact field requirements
  • Ensure compliance with SAT specifications

2. Official FEL SAT GitHub Repository​

Repository: https://github.com/fel-sat-gob-gt/cat

Contains:

  • Official FEL schemas
  • Documentation
  • Reference implementations
  • Updates and changes

3. XML Digital Signature Schema​

W3C XML Signature Schema:

🔍 Reference Implementation​

FELgt Repository​

Repository: https://github.com/krudos/FELgt

Description:

  • C# implementation of FEL schema
  • Can be used as reference for XML structure
  • Shows how to build FEL documents programmatically

Note: While this is a C# implementation, the XML structure is language-agnostic and can be used as a reference for our TypeScript/Node.js implementation.

📋 XSD Schema Files Reference​

Document Types​

Based on SAT's XSD repository, the following document types are supported:

  1. FACT - Factura (Invoice)
  2. NCRE - Nota de Crédito (Credit Note)
  3. NDEB - Nota de DĂ©bito (Debit Note)
  4. ANULACION - AnulaciĂłn de Factura (Invoice Cancellation)
  5. FESP - Factura Especial (Special Invoice)
  6. FACE - Factura ElectrĂłnica (Legacy Electronic Invoice)

Key XSD Elements​

Common Structure (All Document Types)​

<dte:GTDocumento>
  <dte:SAT>
    <dte:DTE>
      <dte:DatosEmision>
        <dte:DatosGenerales Tipo="FACT|NCRE|NDEB|ANULACION" />
        <dte:Emisor />
        <dte:Receptor />
        <dte:Frases />
        <dte:Items /> <!-- Not for ANULACION -->
        <dte:Totales /> <!-- Not for ANULACION -->
      </dte:DatosEmision>
      <dte:Certificacion />
    </dte:DTE>
    <dte:Adenda /> <!-- Optional -->
  </dte:SAT>
  <ds:Signature /> <!-- Digital signature -->
</dte:GTDocumento>

Credit Note (NCRE) Specific​

Complement: <ReferenciasNota>

<dte:Complementos>
  <dte:Complemento NombreComplemento="ReferenciasNota">
    <cno:ReferenciasNota>
      <cno:ReferenciaTipoDTE>FACT</cno:ReferenciaTipoDTE>
      <cno:ReferenciaNumero>UUID_ORIGINAL</cno:ReferenciaNumero>
      <cno:MotivoAjuste>DevoluciĂłn</cno:MotivoAjuste>
    </cno:ReferenciasNota>
  </dte:Complemento>
</dte:Complementos>

Debit Note (NDEB) Specific​

Complement: <AjustesFactura>

<dte:Complementos>
  <dte:Complemento NombreComplemento="AjustesFactura">
    <cno:AjustesFactura>
      <cno:ReferenciaTipoDTE>FACT</cno:ReferenciaTipoDTE>
      <cno:ReferenciaNumero>UUID_ORIGINAL</cno:ReferenciaNumero>
      <cno:MotivoAjuste>Cobro adicional</cno:MotivoAjuste>
    </cno:AjustesFactura>
  </dte:Complemento>
</dte:Complementos>

Cancellation (ANULACION) Specific​

Structure: Different from other documents

<dte:GTDocumento>
  <dte:SAT>
    <dte:AnulacionDocumento ID="DatosAnulacion">
      <dte:DatosGenerales
        FechaEmisionDocumentoAnulado="2025-02-18T10:20:00-06:00"
        FechaHoraAnulacion="2025-02-18T10:25:00-06:00"
        ID="ANULACION"
        MotivoAnulacion="Error en la factura"
      />
      <dte:DocumentoAnulado
        NumeroDocumento="UUID_ORIGINAL"
        NITEmisor="1234567-8"
        NITReceptor="CF"
      />
    </dte:AnulacionDocumento>
  </dte:SAT>
</dte:GTDocumento>

🛠️ Using XSD for Validation​

Option 1: XML Validation Library​

Node.js Libraries:

  • libxmljs2 - XML parsing and validation
  • xmldom + xsd-schema-validator - XSD validation

Example:

import { validateXML } from 'xsd-schema-validator';

async function validateFelXml(xmlContent: string, xsdPath: string): Promise<boolean> {
  try {
    await validateXML(xmlContent, xsdPath);
    return true;
  } catch (error) {
    console.error('XSD Validation Error:', error);
    return false;
  }
}

Option 2: Download XSD Files​

Download from SAT:

# Download FEL XSD schemas
wget -r https://cat.desa.sat.gob.gt/xsd/alfa/

# Download XML Signature schema
wget https://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd

Store in project:

docs/fel/xsd/
  ├── dte.xsd
  ├── fact.xsd
  ├── ncre.xsd
  ├── ndeb.xsd
  ├── anulacion.xsd
  └── xmldsig-core-schema.xsd

For Development:

  • Use XSD validation in development/staging
  • Log validation errors
  • Don't block certification (certifier will validate anyway)

For Production:

  • Rely on certifier validation
  • Log XML for debugging
  • Monitor certifier error responses

📖 Schema Namespaces​

Common Namespaces​

xmlns:dte="http://www.sat.gob.gt/dte/fel/0.2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:dtecomm="https://www.digifact.com.gt/dtecomm"
xmlns:cno="http://www.sat.gob.gt/dte/fel/CompCambiaria/0.1.0"

Namespace Usage​

  • dte: - Main FEL document elements
  • ds: - Digital signature elements
  • dtecomm: - Digifact addendum (optional)
  • cno: - Complements (ReferenciasNota, AjustesFactura)

🔗 Useful Links​

  1. SAT Portal:

  2. XSD Repository:

  3. Official GitHub:

  4. Reference Implementation:

  5. W3C XML Signature:

💡 Recommendations​

1. Download XSD Files Locally​

Store XSD files in your project for:

  • Reference during development
  • Optional validation in development
  • Documentation purposes

2. Use XSD as Reference​

Even if not validating, use XSD files to:

  • Understand exact field requirements
  • Check data types and formats
  • Ensure compliance

3. Monitor SAT Updates​

  • Check official repository for schema changes
  • Subscribe to SAT notifications
  • Update XSD files when schemas change

4. Test with XSD Validation​

In development/staging:

  • Validate XML before sending to certifier
  • Catch structural errors early
  • Reduce certifier API calls

🎯 Next Steps​

  1. Download XSD Files:

    mkdir -p docs/fel/xsd
    cd docs/fel/xsd
    wget -r --no-parent https://cat.desa.sat.gob.gt/xsd/alfa/

  2. Review Schema Files:

    • Check ncre.xsd for credit note structure
    • Check ndeb.xsd for debit note structure
    • Check anulacion.xsd for cancellation structure

  3. Update XML Generation:

    • Use XSD as reference for exact structure
    • Ensure all required fields are included
    • Match namespace declarations exactly

  4. Add Optional Validation:

    • Implement XSD validation in development
    • Log validation errors
    • Don't block certification (certifier is source of truth)

Last Updated: 2025-12-18
References: