RPAfelApi Integration Implementation Guide

🎯 Updated Recommendation: Use RPAfelApi ⭐⭐⭐

After reviewing the complete API documentation, RPAfelApi is the clear winner:

Why Use RPAfelApi Now

✅ Already Production-Ready
- Deployed at: https://fel.rpapos.com/api/fel
- Production-tested
- Comprehensive error handling
✅ All Features Included
- Certificate caching (for Infile)
- "Already signed" error handling (406)
- Support for all document types (FACT, NCRE, NDEB, ANULACION)
- Void certificate endpoint
- Query payer info
- Email sending
✅ Faster Implementation
- No need to build caching
- No need to implement error handling
- Just integrate the API
✅ Comprehensive Documentation
- Complete API guide
- Code examples in multiple languages
- Clear request/response formats

🏗️ Implementation Plan

Phase 1: Create RPAfelApi Provider Service

File: apps/backend/src/fel/infrastructure/provider-rpafelapi.service.ts

import { Injectable } from '@nestjs/common';
import { HttpService } from '@nestjs/axios';
import { lastValueFrom } from 'rxjs';
import type { ElectronicCertificationProvider } from '@/fel/domain/electronic-certification-provider.interface';
import type {
  IProviderCertifyDocumentParameters,
  IProviderGetSharedInfoParameters,
} from '@/fel/domain/fel.interface';

@Injectable()
export class ProviderRpaFelApiService implements ElectronicCertificationProvider {
  constructor(private readonly httpService: HttpService) {}

  private readonly baseUrl =
    process.env.RPA_FEL_API_URL ||
    process.env.NODE_ENV === 'production'
      ? 'https://fel.rpapos.com/api/fel'
      : 'https://fel-dev.rpapos.com/api/fel';

  async certifyDocument({
    taxId,
    xmlContent,
    apiUrl,
    token,
  }: IProviderCertifyDocumentParameters): Promise<undefined> {
    // Convert XML to DTE JSON structure
    const dteJson = this.convertXmlToDteJson(xmlContent, taxId);

    try {
      const response = await lastValueFrom(
        this.httpService.post(
          `${this.baseUrl}/generateCertificateToSign`,
          dteJson,
          {
            headers: {
              Authorization: token, // RPAfelApi expects token directly
              'Content-Type': 'application/json',
            },
            timeout: 60000, // 60 seconds (certification can take time)
          }
        )
      );

      // Transform RPAfelApi response to match certifier response format
      return this.transformResponse(response.data);
    } catch (error) {
      // Handle errors
      if (error.response?.status === 406) {
        // Already signed - RPAfelApi handles this automatically
        // It will fetch from certifier and return
        throw new Error('Document already signed - RPAfelApi will handle');
      }
      throw error;
    }
  }

  async getSharedInfo({
    taxId,
    data1,
    data2,
    username,
    apiUrl,
    token,
  }: IProviderGetSharedInfoParameters): Promise<unknown> {
    const response = await lastValueFrom(
      this.httpService.post(
        `${this.baseUrl}/QueryPayerInfo`,
        {
          IdentificationType: 'NIT',
          gface: 'Digifact', // or extract from config
          payerId: data2?.split('|')[1] || taxId,
          EmisorUser: username,
          EmisorNIT: taxId,
        },
        {
          headers: {
            Authorization: token,
            'Content-Type': 'application/json',
          },
        }
      )
    );

    return response.data;
  }

  /**
   * Convert XML to DTE JSON structure expected by RPAfelApi
   */
  private convertXmlToDteJson(xmlContent: string, taxId: string): any {
    // Parse XML and convert to DTE JSON structure
    // This is a simplified version - you'll need to parse the XML properly
    // You can use xml2js or similar library

    // For now, return structure - you'll need to implement XML parsing
    return {
      ID: 'DatosCertificados',
      DatosEmision: {
        ID: 'DatosEmision',
        // ... parse from XML
      },
    };
  }

