Cargar anexos o documentos adicionales

El método CargarAnexo permite adjuntar archivos adicionales a un documento electrónico existente en la plataforma. Estos archivos pueden enviarse al adquiriente junto con la factura, ya sea incluidos dentro del archivo ZIP del documento electrónico o como archivos adjuntos independientes en el correo electrónico.

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

Endpoint

Dato	Valor
Método HTTP	POST
Operación	CargarAnexo

Requisito previo

Para utilizar este método, es necesario indicar al generar el documento electrónico que se incluirá un anexo.

Campo de configuración en la factura

El campo EncabezadoData.AdjuntarAnexo debe configurarse de acuerdo con el comportamiento esperado para el envío del documento.

Valor	Comportamiento
true	El sistema dejará el envío del correo en espera hasta que se cargue el anexo mediante el método CargarAnexo.
false	El sistema enviará el documento sin esperar la carga de un anexo.

Importante

Si el documento se genera con EncabezadoData.AdjuntarAnexo = true, el envío del correo electrónico quedará pendiente hasta que se ejecute correctamente el método CargarAnexo.

Parámetros de entrada

El método recibe la información de un archivo anexo y lo asocia a un documento electrónico previamente generado en la plataforma.

El archivo puede suministrarse de las siguientes formas:

• Contenido en Base64: se envía el archivo codificado en Base64 en el campo contenido.
• URL de descarga: se proporciona una dirección desde la cual el servicio puede obtener el archivo mediante el campo urlDescarga.

Además, el parámetro externo determina cómo se incorporará el archivo al envío del documento electrónico.

Estructura de la solicitud

La solicitud debe enviarse con la siguiente estructura:

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

Descripción de los parámetros

Parámetro	Tipo	Obligatorio	Descripción
guidEmpresa	string	Sí	Identificador GUID de la empresa emisora del documento.
codigoTransaccion	string	Sí	Código que identifica el documento electrónico, como el CUFE, CUDE o identificador válido de la transacción.
periodo	string	Sí	Período asociado al documento, en formato yyyyMM.
extension	string	Sí	Extensión del archivo sin el punto inicial. Por ejemplo: pdf, zip, json o txt.
externo	boolean	Sí	Indica si el archivo se enviará como adjunto independiente (true) o dentro del ZIP del documento electrónico (false).
contenido	string	Condicional	Archivo anexo codificado en Base64. Obligatorio si no se envía urlDescarga.
urlDescarga	string	Condicional	URL desde la cual el servicio puede descargar el archivo anexo. Obligatorio si no se envía contenido.
nombreArchivo	string	Sí	Nombre del archivo que se adjuntará al documento electrónico.
IsBilling	boolean	Sí	true: facturación y documentos equivalentes. false: nómina electrónica.

Contenido del archivo

Se debe proporcionar al menos uno de los siguientes campos:

• contenido: archivo codificado en Base64.
• urlDescarga: URL desde la cual se obtiene el archivo.

No es necesario enviar ambos campos con información simultáneamente.

Comportamiento del campo externo

El valor del parámetro externo determina cómo se incorpora el anexo al documento electrónico y a su envío.

Valor	Comportamiento
false	El archivo se incluye dentro del ZIP del documento electrónico.
true	El archivo se envía como un adjunto independiente al correo electrónico.

Ejemplo de solicitud

Envío del anexo mediante Base64

En este ejemplo, el archivo se envía codificado en Base64 y se incluye dentro del ZIP del documento electrónico, ya que externo está configurado en false.

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

Envío de un archivo como adjunto independiente

En este ejemplo, el archivo se envía codificado en Base64 y se incorpora como adjunto independiente al correo electrónico, ya que externo está configurado en true.

{
  "documento": {
    "guidEmpresa": "12345678-ABCD-1234-ABCD-123456789ABC",
    "codigoTransaccion": "CUFE123456789",
    "periodo": "202401",
    "extension": "zip",
    "externo": true,
    "contenido": "UEsDBBQAAAA...",
    "urlDescarga": "",
    "nombreArchivo": "anexos_salud.zip",
    "IsBilling": true
  }
}

Estructura de la respuesta

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

Ejemplo de respuesta

{
  "CargarAnexoResult": {
    "CodQR": null,
    "Base64QR": null,
    "CodResp": "OK",
    "CodigoTransaccion": "0e0872afa6e67e0203099e08cd5755b4ea558ed89736cba627282eb798018e1f8c60bf2a9c81c61f776c0d6cd5351d84",
    "NumeroTransaccion": "",
    "DetalleRespuesta": "El archivo Anexo fue registrado correctamente.",
    "Detalles": "El Anexo fue registrado correctamente, lo adjuntará al correo enviado al cliente.",
    "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 el anexo fue registrado correctamente.
CodigoTransaccion	Identificador asociado al documento procesado.
DetalleRespuesta	Mensaje resumido con el resultado de la operación.
Detalles	Descripción detallada del resultado del registro del anexo.
TipoTransaccion	Tipo de transacción reportado por el servicio.
EmailEstado	Información sobre el estado del envío del correo electrónico, si aplica.
CodQR	Campo relacionado con el código QR del documento.
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.
PDFBase64	Contenido PDF en Base64, si es retornado por el servicio.
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

Registro exitoso del anexo

Cuando el anexo se registra correctamente:

• El archivo queda asociado al documento electrónico correspondiente.
• Si el documento fue generado con AdjuntarAnexo = true, el sistema podrá continuar con el flujo de envío del correo una vez cargado el anexo.
• El archivo se incorpora al envío de acuerdo con el valor del parámetro externo:
  • Dentro del ZIP del documento electrónico, si externo = false.
  • Como adjunto independiente del correo electrónico, si externo = true.

Error en la operación

Si ocurre un error durante el registro del anexo, se deben revisar los campos CodResp, DetalleRespuesta y Detalles de la respuesta para identificar el resultado reportado por el servicio.

Consideraciones importantes

• Documento existente: el documento electrónico debe estar registrado previamente en la plataforma.
• Configuración del anexo: para que el envío del correo quede pendiente hasta la carga del archivo, la factura debe generarse con EncabezadoData.AdjuntarAnexo = true.
• Continuidad del envío: si el documento está pendiente por la carga del anexo, se debe ejecutar CargarAnexo para permitir que continúe el flujo de envío.
• Codificación: cuando se utiliza contenido, el archivo debe estar correctamente codificado en Base64.
• Acceso a la URL: si se utiliza urlDescarga, la dirección debe ser accesible desde el servicio que realiza la descarga.
• Nombre y extensión: nombreArchivo y extension deben corresponder al archivo suministrado.
• Tipo de adjunto: se debe configurar correctamente externo según se requiera incluir el archivo dentro del ZIP o enviarlo como adjunto independiente.