FEL Controller - cURL Commands Reference

Complete cURL commands for all endpoints in fel.controller.ts.

Configuration

export BASE_URL="http://localhost:4000"
export TOKEN="YOUR_FIREBASE_ID_TOKEN"

1. Convert Document to XML

POST /fel/convert-to-xml

Converts an Invoice document to XML format.

curl -X POST "${BASE_URL}/fel/convert-to-xml" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "businessData": {
      "id": "your-business-uuid"
    },
    "felProviderData": {
      "providerName": "rpafelapi"
    },
    "invoiceNumber": "FAC-001",
    "date": "2024-01-15",
    "generalData": {
      "type": "FACT",
      "dateTimeIssue": "2024-01-15T10:00:00-06:00",
      "currencyCode": "GTQ"
    },
    "issuerData": {
      "taxId": "12345678-9",
      "taxName": "Empresa de Prueba S.A.",
      "establishmentCode": "001",
      "commercialName": "Empresa de Prueba",
      "vatAffiliationCode": "GEN",
      "addressData": {
        "address": "Calle Principal 123",
        "postalCode": "01001",
        "municipality": "Guatemala",
        "department": "Guatemala",
        "country": "GT"
      }
    },
    "receiverData": {
      "taxId": "98765432-1",
      "taxName": "Cliente de Prueba",
      "taxpayerType": "NIT",
      "addressData": {
        "address": "Calle Cliente 456",
        "postalCode": "01002",
        "municipality": "Guatemala",
        "department": "Guatemala",
        "country": "GT"
      }
    },
    "phrases": [
      {
        "phraseType": "1",
        "scenarioCode": "1"
      }
    ],
    "addendumData": {
      "version": "1.0",
      "internalReference": "REF-001",
      "dateReference": "2024-01-15",
      "validateInternalReference": "true"
    },
    "items": [
      {
        "name": "Producto de Prueba",
        "unitOfMeasure": "UNI",
        "quantity": 1,
        "unitPrice": 100.00,
        "amount": 100.00,
        "discount": 0.00,
        "goodOrService": "B",
        "productName": "Producto de Prueba",
        "taxes": [
          {
            "shortName": "IVA",
            "taxableUnitCode": "BOLSA",
            "taxableAmount": 100.00,
            "taxAmount": 12.00
          }
        ]
      }
    ],
    "total": 112.00
  }'

Response: XML content (Content-Type: application/xml)

2. Certify Document

POST /fel/certify-document

Certifies an Invoice document with the FEL provider.

curl -X POST "${BASE_URL}/fel/certify-document" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "businessData": {
      "id": "your-business-uuid"
    },
    "felProviderData": {
      "providerName": "rpafelapi"
    },
    "invoiceNumber": "FAC-001",
    "date": "2024-01-15",
    "generalData": {
      "type": "FACT",
      "dateTimeIssue": "2024-01-15T10:00:00-06:00",
      "currencyCode": "GTQ"
    },
    "issuerData": {
      "taxId": "12345678-9",
      "taxName": "Empresa de Prueba S.A.",
      "establishmentCode": "001",
      "commercialName": "Empresa de Prueba",
      "vatAffiliationCode": "GEN",
      "addressData": {
        "address": "Calle Principal 123",
        "postalCode": "01001",
        "municipality": "Guatemala",
        "department": "Guatemala",
        "country": "GT"
      }
    },
    "receiverData": {
      "taxId": "98765432-1",
      "taxName": "Cliente de Prueba",
      "taxpayerType": "NIT",
      "addressData": {
        "address": "Calle Cliente 456",
        "postalCode": "01002",
        "municipality": "Guatemala",
        "department": "Guatemala",
        "country": "GT"
      }
    },
    "phrases": [
      {
        "phraseType": "1",
        "scenarioCode": "1"
      }
    ],
    "addendumData": {
      "version": "1.0",
      "internalReference": "REF-001",
      "dateReference": "2024-01-15",
      "validateInternalReference": "true"
    },
    "items": [
      {
        "name": "Producto de Prueba",
        "unitOfMeasure": "UNI",
        "quantity": 1,
        "unitPrice": 100.00,
        "amount": 100.00,
        "discount": 0.00,
        "goodOrService": "B",
        "productName": "Producto de Prueba",
        "taxes": [
          {
            "shortName": "IVA",
            "taxableUnitCode": "BOLSA",
            "taxableAmount": 100.00,
            "taxAmount": 12.00
          }
        ]
      }
    ],
    "total": 112.00
  }'