  /**
   * Transform RPAfelApi response to match certifier response format
   */
  private transformResponse(rpaResponse: any): any {
    return {
      Codigo: rpaResponse.Codigo || 1,
      Mensaje: rpaResponse.Mensaje || 'OK',
      AcuseReciboSAT: rpaResponse.AcuseReciboSAT,
      Autorizacion: rpaResponse.Autorizacion_Text || rpaResponse.Autorizacion,
      Serie: rpaResponse.Autorizacion_Serie,
      NUMERO: rpaResponse.Autorizacion_Numero,
      Fecha_DTE: rpaResponse.FechaHoraCertificacion,
      Fecha_de_certificacion: rpaResponse.FechaHoraCertificacion,
      NITCertificador: rpaResponse.NITCertificador,
      NombreCertificador: rpaResponse.NombreCertificador,
      ResponseDATA1: rpaResponse.ResponseDATA1, // Base64 XML if available
    };
  }
}

Phase 2: Add XML to DTE JSON Converter

File: apps/backend/src/fel/application/xml-to-dte-json.service.ts

import { Injectable } from '@nestjs/common';
import { parseString } from 'xml2js';
import type { Invoice } from '@/fel/domain/fel.interface';

@Injectable()
export class XmlToDteJsonService {
  /**
   * Convert Invoice object to DTE JSON structure
   */
  convertInvoiceToDteJson(invoice: Invoice, rpaUUID: string): any {
    return {
      ID: 'DatosCertificados',
      DatosEmision: {
        ID: 'DatosEmision',
        DatosGenerales: {
          Tipo: invoice.generalData.type,
          FechaHoraEmision: invoice.generalData.dateTimeIssue,
          CodigoMoneda: invoice.generalData.currencyCode || 'GTQ',
          rpaUUID: rpaUUID,
          rpaDE_Empresa: this.mapProviderName(invoice.felProviderData.providerName),
          rpaCertificador_Usuario: '', // Will be set from business config
          rpaCertificador_Clave: '', // Will be set from business config
          rpaFisco_Usuario: '',
        },
        Emisor: {
          NITEmisor: invoice.issuerData.taxId,
          NombreEmisor: invoice.issuerData.taxName,
          CodigoEstablecimiento: invoice.issuerData.establishmentCode,
          NombreComercial: invoice.issuerData.commercialName,
          AfiliacionIVA: invoice.issuerData.vatAffiliationCode,
          DireccionEmisor: {
            Direccion: invoice.issuerData.addressData.address,
            CodigoPostal: invoice.issuerData.addressData.postalCode,
            Municipio: invoice.issuerData.addressData.municipality,
            Departamento: invoice.issuerData.addressData.department,
            Pais: invoice.issuerData.addressData.country,
          },
        },
        Receptor: {
          NombreReceptor: invoice.receiverData.taxName,
          IDReceptor: invoice.receiverData.taxId,
          TipoEspecial: invoice.receiverData.taxpayerType || 'NIT',
          DireccionReceptor: {
            Direccion: invoice.receiverData.addressData.address,
            CodigoPostal: invoice.receiverData.addressData.postalCode,
            Municipio: invoice.receiverData.addressData.municipality,
            Departamento: invoice.receiverData.addressData.department,
            Pais: invoice.receiverData.addressData.country,
          },
        },
        Frases: {
          Frase: invoice.phrases.map((phrase) => ({
            TipoFrase: phrase.phraseType,
            CodigoEscenario: phrase.scenarioCode,
          })),
        },
        Items: {
          Item: invoice.items.map((item, index) => ({
            NumeroLinea: (index + 1).toString(),
            BienOServicio: item.goodOrService,
            Cantidad: item.quantity.toString(),
            UnidadMedida: item.unitOfMeasure,
            Descripcion: item.name,
            PrecioUnitario: item.unitPrice.toFixed(2),
            Precio: item.amount.toFixed(2),
            Descuento: item.discount.toFixed(2),
            Total: (item.amount - item.discount).toFixed(2),
            Impuestos: {
              Impuesto: item.taxes.map((tax) => ({
                NombreCorto: tax.shortName,
                CodigoUnidadGravable: tax.taxableUnitCode,
                MontoGravable: tax.taxableAmount.toFixed(2),
                MontoImpuesto: tax.taxAmount.toFixed(2),
              })),
            },
          })),
        },
        Totales: {
          GranTotal: invoice.total.toFixed(2),
          TotalImpuestos: {
            TotalImpuesto: this.calculateTotalTaxes(invoice.items).map((tax) => ({
              NombreCorto: tax.name,
              TotalMontoImpuesto: tax.amount.toFixed(2),
            })),
          },
        },
      },
      extra: {
        subDomain: invoice.addendumData?.version || '',
        TipoEspecial: invoice.receiverData.taxpayerType || 'NIT',
      },
    };
  }

