Carga masiva (lotes)

Un lote permite emitir muchos DTE de una sola vez: en vez de llamar POST /dte documento por documento, se sube un archivo Excel con una fila por documento (y sus ítems), y un proceso asíncrono de Fegora emite cada documento por su cuenta.

Si prefiere no armar el archivo por API, la aplicación web de Fegora ofrece una pantalla de carga guiada — vea Carga masiva (guía de usuario).

Crear un lote: `POST /lote`

curl -X POST https://api.fegora.com/lote \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...ejemplo" \
  -H "Content-Type: application/json" \
  -d '{
        "idCuenta": "12345678",
        "archivo": "UEsDBBQABgAIAAAAIQBBN4LPbgEAAAQFAAATAAgC...ejemplo-base64-xlsx"
      }'

Campo	Tipo	Obligatorio	Descripción
`idCuenta`	string	Sí	Cuenta emisora sobre la que se crearán los documentos.
`archivo`	string (base64)	Sí	Contenido del archivo Excel, codificado en base64.

Respuesta

{
  "id": "030b57e5-c84a-4376-813d-150bdd933151",
  "idCuenta": "12345678",
  "estado": "Creado",
  "archivoUri": "https://cdn.fegora.com/lotes/12345678_20260712155000.xlsx",
  "resultadoArchivoUri": null,
  "cantidadOperaciones": 25,
  "cantidadOperacionesEjecutadas": 0,
  "cantidadOperacionesError": 0,
  "cantidadOperacionesPendientesEjecucion": 25,
  "fechaCreacion": "2026-07-12T15:50:00",
  "usuarioCreacion": "integracion@empresa-ejemplo.com"
}

Al crear el lote, Fegora ya valida el archivo y calcula cantidadOperaciones contando las filas no vacías de la columna OPERACION (menos el encabezado). Si el archivo no puede leerse, no tiene hojas, no tiene filas o falta la columna OPERACION, la solicitud falla con 400 y uno de los códigos LOT-INVEXC-2..LOT-INVEXC-5.

Formato del archivo Excel

Extensión: .xlsx únicamente. La validación al crear el lote usa una librería que no lee el formato antiguo .xls — un archivo .xls es rechazado con LOT-INVEXC-2 antes de procesarse.
La primera fila debe contener los encabezados de columna (nombres exactos, sin distinguir mayúsculas/minúsculas).
Cada documento ocupa una fila de encabezado (con la columna OPERACION en CREAR) seguida de una o más filas de detalle (una por ítem, sin valor en OPERACION), hasta la siguiente fila CREAR o hasta 5 filas vacías consecutivas.

TIPO acepta factura, notaCredito, notaDebito y facturaEspecial (sin distinguir mayúsculas/minúsculas), y también los demás tipos de Guatemala que acepta POST /dte — por ejemplo recibo o reciboDonacion (vea Recibos en un lote). Los valores por defecto de la dirección del receptor (CIUDAD, GUATEMALA, código postal 01001, país GT) asumen un emisor guatemalteco.

Columnas de encabezado del documento

Columna	Descripción
`OPERACION`	`CREAR` marca el inicio de un nuevo documento en esa fila.
`CODIGO_ESTABLECIMIENTO`	Código de establecimiento del emisor.
`TIPO`	`factura`, `notaCredito`, `notaDebito`, `facturaEspecial`, `recibo`, `reciboDonacion`, … (vea la nota anterior).
`NUMERO_TRANSACCION`	Número de transacción propio, para evitar duplicados.
`FECHA` (o `FECHA_ANIO` / `FECHA_MES` / `FECHA_DIA`)	Fecha de emisión.
`MONEDA`	Moneda del documento.
`MOTIVO_EXENCION_IVA`	Motivo de exención de IVA del documento (mismo valor que `motivoExencionIva` en `POST /dte`, p. ej. `LEY_IVA_ART8_NUM1`). Obligatorio en la práctica para recibos — vea Recibos en un lote.
`ES_EXENTO_IVA`	`si` / `no`. Opcional; si se omite, se hereda lo configurado en la cuenta.
`ID_RECEPTOR`	Identificador fiscal del receptor (`CF` para consumidor final).
`NOMBRE_RECEPTOR`	Nombre del receptor.
`DIRECCION_RECEPTOR` / `MUNICIPIO_RECEPTOR` / `DEPARTAMENTO_RECEPTOR` / `PAIS_RECEPTOR` / `CODIGO_POSTAL_RECEPTOR`	Dirección del receptor.
`DIRECCION_CORREO_ELECTRONICO_RECEPTOR`	Correo del receptor.
`DATO_ADICIONAL_1_NOMBRE` / `_ETIQUETA` / `_VALOR` / `_VISIBLE` (y `_2_`, `_3_`)	Hasta 3 datos adicionales a nivel de documento — vea Datos adicionales.
`ABONO_PACTADO_1_FECHA` / `_MONTO` (hasta `_5_`)	Hasta 5 abonos pactados — vea Casos especiales.

