Cargar la representación gráfica PDF

El método CargarPDF permite cargar el archivo PDF correspondiente a un documento electrónico existente en la plataforma. Este archivo se asocia a la transacción para que pueda utilizarse como representación gráfica y adjuntarse automáticamente al correo electrónico enviado al adquiriente.

POST https://micro.conexusit.com/corp/demo/api/Service.svc/CargarPdf

Endpoint

Dato	Valor
Método HTTP	POST
Operación	CargarPdf

Requisito previo

Para utilizar este método, es necesario tener habilitada la opción externoPDF.

Esta configuración indica que el sistema utilizará un archivo PDF externo como representación gráfica del documento, en lugar de generar dicha representación internamente.

Parámetros de entrada

El método recibe la información necesaria para asociar un archivo PDF a una transacción existente. El archivo puede suministrarse de una de las siguientes formas:

• Contenido en Base64: se envía el archivo PDF codificado en Base64.
• URL de descarga: se proporciona una dirección desde la cual el servicio puede descargar el archivo PDF.

Se debe enviar al menos una de estas dos opciones: contenido o urlDescarga.

Estructura de la solicitud

La solicitud debe enviarse con la siguiente estructura:

{
  "documento": {
    "guidEmpresa": "",
    "codigoTransaccion": "",
    "periodo": "",
    "contenido": "",
    "urlDescarga": "",
    "nombreArchivo": "",
    "IsBilling": true
  }
}

Descripción de los parámetros

Parámetro	Tipo	Obligatorio	Descripción
guidEmpresa	string	Sí	GUID que identifica a la empresa emisora.
codigoTransaccion	string	Sí	Código que identifica el documento electrónico, como el CUFE, CUDE o un identificador interno válido.
periodo	string	Sí	Período asociado al documento, en formato yyyyMM.
contenido	string	Condicional	Archivo PDF codificado en Base64. Obligatorio si no se envía urlDescarga.
urlDescarga	string	Condicional	URL desde la cual el servicio puede descargar el archivo PDF. Obligatorio si no se envía contenido.
nombreArchivo	string	No	Nombre del archivo PDF.
IsBilling	boolean	Sí	true: facturación y documentos equivalentes. false: nómina electrónica.

Importante

Se debe informar al menos uno de los siguientes campos:

• contenido: archivo PDF codificado en Base64.
• urlDescarga: URL de descarga del archivo PDF.

No es necesario enviar ambos campos con información al mismo tiempo.

Ejemplo de solicitud

Envío mediante Base64

En este ejemplo, el archivo PDF se envía codificado en Base64 en el campo contenido.

{
  "documento": {
    "guidEmpresa": "12345678-ABCD-1234-ABCD-123456789ABC",
    "codigoTransaccion": "CUFE123456789",
    "periodo": "202401",
    "contenido": "JVBERi0xLjQKJcfs...",
    "urlDescarga": "",
    "nombreArchivo": "factura_123.pdf",
    "IsBilling": true
  }
}

Envío mediante URL

En este ejemplo, el servicio obtiene el archivo PDF desde la URL indicada en urlDescarga.

{
  "documento": {
    "guidEmpresa": "12345678-ABCD-1234-ABCD-123456789ABC",
    "codigoTransaccion": "CUFE123456789",
    "periodo": "202401",
    "contenido": "",
    "urlDescarga": "https://midominio.com/factura_123.pdf",
    "nombreArchivo": "factura_123.pdf",
    "IsBilling": true
  }
}

Estructura de la respuesta

El método devuelve un ResponseType. En la carga del PDF los campos relevantes son CodResp, CodigoTransaccion, DetalleRespuesta, Detalles y TipoTransaccion.

Ejemplo de respuesta

{
  "CargarPDFResult": {
    "CodQR": null,
    "Base64QR": null,
    "CodResp": "OK",
    "CodigoTransaccion": "a967a5a947e535774290fdcce2ba6b37c9bdb7e0680c5171042c6e2784f095294cbc524a1b5916637a60c3b660f9409e",
    "NumeroTransaccion": "",
    "DetalleRespuesta": "El archivo PDF fue actualizado correctamente.",
    "Detalles": "El PDF fue actualizado correctamente, el sistema enviara esa representación grafica al comprador.",
    "IdTransaccion": 0,
    "PDFBase64": "",
    "Proceso": [],
    "Suscripciones": null,
    "EmailEstado": null,
    "TipoTransaccion": "RECIB",
    "XML": "",
    "FechaValidacion": null
  }
}

Campos de la respuesta

Campo	Descripción
CodResp	Código de respuesta de la operación. En el ejemplo, OK indica que la carga se realizó correctamente.
CodigoTransaccion	Identificador asociado al documento procesado.
DetalleRespuesta	Mensaje resumido con el resultado de la operación.
Detalles	Descripción detallada del resultado de la operación.
TipoTransaccion	Tipo de transacción reportado en la respuesta.
PDFBase64	Contenido PDF codificado en Base64, si es retornado por el servicio. Puede venir vacío.
EmailEstado	Información sobre el estado del envío de correo, si aplica.
CodQR	Campo relacionado con el código QR de la representación gráfica.
Base64QR	Campo relacionado con el contenido del código QR en Base64.
NumeroTransaccion	Número de transacción reportado por el servicio.
IdTransaccion	Identificador numérico de la transacción.
Proceso	Lista de procesos reportados por el servicio.
Suscripciones	Información de suscripciones, si aplica.
XML	Contenido XML reportado por el servicio, si aplica.
FechaValidacion	Fecha de validación reportada por el servicio, si aplica.

Comportamiento del método

Carga exitosa

Cuando la operación se completa correctamente:

• El archivo PDF queda asociado al documento correspondiente.
• El sistema utiliza el archivo cargado como representación gráfica, de acuerdo con la configuración externoPDF.
• El PDF queda disponible para ser adjuntado al correo electrónico enviado al adquiriente, según el flujo de procesamiento del sistema.

Error en la operación

Si ocurre un error durante la carga o asociación del archivo, el resultado debe revisarse en los campos CodResp, DetalleRespuesta y Detalles.

Consideraciones importantes

• Identificación del documento: el campo codigoTransaccion debe corresponder a un documento válido y coincidir con la transacción a la que se asociará el PDF.
• Formato del archivo: el contenido suministrado debe corresponder a un archivo PDF válido.
• Tamaño del request: el envío del archivo en Base64 incrementa el tamaño de la solicitud. Según la especificación suministrada, se debe considerar un tamaño máximo de 10 MB.
• Acceso a la URL: si se utiliza urlDescarga, la dirección debe ser accesible desde el servicio que realiza la descarga.
• Configuración previa: se debe verificar que la opción externoPDF esté habilitada para la empresa o el contexto correspondiente.
• Envío al adquiriente: la carga del PDF permite utilizarlo como representación gráfica para el correo electrónico; el envío efectivo depende del flujo de procesamiento y de la configuración del sistema.