  private mapProviderName(providerName: string): string {
    const mapping: Record<string, string> = {
      digifact: 'Digifact',
      infile: 'Infile',
      fegora: 'Fegora',
      guatefactura: 'GuateFactura',
    };
    return mapping[providerName.toLowerCase()] || 'Digifact';
  }

  private calculateTotalTaxes(items: InvoiceItem[]): Array<{ name: string; amount: number }> {
    const taxMap = new Map<string, number>();

    items.forEach((item) => {
      item.taxes.forEach((tax) => {
        const current = taxMap.get(tax.shortName) || 0;
        taxMap.set(tax.shortName, current + tax.taxAmount);
      });
    });

    return Array.from(taxMap.entries()).map(([name, amount]) => ({ name, amount }));
  }
}

Phase 3: Update FelService

Update: apps/backend/src/fel/application/fel.service.ts

async certifyDocument({
  taxId,
  document,
}: ICertifyDocumentParameters): Promise<undefined> {
  const { businessData, felProviderData } = document;

  try {
    // Step 1: Fetch business data
    const business = await this.businessesRepository.findById(businessData.id);
    if (!business) {
      throw new Error('Business not found');
    }

    // Step 2: Check if using RPAfelApi
    const useRpaFelApi = process.env.USE_RPA_FEL_API === 'true' ||
                         felProviderData.providerName === 'rpafelapi';

    if (useRpaFelApi) {
      return await this.certifyViaRpaFelApi(document, business, taxId);
    }

    // Step 3: Use direct certifier (existing logic)
    // ... existing code ...
  } catch (error) {
    // ... error handling ...
  }
}

private async certifyViaRpaFelApi(
  document: Invoice,
  business: SelectableBusiness,
  taxId: string
): Promise<undefined> {
  // Extract certifier config
  const { felCertifier, encryptedFelToken } =
    this.extractFelCertifierConfig(business.felCertifierConfig);

  // Get certifier credentials
  const certifierUser = this.getCertifierUser(business, felCertifier);
  const certifierPassword = this.cryptoService.decrypt(encryptedFelToken);

  // Convert Invoice to DTE JSON
  const rpaUUID = document.addendumData.internalReference; // sale.id
  const dteJson = this.xmlToDteJsonService.convertInvoiceToDteJson(document, rpaUUID);

  // Add certifier credentials to DTE JSON
  dteJson.DatosEmision.DatosGenerales.rpaCertificador_Usuario = certifierUser;
  dteJson.DatosEmision.DatosGenerales.rpaCertificador_Clave = certifierPassword;

  // Get RPAfelApi provider
  const provider = this.providerService.getProvider('rpafelapi');

  // Certify via RPAfelApi
  const result = await provider.certifyDocument({
    taxId,
    xmlContent: '', // Not needed for RPAfelApi
    apiUrl: '', // Not needed
    token: '', // RPAfelApi handles auth internally
  });

  return result;
}

Phase 4: Update ProviderService

Update: apps/backend/src/fel/application/provider.service.ts

getProvider(providerName: string): ElectronicCertificationProvider {
  switch (providerName.toLowerCase()) {
    case 'digifact':
      return this.providerDigifactService;
    case 'infile':
      return this.providerInfileService;
    case 'rpafelapi':
      return this.providerRpaFelApiService; // Add this
    default:
      throw new Error(`Unknown provider: ${providerName}`);
  }
}

Phase 5: Update FelModule

Update: apps/backend/src/fel/fel.modules.ts

import { ProviderRpaFelApiService } from '@/fel/infrastructure/provider-rpafelapi.service';
import { XmlToDteJsonService } from '@/fel/application/xml-to-dte-json.service';

@Module({
  // ... existing imports ...
  providers: [
    FelService,
    ProviderService,
    XmlConversionService,
    XmlToDteJsonService, // Add this
    ProviderDigifactService,
    ProviderInfileService,
    ProviderRpaFelApiService, // Add this
  ],
  // ...
})
export class FelModule {}

Phase 6: Add Environment Configuration

Update: .env files

