README

SDKs para la API Digifact FEL NUC GT — facturación electrónica SAT Guatemala.

Instalación rápida

# Python
pip install digifact-sdk

# JavaScript
npm install digifact-sdk

# PHP
composer require aalonzolu/digifact

# C# / .NET
dotnet add package Digifact.Fel

Uso básico (los 4 SDKs)

# Python
from digifact_sdk import DigifactClient

client = DigifactClient(
    taxid="12345678",
    username="FELUSER",
    password="...",
    environment="test",   # o "production"
)
result = client.invoice("CF", [
    {"description": "Servicio", "qty": 1, "price": 100},
])
print(result.auth_number)

// JavaScript
import { DigifactClient } from 'digifact-sdk';

const client = new DigifactClient({
  taxid: '12345678', username: 'FELUSER', password: '...', environment: 'test',
});
const result = await client.invoice('CF', [
  { description: 'Servicio', qty: 1, price: 100 },
]);
console.log(result.authNumber);

// PHP
use Digifact\Fel\DigifactClient;

$client = new DigifactClient([
  'taxid' => '12345678', 'username' => 'FELUSER',
  'password' => '...', 'environment' => 'test',
]);
$result = $client->invoice('CF', [
  ['description' => 'Servicio', 'qty' => 1, 'price' => 100],
]);
echo $result->authNumber;

// C# / .NET
using Digifact.Fel;

using var client = new DigifactClient(new DigifactOptions {
  Taxid = "12345678", Username = "FELUSER",
  Password = "...", Environment = "test",
});
var result = await client.InvoiceAsync("CF", new[] {
  new LineItem { Description = "Servicio", Qty = 1, Price = 100 },
});
Console.WriteLine(result.AuthNumber);

Tipos de DTE soportados

Configuración del cliente (común a los 4 SDKs)

Ordenados de más usados a menos usados.

Ver detalles y ejemplos por lenguaje en los READMEs respectivos.

Subsidio combustibles — frases automáticas (9/18 y 9/19)

Durante el periodo de subsidio (2026-04-27 (incl.) a 2026-07-27 (excl.)), SAT exige incluir frases especiales TipoFrase=9, Escenario=18 y TipoFrase=9, Escenario=19 en facturas de combustible. El SDK las agrega automáticamente — las integraciones existentes no necesitan cambios.

Para deshabilitar la auto-inyección (ej. presupuesto agotado):

• Por ENV VAR (sin deploy): DIGIFACT_DISABLE_AUTO_FUEL_SUBSIDY_FRASES=1
• Por código: auto_fuel_subsidy_frases=false al inicializar el cliente o en cada llamada.

Para control total (frases propias): usa frases=[...] en lugar de tipo_frase/escenario.

Variables de entorno

DIGIFACT_TAXID=12345678
DIGIFACT_USERNAME=FELUSER
DIGIFACT_PASSWORD=...
# Deshabilita auto-inyección de frases de subsidio sin tocar código:
# DIGIFACT_DISABLE_AUTO_FUEL_SUBSIDY_FRASES=1

Estructura del repositorio

digifact-sdk/
├── python/          SDK Python — pyproject.toml, digifact_sdk/
├── javascript/      SDK JavaScript — package.json, src/
├── php/             SDK PHP — composer.json, src/
├── dotnet/          SDK C#/.NET — Digifact.Fel.csproj, *.cs
├── docs/            Documentación y colección Postman
│   └── postman/     Colección y ambiente para Postman
├── scripts/         Herramientas de validación y smoke tests
└── .github/
    └── workflows/
        ├── ci.yml       Tests en cada push/PR
        └── publish.yml  Publicación a PyPI/npm/Packagist/NuGet al hacer tag

Publicar una release

# Actualizar versiones en pyproject.toml y package.json, luego:
git tag v1.2.3
git push origin v1.2.3

El workflow publish.yml se activa automáticamente y publica los cuatro paquetes.

Documentación adicional

• Python SDK
• JavaScript SDK
• PHP SDK
• C# / .NET SDK
• Documentación SAT
• Colección Postman