README

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

SDK	Paquete	Versión mínima
Python	`digifact-sdk` (PyPI)	Python 3.10+
JavaScript	`digifact-sdk` (npm)	Node 18+
PHP	`aalonzolu/digifact` (Packagist)	PHP 8.1+
C# / .NET	`Digifact.Fel` (NuGet)	.NET 8+

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

Método	DTE	Descripción
`invoice()`	FACT	Factura de consumidor final o NIT
`invoice()`	FCAM	Factura cambiaria con cuotas
`invoice()`	NABN	Nota de abono
`invoice()`	FESP	Factura especial (retención)
`invoice()`	RDON	Recibo por donación
`invoice()`	RECI	Recibo de colegiatura
`invoice()`	FPEQ	Factura pequeño contribuyente
`debitNote()`	NDEB	Nota de débito
`creditNote()`	NCRE	Nota de crédito parcial
`creditNoteTotal()`	—	Nota de crédito total (anulación)
`cancel()`	—	Anulación de DTE
`fuelInvoice()`	FACT+Combustible	Factura con IVA + impuesto PETROLEO
`ccaInvoice()`	FACT+CCA	Cobro por cuenta ajena
`lookupNit()`	—	Consulta nombre/dirección de un NIT en SAT
`lookupCui()`	—	Consulta el nombre de un CUI (DPI) en SAT
`getDte()`	—	Descarga un DTE ya emitido

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

Ordenados de más usados a menos usados.

Parámetro	Requerido	Descripción
`taxid` / `Taxid`	✔	NIT del emisor.
`username` / `Username`	✔	Usuario Digifact (la parte después de `GT.<NIT>.`).
`password` / `Password`	✔*	Contraseña. *O bien `token`.
`token` / `Token`	✔*	Bearer token preobtenido. *O bien `password`.
`environment` / `Environment`		`"test"` (default) o `"production"`.
`seller_name` / `SellerName`		Nombre del emisor. Para NIT individual es el nombre de la persona; para S.A. / S.E. es la razón social. Auto-consulta en SAT si se omite.
`seller_address` / `SellerAddress`		Dirección del emisor. Auto-consulta en SAT si se omite.
`branch_code` / `BranchCode`		Código del establecimiento (RTU). Default `"1"`.
`branch_name` / `BranchName`		Nombre comercial de la sucursal, el mismo que aparece en la patente de comercio. Default `"ESTABLECIMIENTO PRINCIPAL"`.
`afiliacion_iva` / `AfiliacionIva`		`"GEN"` (default), `"PEQ"` o `"EXE"`.
`tipo_frase` / `TipoFrase`		Override global de `TipoFrase` (legacy). Mutuamente exclusivo con `frases`.
`escenario` / `Escenario`		Override global de `CodigoEscenario` (legacy). Mutuamente exclusivo con `frases`.
`frases` / `Frases`		Nuevo. Lista de frases `{tipo_frase, escenario}`. Reemplaza a `tipo_frase`/`escenario`. Mutuamente exclusivo con ellos.
`petroleo_rates` / `PetroleoRates`		Mapa código→tarifa PETROLEO para `fuelInvoice()` (sólo gasolineras).
`timeout` / `Timeout`		Timeout HTTP. Default 120s (JS: 120000 ms).
`tipo_personeria` / `TipoPersoneria`		Código de personería del RTU. Sólo aplica a RDON. Default `"1"`.

Ver detalles y ejemplos por lenguaje en los READMEs respectivos.

Subsidio combustibles

El subsidio a la gasolina y al diésel finalizó el jueves 2 de julio de 2026 a las 24:00, antes de lo previsto: el presupuesto de Q2 mil millones (Decreto 11-2026, reglamentado por el Acuerdo Gubernativo 64-2026) se agotó por la demanda. Por eso los SDKs nunca envían las frases TipoFrase=9, Escenario=18 ni TipoFrase=9, Escenario=19 por su cuenta — no hay fecha de corte que valga para todos.

Las estaciones con inventario adquirido bajo el subsidio deben mantener el precio rebajado hasta agotar ese producto, sujeto a verificación. Mientras te quede ese inventario, manda las frases explícitamente con frases; al agotarlo, deja de mandarlas:

client.fuel_invoice("CF", items, frases=[
    {"tipo_frase": "1", "escenario": "1"},   # frase base
    {"tipo_frase": "9", "escenario": "18"},
    {"tipo_frase": "9", "escenario": "19"},
])

La leyenda del subsidio en la representación gráfica la genera Digifact a partir del XML certificado, no estos SDKs: al dejar de mandar las frases, deja de imprimirse sola.

Variables de entorno

DIGIFACT_TAXID=12345678
DIGIFACT_USERNAME=FELUSER
DIGIFACT_PASSWORD=...

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.

aalonzolu / digifact

Maintainers

Package info

Statistics

Security