# Use RPAfelApi instead of direct certifiers
USE_RPA_FEL_API=true

# RPAfelApi URLs
RPA_FEL_API_URL=https://fel.rpapos.com/api/fel
# or for dev:
# RPA_FEL_API_URL=https://fel-dev.rpapos.com/api/fel

🎯 Benefits of This Approach

1. Immediate Value

✅ Certificate caching (built-in)
✅ "Already signed" handling (automatic)
✅ All document types supported
✅ Production-tested

2. Simpler Code

✅ No need to implement caching
✅ No need to handle 406 errors
✅ Less code to maintain
✅ Focus on business logic

3. Better Features

✅ Void certificate endpoint
✅ Query payer info
✅ Email sending
✅ Pub/Sub events

4. Future-Proof

✅ Centralized FEL service
✅ Easy to add new features
✅ Shared across systems
✅ Consistent behavior

🔄 Migration Strategy

Phase 1: Parallel Implementation (Week 1)

✅ Add RPAfelApi provider
✅ Keep existing direct certifiers
✅ Add feature flag: USE_RPA_FEL_API
✅ Test with sample documents

Phase 2: Gradual Rollout (Week 2)

✅ Enable for test businesses
✅ Monitor performance
✅ Compare results
✅ Fix any issues

Phase 3: Full Migration (Week 3)

✅ Enable for all businesses
✅ Keep direct certifiers as fallback
✅ Monitor and optimize
✅ Document changes

📊 Comparison: Before vs After

Feature	Direct Certifiers	RPAfelApi
Certificate Caching	❌ No	✅ Yes (Infile)
Already Signed Handling	❌ Manual	✅ Automatic
Void Certificate	❌ Not implemented	✅ Yes
Query Payer Info	⚠️ Partial	✅ Yes
Email Sending	❌ Not implemented	✅ Yes
Code Complexity	⚠️ Medium	✅ Low
Maintenance	⚠️ You maintain	✅ Centralized

🚀 Quick Start

1. Install Dependencies

npm install xml2js @types/xml2js

2. Create Provider Service

Copy the ProviderRpaFelApiService code above.

3. Create XML to DTE JSON Service

Copy the XmlToDteJsonService code above.

4. Update FelService

Add the certifyViaRpaFelApi method.

5. Update Configuration

Add environment variables:

USE_RPA_FEL_API=true
RPA_FEL_API_URL=https://fel.rpapos.com/api/fel

6. Test

// Test with a sample invoice
const result = await felService.certifyDocument({
  taxId: '44653948',
  document: sampleInvoice,
});

🎯 Next Steps

Implement RPAfelApi Provider - Use code above
Add XML to DTE JSON Converter - Convert Invoice to DTE JSON
Update FelService - Add RPAfelApi path
Test Thoroughly - Test with real documents
Enable Feature Flag - Gradual rollout
Monitor Performance - Track metrics
Full Migration - Enable for all

💡 Key Insights

RPAfelApi is Production-Ready - Already deployed and tested
All Features Included - Caching, error handling, void, etc.
Faster Implementation - No need to build everything
Better Long-term - Centralized service, easier maintenance
Supports All Document Types - FACT, NCRE, NDEB, ANULACION

Last Updated: 2025-12-18 Status: Implementation Guide - Ready to Code!

🎯 Updated Recommendation: Use RPAfelApi ⭐⭐⭐​

Why Use RPAfelApi Now​

🏗️ Implementation Plan​

Phase 1: Create RPAfelApi Provider Service​

Phase 2: Add XML to DTE JSON Converter​

Phase 3: Update FelService​

Phase 4: Update ProviderService​

Phase 5: Update FelModule​

Phase 6: Add Environment Configuration​

🎯 Benefits of This Approach​

1. Immediate Value​

2. Simpler Code​

3. Better Features​

4. Future-Proof​

🔄 Migration Strategy​

Phase 1: Parallel Implementation (Week 1)​

Phase 2: Gradual Rollout (Week 2)​

Phase 3: Full Migration (Week 3)​

📊 Comparison: Before vs After​

🚀 Quick Start​

1. Install Dependencies​

2. Create Provider Service​

3. Create XML to DTE JSON Service​

4. Update FelService​

5. Update Configuration​

6. Test​

🎯 Next Steps​

💡 Key Insights​