Saltar al contenido principal

🛠️ Guía Técnica API REST: Método Lista Documentos

Actualización

Este instructivo detalla el funcionamiento del endpoint para la consulta de documentos emitidos. Se han aplicado reglas estrictas de validación de fechas y paginación para garantizar la estabilidad de las consultas y la fluidez en las integraciones.

1. Información del Endpoint

2. Reglas de Validación de Fechas (Obligatorio)

Para que la solicitud sea procesada exitosamente, los parámetros de fecha deben cumplir con las siguientes condiciones:

  • Rango de Consulta: El periodo entre la fechaInicio y la fechaFin no puede ser mayor a 7 días calendario.

  • Fecha de Inicio (Opcional): * No existe una limitación de días hacia el pasado para la fecha de inicio, siempre que el rango total no exceda los 7 días.

    • Si no se informa la fecha de inicio: El sistema la igualará automáticamente a la fechaFin.

  • Fecha de Fin (Requerido): * Si el campo fechaFin se envía únicamente con el formato YYYY-MM-DD (sin hora), el sistema asumirá automáticamente las 23:59:59.

    • Esto permite que, al consultar un mismo día (inicio y fin iguales), se obtengan todos los registros generados hasta el último segundo de esa fecha.

3. Paginación y Control de Duplicados

El sistema cuenta con un mecanismo de protección para evitar consultas redundantes que saturen la base de datos.

  • Identificación por Página: El parámetro paginaActual es ahora parte de la llave de validación.

  • Comportamiento: Usted puede solicitar las páginas sucesivas (1, 2, 3...) de un mismo set de filtros de forma consecutiva. El sistema ya no detectará estas peticiones como duplicadas, permitiendo una descarga fluida de grandes volúmenes de datos dentro del rango de 7 días.

4. Estructura del JSON (Request)

Request: Parámetros a enviar

{
"codigoSucursal": "string",
"ptoFacturacion": "string",
"tipoDocumento": "string",
"serialDispositivo": "string", #OPCIONAL
"fechaInicio": "string",
"fechaFin": "string",
"paginaActual": 0
}
Parámetro Tipo Obligatorio Descripción
codigoSucursal String Sí Código de la sucursal a consultar
ptoFacturacion String Sí Código del punto de facturación a consultar
tipoDocumento String Sí Código del documento (Ej: 01 para Factura, 04 para Nota de Crédito).
serialDispositivo String No Serial del dispositivo a consultar
fechaInicio String No Formato YYYY-MM-DD. Si se omite, toma el valor de fechaFin.
fechaFin String Sí Formato YYYY-MM-DD. Por defecto toma las 23:59:59 si no se envía hora.
paginaActual Integer Sí Número de página a consultar. Diferencia la petición para evitar bloqueos por duplicidad.

Ejemplo Request: JSON

{
  "codigoSucursal": "0000",
  "ptoFacturacion": "1",
  "tipoDocumento": "01",
  "serialDispositivo": "TFHKA00001",
  "fechaInicio": "2026-03-11 00:00:00", 
  "fechaFin": "2026-03-18 23:59:59",
  "paginaActual": 1
}


5. Estructura de Respuesta del API (Response)

Cuando realices una consulta exitosa al método ListaDocumentos, el sistema retornará un objeto JSON con el siguiente formato.


Ejemplo Response:
 

{
  "codigo": "200",
  "mensaje": "Se retorna listado de documentos.",
  "resultado": "procesado",
  "total": 1,
  "documentos": [
    {
      "tipoDocumento": "01",
      "numeroDocumentoFiscal": "0000000001",
      "fechaEmisionDocumento": "2024-12-16 12:42:21",
      "tipoEmision": "01",
      "cufe": "FE011000000000008-952-840-7700012024121600000000014430121709441459",
      "qr": "https://dgi-fep-test.mef.gob.pa:40001/...",
      "numeroProtocoloAutorizacion": "0000155596713-2-201520240000000003280457",
      "fechaAutorizacion": "2024-12-16 12:43:23",
      "fechaRecepcionDocumento": "2024-12-16 12:43:22",
      "estatusDocumento": "Autorizada",
      "infoInteres": ""
    }
  ]
}

 

Campo Descripción
codigo Código de respuesta HTTP (Ej: 200 para éxito).
total Cantidad de documentos encontrados en el rango solicitado.
tipoDocumento Código del documento (01=Factura, 04=Nota de Crédito, etc.).
cufe Código Único de Factura Electrónica. Es la llave de 66 caracteres que identifica el documento ante la DGI.
qr URL oficial de la DGI para la consulta pública del documento.
estatusDocumento Estado actual en la plataforma (Autorizada, Rechazada).
numeroProtocoloAutorizacion Número único asignado por el PAC (The Factory HKA) al autorizar el documento.

💡 Recomendaciones para Desarrolladores

  1. Consultas de un solo día: Si solo necesita los documentos de hoy, puede enviar únicamente la fechaFin. El sistema buscará desde las 00:00:00 hasta las 23:59:59 de dicha fecha.

  2. Formato de hora: Aunque el sistema completa la hora automáticamente, usted puede enviar el formato YYYY-MM-DD HH:MM:SS para obtener rangos específicos (ej. cortes de turno).

  3. Manejo de Rangos Largos: Si requiere reportes de 30 días o más, su integración debe realizar solicitudes en bloques de máximo 7 días de forma secuencial.

¿Deseas que prepare una nota informativa para los clientes que actualmente tienen integraciones activas, explicándoles que deben ajustar sus rangos de consulta a un máximo de 7 días?



 

 

Artículos relacionados