Columnas de detalle (una fila por ítem)

Columna	Descripción
`LINEA_DESCRIPCION`	Descripción del ítem.
`LINEA_TIPO`	`bien` o `servicio`.
`LINEA_CANTIDAD`	Cantidad.
`LINEA_PRECIO_UNITARIO` / `LINEA_PRECIO`	Precio unitario o precio de línea.
`LINEA_DESCUENTO`	Descuento del ítem.
`LINEA_IMPUESTO_1_NOMBRE_CORTO`	Nombre corto del impuesto (p. ej. `IVA`).
`LINEA_DATO_ADICIONAL_1_NOMBRE` / `_ETIQUETA` / `_VALOR` / `_VISIBLE` (y `_2_`, `_3_`)	Hasta 3 datos adicionales a nivel de ítem.

Recibos en un lote

La SAT exige que todo recibo (TIPO = recibo) incluya la frase de exención de IVA, y el motivo depende de quién emite — no hay un valor único que Fegora pueda asignar por usted. En un recibo la SAT sólo acepta estos tres:

Emisor / concepto	`MOTIVO_EXENCION_IVA`	Frase
Colegios privados: matrícula, colegiaturas, derechos de examen	`LEY_IVA_ART8_NUM1`	4-8
Cuotas de membresía de asociaciones, gremiales, colegios profesionales	`LEY_IVA_ART7_NUM10`	4-5
Servicios de asociaciones, fundaciones e instituciones no lucrativas	`LEY_IVA_ART7_NUM13`	4-6

Cualquier otro motivo en un recibo lo rechaza el certificador (FEL_RCP328). Si la celda queda vacía, Fegora usa el motivo por defecto configurado en la cuenta (motivoExencionIva de la información fiscal, aunque la cuenta no esté marcada como exenta). Si la cuenta tampoco tiene uno, esa fila falla con FEG_DTE_CREA_RECI_001 y cuenta como error del lote.

OPERACION	TIPO	NUMERO_TRANSACCION	MOTIVO_EXENCION_IVA	ID_RECEPTOR	NOMBRE_RECEPTOR	LINEA_TIPO	LINEA_DESCRIPCION	LINEA_CANTIDAD	LINEA_PRECIO_UNITARIO
CREAR	recibo	REC-0001	LEY_IVA_ART8_NUM1	CF	Padre de Familia Ejemplo	servicio	Colegiatura octubre	1	850.00
						servicio	Derecho de examen	1	150.00

Use LINEA_TIPO = servicio (si se omite, el ítem se emite como bien) y deje vacías las columnas LINEA_IMPUESTO_1_*: un recibo no lleva IVA. Para reciboDonacion el motivo se asigna solo, pero el documento necesita el dato adicional TIPO_PERSONERIA (vea Tipos de documento).

Descargar el archivo del lote: `GET /lote/{id}/archivo`

El archivo subido contiene datos de sus receptores, así que no es público: la archivoUri que devuelve el lote es una referencia interna y no se puede abrir directamente. Para descargar el archivo original use:

curl -X GET https://api.fegora.com/lote/030b57e5-c84a-4376-813d-150bdd933151/archivo \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...ejemplo" \
  -o lote.xlsx

Sólo pueden descargarlo los usuarios de la cuenta del lote (o el operador de su canal). Un lote de otra cuenta responde igual que un lote inexistente.