Note: The felProviderData.providerName and businessData.id are used to retrieve FEL credentials from the business configuration.

Response: CertifierResponse | undefined

3. Get Shared Info

POST /fel/get-shared-info

Retrieves shared information from the FEL provider (e.g., NIT/CUI lookup).

curl -X POST "${BASE_URL}/fel/get-shared-info" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "your-business-uuid",
    "data1": "SHARED_GETINFONITcom",
    "data2": "NIT|12345678"
  }'

Example for CUI lookup:

curl -X POST "${BASE_URL}/fel/get-shared-info" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "your-business-uuid",
    "data1": "SHARED_GETINFOCUI",
    "data2": "CUI|1234567890123"
  }'

Response: Shared info response object

4. Create Credit Note

POST /fel/credit-notes

Creates a new credit note (Nota de Crédito).

curl -X POST "${BASE_URL}/fel/credit-notes" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "your-business-uuid",
    "saleId": "your-certified-sale-uuid",
    "createdBy": "your-user-uuid",
    "creditNoteDate": "2024-01-15T10:00:00.000Z",
    "customerId": "customer-uuid",
    "taxId": "12345678-9",
    "taxName": "Cliente de Prueba",
    "taxAddress": "Ciudad de Guatemala",
    "locationId": "location-uuid",
    "locationName": "Tienda Principal",
    "currencyId": "currency-uuid",
    "currencyCode": "GTQ",
    "minorUnit": 2,
    "exchangeRate": 1.0,
    "currency": {
      "id": "currency-uuid",
      "code": "GTQ",
      "name": "Quetzal",
      "symbol": "Q"
    },
    "totalAmount": 100.00,
    "totalBaseAmount": 90.00,
    "detail": {
      "items": [
        {
          "productId": "product-uuid",
          "productName": "Producto de Prueba",
          "quantity": 1,
          "unitPrice": 100.00,
          "amount": 100.00,
          "baseAmount": 90.00,
          "taxes": [
            {
              "taxId": "tax-uuid",
              "taxName": "IVA",
              "rate": 0.12,
              "amount": 10.00,
              "baseAmount": 90.00
            }
          ]
        }
      ]
    },
    "paymentDetail": {},
    "taxpayerType": "NIT",
    "originalInvoiceUuid": "fel-uuid-from-certified-sale",
    "adjustmentReason": "Devolución de mercancía",
    "generateElectronicTaxDocument": true
  }'

Response: Created credit note object with id field

5. Get Credit Note by ID

GET /fel/credit-notes/:id

Retrieves a credit note by its ID.

curl -X GET "${BASE_URL}/fel/credit-notes/your-credit-note-id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Credit note object

6. Get Credit Notes by Sale ID

GET /fel/credit-notes/sale/:saleId

Retrieves all credit notes for a specific sale.

curl -X GET "${BASE_URL}/fel/credit-notes/sale/your-sale-id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Array of credit note objects

7. Certify Credit Note

POST /fel/credit-notes/:id/certify

Certifies a credit note with the FEL provider (RPAfelApi).

curl -X POST "${BASE_URL}/fel/credit-notes/your-credit-note-id/certify" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Certification response

Note: This will:

Validate SAT requirements
Convert to DTE JSON
Send to RPAfelApi
Update credit note with certification details
Trigger inventory reversal event

8. Create Debit Note

POST /fel/debit-notes

Creates a new debit note (Nota de Débito).

