DGI E-Invoicing Sandbox: Test Your Integration

import { EFact } from '@itzenata/efact-node'

const efact = new EFact(process.env.EFACT_SECRET_KEY!)

// 1. Create: invoice is returned normalized (UBL 2.1) and signed (XAdES)
const invoice = await efact.invoices.create({
  invoiceNumber: `TEST-${Date.now()}`,   // unique per organization
  invoiceDate: '2026-07-14',
  currency: 'MAD',
  paymentMethod: 'BANK_TRANSFER',
  buyerIce: '002345678901234',
  buyerName: 'Test Client SARL',
  lines: [
    { lineNumber: 1, description: 'Test integration', quantity: 1, unitPrice: 100, vatRate: 20 },
  ],
})
console.log(invoice.status) // 'SIGNED'

// 2. Track clearance: simulator responds within seconds
let status = await efact.invoices.retrieveStatus(invoice.id)
while (status.status === 'SIGNED' || status.status === 'TRANSMITTED') {
  await new Promise((r) => setTimeout(r, 2000))
  status = await efact.invoices.retrieveStatus(invoice.id)
}

console.log(status.status)       // 'ACCEPTED'
console.log(status.dgiReference) // clearance reference
console.log(status.dgiQrPayload) // QR code payload

import { EFactValidationError, EFactConflictError } from '@itzenata/efact-node'

// Invalid ICE (14 digits instead of 15) -> 400 VALIDATION_ERROR
try {
  await efact.invoices.create({ ...input, buyerIce: '12345678901234' })
} catch (e) {
  if (e instanceof EFactValidationError) {
    console.log(e.errors) // [{ field: 'buyerIce', message: '...' }]
  }
}

// Invoice number already used -> 409 INVOICE_NUMBER_EXISTS
try {
  await efact.invoices.create({ ...input, invoiceNumber: 'TEST-DUPLICATE' })
  await efact.invoices.create({ ...input, invoiceNumber: 'TEST-DUPLICATE' })
} catch (e) {
  if (e instanceof EFactConflictError) {
    console.log(e.code) // 'INVOICE_NUMBER_EXISTS'
  }
}

// Modifying an already signed invoice -> 409 INVOICE_NOT_EDITABLE
try {
  await efact.invoices.update(invoice.id, { buyerName: 'New name' })
} catch (e) {
  if (e instanceof EFactConflictError) {
    console.log(e.code) // 'INVOICE_NOT_EDITABLE'
  }
}

// Write this handler today: REJECTED contract is stable,
// even though the sandbox does not produce on-demand rejections yet.
const status = await efact.invoices.retrieveStatus(invoice.id)

switch (status.status) {
  case 'ACCEPTED':
    // Cleared invoice: archive dgiReference + QR, mark payable
    break
  case 'REJECTED':
    // Clearance rejected: display dgiErrorCode / dgiErrorMessage
    // to user, correct invoice data, issue a new invoice
    console.error(status.dgiErrorCode, status.dgiErrorMessage)
    break
  case 'FAILED':
    // Unrecoverable technical failure: alert team, contact support
    break
}

// Once ACCEPTED, artifacts can be downloaded directly:
GET /v1/invoices/{id}/pdf   # Invoice PDF
GET /v1/invoices/{id}/xml   # Signed UBL 2.1 XML (legal original)
GET /v1/invoices/{id}/qr    # Clearance QR code (PNG)