Seguir el estado: `GET /lote/{id}`

curl -X GET https://api.fegora.com/lote/030b57e5-c84a-4376-813d-150bdd933151 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...ejemplo"

{
  "id": "030b57e5-c84a-4376-813d-150bdd933151",
  "estado": "procesado",
  "archivoUri": "https://cdn.fegora.com/lotes/12345678_20260712155000.xlsx",
  "resultadoArchivoUri": "https://cdn.fegora.com/lotes/12345678_20260712155000-resultado.xlsx",
  "cantidadOperaciones": 25,
  "cantidadOperacionesEjecutadas": 23,
  "cantidadOperacionesError": 2,
  "cantidadOperacionesPendientesEjecucion": 0,
  "fechaCreacion": "2026-07-12T15:50:00",
  "ultimaFechaEdicion": "2026-07-12T15:52:30"
}

El valor de estado no sigue un catálogo cerrado ni una capitalización consistente en el API actual: al crear el lote se observa "Creado", y el proceso de emisión de Fegora luego lo actualiza a "enProceso" y finalmente "procesado" (minúscula). No existe un estado "Error" propio del lote — un lote puede terminar en "procesado" con cantidadOperacionesError mayor a cero, indicando que algunas filas fallaron aunque el lote en sí ya terminó de procesarse. Compare estado sin distinguir mayúsculas/minúsculas y guíese por los contadores (cantidadOperacionesEjecutadas, cantidadOperacionesError, cantidadOperacionesPendientesEjecucion) para el progreso real, no sólo por el texto de estado.

Mientras cantidadOperacionesPendientesEjecucion sea mayor a cero, siga consultando este endpoint periódicamente hasta que llegue a cero.

Actualizar un lote: `PATCH /lote/{id}`

Fegora usa esta misma ruta internamente para reportar el avance del procesamiento. Como integrador normalmente sólo necesita leer el lote (GET /lote/{id}), pero la ruta de actualización acepta los mismos campos:

{
  "estado": "procesado",
  "cantidadOperacionesEjecutadas": 23,
  "cantidadOperacionesError": 2,
  "cantidadOperacionesPendientesEjecucion": 0
}

Todos los campos son opcionales — sólo se actualizan los que se envían.

Obtener los resultados por fila

Cuando el lote termina de procesarse, resultadoArchivoUri (si está disponible) apunta a un archivo con el detalle de cada fila, incluidas las que fallaron.

Páginas relacionadas

Carga masiva (guía de usuario)

La misma funcionalidad desde la aplicación web, sin usar el API directamente.

Casos especiales

Plantillas reutilizables, resguardo de XML y otros flujos fuera de la emisión estándar.

Introducción

Documentos DTE

Guías por país

Carga masiva (lotes)

Crear un lote: `POST /lote`

Respuesta

Formato del archivo Excel

Columnas de encabezado del documento

Columnas de detalle (una fila por ítem)

Recibos en un lote

Descargar el archivo del lote: `GET /lote/{id}/archivo`

Seguir el estado: `GET /lote/{id}`

Actualizar un lote: `PATCH /lote/{id}`

Obtener los resultados por fila

Páginas relacionadas

Carga masiva (guía de usuario)

Casos especiales

​Crear un lote: POST /lote

​Respuesta

​Formato del archivo Excel

​Columnas de encabezado del documento

​Columnas de detalle (una fila por ítem)

​Recibos en un lote

​Descargar el archivo del lote: GET /lote/{id}/archivo

​Seguir el estado: GET /lote/{id}

​Actualizar un lote: PATCH /lote/{id}

​Obtener los resultados por fila

​Páginas relacionadas

Carga masiva (guía de usuario)

Casos especiales

Crear un lote: `POST /lote`

Respuesta

Formato del archivo Excel

Columnas de encabezado del documento

Columnas de detalle (una fila por ítem)

Recibos en un lote

Descargar el archivo del lote: `GET /lote/{id}/archivo`

Seguir el estado: `GET /lote/{id}`

Actualizar un lote: `PATCH /lote/{id}`

Obtener los resultados por fila

Páginas relacionadas