curl -X POST "${BASE_URL}/fel/debit-notes" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "your-business-uuid",
    "saleId": "your-certified-sale-uuid",
    "createdBy": "your-user-uuid",
    "debitNoteDate": "2024-01-15T10:00:00.000Z",
    "customerId": "customer-uuid",
    "taxId": "12345678-9",
    "taxName": "Cliente de Prueba",
    "taxAddress": "Ciudad de Guatemala",
    "locationId": "location-uuid",
    "locationName": "Tienda Principal",
    "currencyId": "currency-uuid",
    "currencyCode": "GTQ",
    "minorUnit": 2,
    "exchangeRate": 1.0,
    "currency": {
      "id": "currency-uuid",
      "code": "GTQ",
      "name": "Quetzal",
      "symbol": "Q"
    },
    "totalAmount": 50.00,
    "totalBaseAmount": 45.00,
    "detail": {
      "items": [
        {
          "productId": "product-uuid",
          "productName": "Producto de Prueba",
          "quantity": 1,
          "unitPrice": 50.00,
          "amount": 50.00,
          "baseAmount": 45.00,
          "taxes": [
            {
              "taxId": "tax-uuid",
              "taxName": "IVA",
              "rate": 0.12,
              "amount": 5.00,
              "baseAmount": 45.00
            }
          ]
        }
      ]
    },
    "paymentDetail": {},
    "taxpayerType": "NIT",
    "originalInvoiceUuid": "fel-uuid-from-certified-sale",
    "adjustmentReason": "Ajuste por error en facturación",
    "generateElectronicTaxDocument": true
  }'

Response: Created debit note object with id field

9. Get Debit Note by ID

GET /fel/debit-notes/:id

Retrieves a debit note by its ID.

curl -X GET "${BASE_URL}/fel/debit-notes/your-debit-note-id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Debit note object

10. Get Debit Notes by Sale ID

GET /fel/debit-notes/sale/:saleId

Retrieves all debit notes for a specific sale.

curl -X GET "${BASE_URL}/fel/debit-notes/sale/your-sale-id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Array of debit note objects

11. Certify Debit Note

POST /fel/debit-notes/:id/certify

Certifies a debit note with the FEL provider (RPAfelApi).

curl -X POST "${BASE_URL}/fel/debit-notes/your-debit-note-id/certify" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Certification response

Note: This will:

Validate SAT requirements
Convert to DTE JSON
Send to RPAfelApi
Update debit note with certification details

12. Request Cancellation

POST /fel/cancellations

Requests cancellation of an invoice (Anulación).

curl -X POST "${BASE_URL}/fel/cancellations" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "saleId": "your-certified-sale-uuid",
    "cancellationReason": "Error en la facturación",
    "createdBy": "your-user-uuid"
  }'

Response: Created cancellation object with id field

Note: Cancellation can only be requested for invoices in the same month they were issued (SAT requirement).

13. Get Cancellation by ID

GET /fel/cancellations/:id

Retrieves a cancellation by its ID.

curl -X GET "${BASE_URL}/fel/cancellations/your-cancellation-id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Cancellation object

14. Get Cancellations by Sale ID

GET /fel/cancellations/sale/:saleId

Retrieves all cancellations for a specific sale.

curl -X GET "${BASE_URL}/fel/cancellations/sale/your-sale-id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Array of cancellation objects

15. Certify Cancellation

POST /fel/cancellations/:id/certify

Certifies a cancellation with the FEL provider (RPAfelApi).

curl -X POST "${BASE_URL}/fel/cancellations/your-cancellation-id/certify" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Response: Certification response

Note: This will:

Validate SAT requirements (same-month cancellation)
Convert to DTE JSON
Send to RPAfelApi
Update cancellation with certification details
Update sale status to CANCELLED
Trigger inventory reversal event

Complete Testing Workflow Examples

Credit Note Flow

# 1. Create credit note
RESPONSE=$(curl -X POST "${BASE_URL}/fel/credit-notes" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @credit-note-payload.json)

CREDIT_NOTE_ID=$(echo $RESPONSE | jq -r '.id')

