Skip to main content

GF - Métodos y Parámetros

APIs – Gestor de Folios 3.0 (GF 3.0)​

1. Introducción

El Gestor de Folios 3.0 (GF 3.0) expone un conjunto de APIs REST que permiten:

  • Administrar facturadores
  • Consultar rangos primarios
  • Gestionar subrangos
  • Obtener numeración para emisión de documentos

El modelo de operación depende del tipo de facturador:

  • Facturador Local → trabaja con subrangos
  • Facturador Centralizado → solicita número a número

2. Modelo de operación

2.1 Facturador Local​

El facturador solicita un subrango completo de numeración y lo administra localmente.

Ventajas:

  • Menor latencia
  • Operación offline posible
  • Menor consumo de API

Responsabilidad:

  • Controlar secuencia interna
  • Liberar subrangos no utilizados

2.2 Facturador Centralizado​

El facturador solicita un número por cada documento emitido.

Ventajas:

  • Control centralizado absoluto
  • No hay manejo local de rangos

Responsabilidad:

  • Solicitar número antes de cada emisión

3. APIs para Facturadores Locales

3.1 POST RefillSubRange​

Descripción​

Solicita un nuevo subrango de numeración desde el rango primario asignado.

Resultado esperado​

El sistema devuelve:

  • Número inicial del subrango
  • Número final del subrango
  • Identificador del subrango
  • Serie
  • Tipo de documento

Uso típico​

Cuando:

  • El subrango actual se agotó
  • Se inicia operación
  • Se detecta bajo umbral interno

3.2 POST ReleaseSubRange​

Descripción​

Consulta qué subrangos están disponibles para ser liberados (devueltos al GF).

Uso típico​

Antes de ejecutar la liberación definitiva.

Resultado esperado​

Listado de subrangos:

  • Id del subrango
  • Desde / Hasta
  • Estado

3.3 POST ConfirmReleaseSubRange​

Descripción​

Confirma la liberación del subrango previamente seleccionado.

Resultado esperado​

  • El subrango queda disponible nuevamente en el rango primario
  • Se actualiza estado a liberado

⚠ Esta operación es irreversible.

4. APIs para Facturadores Centralizados

4.1 POST GetNextNumber​

Descripción​

Entrega el siguiente número disponible del rango primario.

Resultado esperado​

Devuelve:

  • Serie
  • Número
  • Tipo de documento
  • Id de asignación

Uso típico​

Debe invocarse:

  • Antes de emitir cada documento

⚠ El número entregado queda reservado y no puede reutilizarse.

5. APIs de Uso General

5.1 POST AddBiller​

Descripción​

Crea un nuevo facturador en el GF 3.0.

Uso​

Se utiliza al dar de alta:

  • Nuevas sucursales
  • Nuevas cajas
  • Nuevos puntos emisores

5.2 POST UpdateBiller​

Descripción​

Actualiza información o configuraciones de un facturador existente.

Ejemplos:

  • Cambio de tipo (local / centralizado)
  • Configuración de umbrales
  • Activación / desactivación

5.3 GET GetBillers​

Descripción​

Retorna la lista completa de facturadores registrados.

Incluye:

  • UUID
  • Tipo
  • Estado
  • Configuración

5.4 GET GetBillerById​

Descripción​

Retorna la información completa de un facturador específico utilizando su UUID.

5.5 GET GetPrimaryRanges​

Descripción​

Entrega todos los rangos primarios registrados en el sistema.

Incluye:

  • Serie
  • Desde
  • Hasta
  • Estado
  • Tipo de documento
  • Fecha de vencimiento (si aplica)

5.6 GET GetPrimaryRangeSubRanges​

Descripción​

Entrega todos los subrangos generados desde los rangos primarios.

Incluye:

  • Id del subrango
  • Facturador asignado
  • Estado
  • Intervalo numérico

5.7 GET GetBillerSubRanges​

Descripción​

Entrega los subrangos asociados a un facturador específico (por UUID).

6. Flujos recomendados

6.1 Flujo – Facturador Local​

  1. Crear facturador (AddBiller)

  2. Solicitar subrango (RefillSubRange)

  3. Emitir documentos usando numeración local

  4. Cuando corresponda:

    • Consultar subrangos liberables (ReleaseSubRange)
    • Confirmar liberación (ConfirmReleaseSubRange)

6.2 Flujo – Facturador Centralizado​

  1. Crear facturador (AddBiller)

  2. Antes de cada emisión:

    • Solicitar número (GetNextNumber)

  3. Emitir documento

7. Buenas prácticas de integración

  • No reutilizar números bajo ninguna circunstancia
  • Implementar manejo de errores y reintentos controlados
  • Registrar logs de cada solicitud al GF
  • Validar estado del facturador antes de operar
  • Monitorear disponibilidad de rangos primarios

8. Consideraciones técnicas

  • Todas las APIs son REST
  • Métodos: GET / POST
  • Identificación de facturadores por UUID
  • Se recomienda autenticación por token
  • Todas las operaciones quedan auditadas