# 2. Get credit note
curl -X GET "${BASE_URL}/fel/credit-notes/${CREDIT_NOTE_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

# 3. Certify credit note
curl -X POST "${BASE_URL}/fel/credit-notes/${CREDIT_NOTE_ID}/certify" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Debit Note Flow

# 1. Create debit note
RESPONSE=$(curl -X POST "${BASE_URL}/fel/debit-notes" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @debit-note-payload.json)

DEBIT_NOTE_ID=$(echo $RESPONSE | jq -r '.id')

# 2. Get debit note
curl -X GET "${BASE_URL}/fel/debit-notes/${DEBIT_NOTE_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

# 3. Certify debit note
curl -X POST "${BASE_URL}/fel/debit-notes/${DEBIT_NOTE_ID}/certify" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Cancellation Flow

# 1. Request cancellation
RESPONSE=$(curl -X POST "${BASE_URL}/fel/cancellations" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "saleId": "your-sale-id",
    "cancellationReason": "Error en la facturación",
    "createdBy": "your-user-id"
  }')

CANCELLATION_ID=$(echo $RESPONSE | jq -r '.id')

# 2. Get cancellation
curl -X GET "${BASE_URL}/fel/cancellations/${CANCELLATION_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

# 3. Certify cancellation
curl -X POST "${BASE_URL}/fel/cancellations/${CANCELLATION_ID}/certify" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json"

Quick Reference

Endpoint	Method	Description
`/fel/convert-to-xml`	POST	Convert Invoice to XML
`/fel/certify-document`	POST	Certify Invoice document
`/fel/get-shared-info`	POST	Get shared info (NIT/CUI lookup)
`/fel/credit-notes`	POST	Create credit note
`/fel/credit-notes/:id`	GET	Get credit note by ID
`/fel/credit-notes/sale/:saleId`	GET	Get credit notes by sale
`/fel/credit-notes/:id/certify`	POST	Certify credit note
`/fel/debit-notes`	POST	Create debit note
`/fel/debit-notes/:id`	GET	Get debit note by ID
`/fel/debit-notes/sale/:saleId`	GET	Get debit notes by sale
`/fel/debit-notes/:id/certify`	POST	Certify debit note
`/fel/cancellations`	POST	Request cancellation
`/fel/cancellations/:id`	GET	Get cancellation by ID
`/fel/cancellations/sale/:saleId`	GET	Get cancellations by sale
`/fel/cancellations/:id/certify`	POST	Certify cancellation

Notes

All endpoints require authentication via Authorization: Bearer <token> header
Replace placeholder UUIDs with actual values from your database
For credit/debit notes, originalInvoiceUuid must be from a certified sale
Cancellation can only be done in the same month as the invoice date (SAT requirement)
Certification endpoints trigger event handlers for inventory and accounting updates

Configuration​

1. Convert Document to XML​

2. Certify Document​

3. Get Shared Info​

4. Create Credit Note​

5. Get Credit Note by ID​

6. Get Credit Notes by Sale ID​

7. Certify Credit Note​

8. Create Debit Note​

9. Get Debit Note by ID​

10. Get Debit Notes by Sale ID​

11. Certify Debit Note​

12. Request Cancellation​

13. Get Cancellation by ID​

14. Get Cancellations by Sale ID​

15. Certify Cancellation​

Complete Testing Workflow Examples​

Credit Note Flow​

Debit Note Flow​

Cancellation Flow​

Quick Reference​

Notes​

Configuration

1. Convert Document to XML

2. Certify Document

3. Get Shared Info

4. Create Credit Note

5. Get Credit Note by ID

6. Get Credit Notes by Sale ID

7. Certify Credit Note

8. Create Debit Note

9. Get Debit Note by ID

10. Get Debit Notes by Sale ID

11. Certify Debit Note

12. Request Cancellation

13. Get Cancellation by ID

14. Get Cancellations by Sale ID

15. Certify Cancellation

Complete Testing Workflow Examples

Credit Note Flow

Debit Note Flow

Cancellation Flow

Quick Reference

Notes