Caracteristicas adicionales - Indice Manual Integración Directa

Caracteristicas adicionales

Uso de campos extras

El arreglo “extras” permite incorporar campos opcionales que se insertarán en el XML-Invoice y en la representación impresa según se desee.

Los campos extras no son obligatorios por la DIAN, pero en ciertos casos son importantes y necesarios en el modelo de negocio del emisor. Estos incorporan información adicional dentro del documento, como por ejemplo, detalles del pago, la entrega, el transporte, coordenadas geográficas, lote de productos, vencimiento de la mercancía, servicios médicos, servicios aeronáuticos, información libre, entre muchos otros.

Los campos extensibles están diseñados según parámetros establecidos en la Cámara Colombiana de Comercio Electrónico y la DIAN, con el propósito de ser interoperables (esto aún no está definido en su totalidad para el modelo de validación previa). La información a insertar en un campo extensible debe cumplir con criterios asociados al campo específico a insertar. La estructura del objeto “extras” es la siguiente:

Tipo	Identificador	Formato	Descripción
String	controlInterno1	AN|100	Etiqueta asignada para la Representación Impresa PDF.
	controlInterno2	Depende del campo	Permite asociar dos o más campos mediante un índice (si los campos son asociables)
	nombre		Código del campo extensible a referenciar (existen códigos definidos por TFHKA para información especifica y también pueden usarse códigos libres)
	pdf	N|1	Indicación de mostrar el campo en la representación gráfica PDF (“0” = No mostrar / “1” = Mostrar)
	valor	Depende del campo	Valor del campo a agregar.
	xml	N|1	Indicación de mostrar el campo en el XML (“0” = No mostrar / “1” = Mostrar)

Ejemplo de uso de Campos Extensible 443 (Vendedor)
<ser:Extras> <ser:controlInterno1>Vendedor</ser:controlInterno1> <ser:controlInterno2></ser:controlInterno2> <ser:nombre>443</ser:nombre> <ser:pdf>1</ser:pdf> <ser:valor>Pablo Marmol</ser:valor> <ser:xml>0</ser:xml> </ser:Extras>
Campo Insertado en el PDF
IMAGEN

@IMPORTANTE: Se recomienda que la propiedad Extras.xml se coloque con el valor ‘0’, ya que The Factory HKA implementa el uso de CDATAS anidados en la estructura del XML para reflejar los campos extras, sin embargo algunas plataformas de recepción no pueden interpretar este estándar y pueden existir rechazos al momento de radicar el documento si a esta propiedad se le asignan al valor ‘1’

La etiqueta que se asigne en Extras.ControlInterno1 es de libre elección, mientras se respete el formato estipulado. Sin embargo, será necesario conocer los demás parámetros, que serán suministrados con los campos disponibles:

• El código del campo, para colocar en Extras.nombre.
• Si el campo es repetible y asociable, para colocar un índice común en Extras.ControlInterno2.
• El formato del valor del campo, para que la información que se coloque Extras.valor sea válida.

Además de los campos disponibles (códigos reservados por TFHKA), se ha contemplado el uso de campos LIBRES, para insertar identificadores y valores genéricos. Este campo es repetible.

Note el siguiente ejemplo para insertar un campo libre:

Ejemplo
<ser:Extras> <ser:controlInterno1>LISTA DE PRECIOS</ser:controlInterno1> <ser:controlInterno2</ser:controlInterno2> <ser:nombre>1</ser:nombre> <ser:pdf>1</ser:pdf> <ser:valor>MAYORISTA</ser:valor> <ser:xml>0</ser:xml> </ser:Extras>
Campo Insertado en el PDF
IMAGEN2

Tabla de códigos para campos extras

En este momento los códigos ó propiedad Extras.nombre para campos extras reservados por TFHKA (cualquier otro código utilizado es considerado como libre) son los siguientes:

Campos Extensibles reservados por TFHKA

Código	Etiqueta PDF	Descripción	Formato de valor	Observaciones
122333	Aceptación Física	Aceptación Física	AN|1000
100200	Pie de página	Pie de página	AN|1000
5170000	Total Base Excluida	Total Base Excluida	Formato Libre	Para totales el R.G
5170001	TOTAL Descuento Detalle	TOTAL Descuento Detalle	Formato Libre	Para totales el R.G
5170002	TOTAL Retenciones	TOTAL Retenciones	Formato Libre	Para totales el R.G
5170003	TOTAL a Pagar	TOTAL a Pagar	Formato Libre	Para totales el R.G
5170004	TOTAL A PAGAR en Letras	TOTAL A PAGAR en Letras	Formato Libre	Para totales el R.G

@IMPORTANTE: El campo Aceptación Física se puede aplicar en dos escenarios. El primer escenario, en donde la factura es aceptada tácitamente y solo el XML es generado (el archivo PDF no se genera en nuestra plataforma), asumiendo que la entrega de la representación gráfica es responsabilidad del usuario. El segundo escenario, en el cual la factura es aceptado tácitamente y se genera el XML y el PDF en nuestra plataforma, los cuales serán enviados vía correo electrónico si el campo “notificar” se encuentra seteado en “SI”. Para este último escenario, es necesario que el campo “controlInterno2” se encuentre en “1”.

ADVERTENCIA: Si utiliza la opción controlInterno2 = "", nuestra plataforma no generará representación estándar HKA, por lo tanto no se aloja PDF en la misma y no se podrá visualizar la representación gráfica desde el portal, en el correo del adquiriente (sección visualizar documento), realizar la descarga a través del método DescargaPDF del servicio ni reenviar la misma a través del método EnvioCorreo.

Ejemplo del uso del campo extensible 122333 en el XML
<ser:Extras> <ser:controlInterno1/> <ser:controlInterno2>1<ser:controlInterno2> <ser:nombre>122333</ser:nombre> <ser:pdf>0</ser:pdf> <ser:valor>1</ser:valor> <ser:xml>0</ser:xml> </ser:Extras>

Correo electrónico personalizado

El arreglo “extras” también permite manejar algunas funcionalidades especiales de la plataforma, como la de correo electrónico personalizado. Para que esta información no aparezca en la representación gráfica, el parámetro pdf del objeto “extras” debe ir en “0”.

@IMPORTANTE: Se recomienda que la propiedad Extras.xml se coloque con el valor ‘0’, ya que The Factory HKA implementa el uso de CDATAS anidados en la estructura del XML para reflejar los campos extras, sin embargo algunas plataformas de recepción no pueden interpretar este estándar y pueden existir rechazos al momento de radicar el documento si a esta propiedad se le asignan el valor ‘1’

@IMPORTANTE: Se recomienda que la propiedad Extras.pdf se coloque con el valor ‘0’, con el fin de que la información indicada no se visualice en la representación gráfica estándar. La funcionalidad de correo electrónico personalizado permite configurar transacción a transacción el asunto, la dirección de respuesta y el cuerpo del correo electrónico. La vía para exponer esta información será a través de campos extras.

Campos Extensibles para Correo Electrónico Personalizado

Código	Etiqueta PDF	Descripción	Formato de valor	Observaciones
11	Cuerpo del Correo Electrónico	Cuerpo del Correo Electrónico	AN | 1000	String que contiene el código html del cuerpo del email.
13	Asunto del Correo Electrónico	Asunto del Correo Electrónico	AN | 100	Definido en el Anexo Técnico V1.7-2020 de la DIAN**
14	Responder a	Responder a	AN | 100	Debe colocarse una única dirección de email
1700	Linea de Negocio	Linea de Negocio	AN|100	(Opcional) Inclusión de línea de negocio en el asunto del correo

** El asunto debe cumplir con el siguiente formato:

NIT del Facturador Electrónico; Nombre del Facturador Electrónico; Número del Documento Electrónico; Código del tipo de documento según Tabla 1; Nombre comercial del facturador; Linea de negocio (este ultimo opcional, acuerdo comercial entre las partes).

Ejemplo de uso de Campos Extensibles 11,13 y 14 para personalizar el Correo Electrónico

<ser:extras> <ser:Extras> <ser:controlInterno1>Cuerpo del Correo Electrónico</ser:controlInterno1> <ser:controlInterno2></ser:controlInterno2> <ser:nombre>11</ser:nombre> <ser:pdf>0</ser:pdf> <ser:valor>String de prueba Cuerpo del correo electronico @email.documento.urlAcuseRecibo</ser:valor> <ser:xml>0</ser:xml> </ser:Extras> <ser:Extras> <ser:controlInterno1>Asunto del Correo Electrónico</ser:controlInterno1> <ser:controlInterno2></ser:controlInterno2> <ser:nombre>13</ser:nombre> <ser:pdf>0</ser:pdf> <ser:valor>@email.emisor.razonSocial le ha enviado la @email.documento.tipoDocumento @email.documento.numeroDocumento </ser:valor> <ser:xml>0</ser:xml> </ser:Extras> <ser:Extras> <ser:controlInterno1>Responder a</ser:controlInterno1> <ser:controlInterno2></ser:controlInterno2> <ser:nombre>14</ser:nombre> <ser:pdf>0</ser:pdf> <ser:valor>notificaciones@thefactoryhka.com</ser:valor> <ser:xml>0</ser:xml> </ser:Extras>

Para que el correo electrónico tenga la capacidad de adoptar los datos propios de la transacción, se plantea un juego de variables de código, las cuales serán sustituidas en la plataforma por el valor propio generado en la misma. A continuación se exponen estas variables:

Campos Extensibles para Correo Electrónico Personalizado

Sección	Descriptor	Valor Referencial	Tipo	Ubicación
Datos Factura	Número de Documento Electrónico	@email.documento.numeroDocumento	Único	Asunto/Cuerpo
	CUFE	@email.documento.cufe	Único	Asunto/Cuerpo
	Fecha Emisión	@email.documento.fechaEmision	Único	Asunto/Cuerpo
	Hora de Emisión	@email.documento.horaEmision	Único	Asunto/Cuerpo
	Tipo de Documento Electrónico	@email.documento.tipoDocumento	Único	Asunto/Cuerpo
	Tipo de Factura	@email.documento.tipoFactura	Único	Asunto/Cuerpo
	Responder A	@email.documento.responderA	Único	Cuerpo
Emisor	Tipo Contribuyente	@email.emisor.tipoContribuyente	Único	Asunto/Cuerpo
	Tipo de Documento de Identidad	@email.emisor.tipoIdentidad	Único	Asunto/Cuerpo
	Número de Documento de Identidad	@email.emisor.numeroIdentidad	Único	Asunto/Cuerpo
	Razón Social	@email.emisor.razonSocial	Único	Asunto/Cuerpo
	Logo	@email.emisor.logo	Único	Cuerpo
Adquiriente	Tipo Contribuyente	@email.receptor.tipoContribuyente	Único	Asunto/Cuerpo
	Tipo de Documento de Identidad	@email.receptor.tipoIdentidad	Único	Asunto/Cuerpo
	Número de Documento de Identidad	@email.receptor.numeroIdentidad	Único	Asunto/Cuerpo
	Razón Social	@email.receptor.razonSocial	Único	Asunto/Cuerpo
Acuse	Acuse de Recibo	@email.documento.urlAcuseRecibo	Único	Cuerpo

Ejemplo de String para Cuerpo de correo electrónico en html

<p>Estimado @email.receptor.razonSocial, ha recibido un DOCUMENTO ELECTRÓNICO por parte de @email.emisor.razonSocial; envío que se efectúa mediante el Proveedor Tecnológico The Factory HKA Colombia SAS</p><div style="text-align:center;"><a style=" background-color: #154380; border: 1px solid #ffffff; border-radius: 20px; color: #ffffff; display: inline-block; font-family: sans-serif; font-size: 25px; font-weight: bold; line-height: 60px; text-align: center; text-decoration: none; width: 300px; -webkit-text-size-adjust: none;" class="btn btn-block btn-info" href="@email.documento.urlAcuseRecibo" target="_blank">Acuse de Recibo</a><br></div><br>Por favor revise el documento electrónico e ingrese en el botón de Acuse<br><b>Este E-mail ha sido enviado automáticamente, no responder a esta cuenta. </b><b>@email.advertencia</b><p>La información contenida en este E-mail es confidencial. Si por error recibe este mensaje, favor reenviarlo y borrar</p></div>

@IMPORTANTE: Para que el servicio tome la configuración dinámica del campo “Cuerpo del Correo Electrónico”, el atributo @email.documento.urlAcuseRecibo deberá estar presente.

Generacion de notas con y sin referencia a documento

Para la generación de notas crédito y débito, se describen 3 escenarios:

Notas de crédito y débito que afecten a facturas de validación previa

Para la emisión de notas de crédito y débito deben enviarse obligatoriamente dos arreglos de documentos referenciados, el primero indicando el codigoInterno = '4' el cual corresponde a los motivos por los cuales se genera la NC/ND (DiscrepancyResponse) y un segundo arreglo, indicando el codigoInterno = '5' en el cual se reflejan los datos de la factura afectada por la NC/NC (BillingReference).

Ejemplo:

 <a:documentosReferenciados>
      <a:DocumentoReferenciado>
	<a:codigoEstatusDocumento>2</a:codigoEstatusDocumento>
	<a:codigoInterno>4</a:codigoInterno>			
	<a:descripción>
	   <b:string>Anulación de factura electrónica</b:string>
	</a:descripcion>
	<a:fecha>2019-10-07</a:fecha>
	<a:numeroDocumento>F4PM3</a:numeroDocumento>
	</a:DocumentoReferenciado>
	<a:DocumentoReferenciado>
	<codigoInterno>5</codigoInterno>			<cufeDocReferenciado>85ea749b18ee5bd251b87442935650e30b4e0e4cd662bef1KqmCLKgxPpH6u5LiKrJvTb6FEyfVuoCcV0baab6b59cdc8b3</cufeDocReferenciado>
	<fecha>2019-10-07</fecha>
	<numeroDocumento>F4PM3</numeroDocumento>
	</a:DocumentoReferenciado>
      </a:documentosReferenciados>

@IMPORTANTE: El campo cufeDocReferenciado debe contener un total de 96 caracteres y el valor del campo FacturaGeneral.tipoOperacion debe ser 20 (para NC) y 30 (para ND).

Notas de crédito y débito que no afecten a facturas

Tener en cuenta que en cada escenario se debe indicar correctamente el campo FacturaGeneral.tipoOperacion:

• Código 22 para Notas Crédito.
• Código 32 para Notas Dedito.

De acuerdo a lo descrito en el Anexo Técnico versión 1.8

@IMPORTANTE: La clase Documentos Referenciados debe enviarse en NULL.

Notas de crédito y débito que afecten a facturas emitidas en validación posterior

Para la emisión de notas de crédito y débito deben enviarse obligatoriamente dos arreglos de documentos referenciados, el primero indicando el codigoInterno = '4' el cual corresponde a los motivos por los cuales se genera la NC/ND (DiscrepancyResponse) y un segundo arreglo, indicando el codigoInterno = '5' en el cual se reflejan los datos de la factura afectada por la NC/NC (BillingReference).

Ejemplo:

 <a:documentosReferenciados>
      <a:DocumentoReferenciado>
	<a:codigoEstatusDocumento>2</a:codigoEstatusDocumento>
	<a:codigoInterno>4</a:codigoInterno>			
	<a:descripción>
	   <b:string>Anulación de factura electrónica</b:string>
	</a:descripcion>
	<a:fecha>2019-10-07</a:fecha>
	<a:numeroDocumento>F4PM3</a:numeroDocumento>
	</a:DocumentoReferenciado>
	<a:DocumentoReferenciado>
	<codigoInterno>5</codigoInterno>		
	<cufeDocReferenciado>85ea749b18ee5bd251b87442935650e30b4e0e4c</cufeDocReferenciado>
	<fecha>2019-10-07</fecha>					
	<numeroDocumento>F4PM3</numeroDocumento>
      </a:DocumentoReferenciado>
</a:documentosReferenciados>

@IMPORTANTE: El campo cufeDocReferenciado debe contener un total de 40 caracteres y el valor del campo FacturaGeneral.tipoOperacion debe ser 23 (para NC) y 33 (para ND).

Transmisión de documentos de contingencia tipo 03 (atribuible al emisor)

Los inconvenientes tecnológicos por parte del facturador electrónico implican que la facturación electrónica tenga las siguientes características:

• Generar la facturación con numeración de contingencia en papel o por computador.
• El facturador electrónico deberá generar una carta declarando el inconveniente tegnológico o superación del misma, la cual debe ir firmada por el representante legal de la compañía y remitirla al correo electrónico contingencia.facturadorvp@dian.gov.co con lo siguiente: o Asunto: Nit de la empresa separado con un guion el digito de verificación; Nombre de la empresa.
  • Adjunto: PDF de la carta donde se declaren en contingencia con la firma del representante legal.
  • Cuerpo del correo: Datos de contacto (Nombres, teléfono/Celular de contacto).
    • Nota: Este correo únicamente será para la recepción de correos de los facturadores electrónicos para informar la contingencia o superación de los inconvenientes tecnológicos.
    • Nota: Adicionalmente, si quieren entregar estas constancias por escrito lo pueden realizar a través de radicados, el cual deberá remitirse a la DIAN - nivel central - factura electrónica.
• El facturador tendrá 48 horas a partir de la fecha en que supera la contingencia para transmitir las facturas electrónicas en formato XML a la DIAN.
• Las facturas electrónicas generadas y emitidas en contingencia pasarán la malla de validaciones de anexo, es decir, la DIAN responderá con un Application Response de Documento Validado por la DIAN, que informará las notificaciones a que haya lugar.
• Una vez el facturador electrónico salga de contingencia deberá proceder al proceso de generación normal.
• Para los documentos de notas crédito y notas débito, el facturador NO debe usar la numeración de contingencia, sino el consecutivo propio normal. Las notas enviadas a la DIAN se validarán de manera normal en la DIAN. Por lo anterior, no existe el concepto de nota en contingencia, por lo que debe cuidarse enviar primeramente las Facturas de Contingencia antes de generar notas sobre las mismas y se recomienda generarlas en un ambiente de operación normal.

¿Cómo transmitir un documento de contingencia Tipo 03?

La transmisión del documento se realiza por medio del método Enviar del Web Service de Emisión que brinda The Factory HKA, indicando el atributo tipoDocumento del objeto FacturaGeneral igual a ‘03’ y enviar en la sección de documentosReferenciados un objeto de tipo DocumentosReferenciados indicando lo siguiente:

• codigoInterno = ‘1’
• fecha = ‘Fecha de emisión del documento de contingencia’
• numeroDocumento = ‘número del consecutivo del documento de contingencia emitido’
• tipoCodigoDocumento = ‘Tipo de documento de soporte del proceso de facturación por contingencias atribuibles al facturador electrónico a transmitir, según lo estipulado en el numeral 12.1.4 de la versión 1.8 del Anexo Técnico de la DIAN ’.

Tipos de documentos de soporte del proceso de facturación por contingencias atribuibles al facturador electrónico

Código	Descripción
FTC	Factura Talonario Contingencia
FTP	Factura Talonario Papel
FTPC	Factura Talonario por Computador

¿Cuál será el código de respuesta de transmisión exitosa que retornará el WS de TFHKA?

El método Enviar retornará código 201 ó 208 ante la recepción exitosa del documento en nuestra plataforma, con el siguiente mensaje: “El documento se recibió como Documento Electronico de Contingenia Tipo 03, este se entregará de manera asíncrona a la DIAN, para más información favor consumir EstadoDocumento luego de 48 horas.” En dicho Response se contará con CUDE y UBL.

¿Cuándo puedo consultar el resultado de la transmisión del documento hacia la DIAN?

Pasadas 48 horas luego de la radicación del documento en la plataforma, pueden consultar el estatus del mismo para conocer el resultado de la transacción ante la DIAN.+

Generación de código QR de respuesta rápida para facturas de contingencia

Para la generación del Código de respuesta rápido – Código QR, en los casos que la factura de venta de talonario o de papel se genere a través de sistemas informáticos electrónicos deberan corresponder a la siguiente tabla:

Detalle
NumFac: [NUMERO_FACTURA]
FecFac: [FECHA_FACTURA]
HorFac: [HORA_FACTURA(con GMT)]
NitFac: [NIT FACTURADOR]
DocAdq: [NUMERO_ID_ADQUIRIENTE]
ValFac: [VALOR_FACTURA]
ValIva: [VALOR_IVA]
ValOtroIm: [VALOR_OTROS_IMPUESTOS]
ValTolFac: [VALOR_TOTAL_FACTURA]

Ejemplo

NumFac: CTG2
FecFac: 2020-06-16
HorFac: 00:00:00-05:00
NitFac: 900390126
DocAdq: 901041710
ValFac: 1003.00
ValIva: 190.57
ValOtroIm: 0.00
ValTolFac: 1193.57

Ejemplo SOAP Request de Factura de Contingencia Tipo 03:

@IMPORTANTE: No es requerido que se notifique a los adquiriente los documentos de contingencia transmitidos a la DIAN, ya que el documento entregado físicamente al mismo durante el período en que mantuvo la contingencia, corresponde al documento legal de la transacción realizada. La transmisión de dicha información a la DIAN es con el fin de notificar al ente regulador las transacciones realizadas durante dicho periodo. Por lo anteriormente descrito, se recomienda enviar el campo notificar = ‘NO’ y no realizar el envío de la información correspondiente al Destinatario:

Notas a documentos en contingencia

Como se mencionó anteriormente, las notas de crédito o débito no tienen esquema de contingencia, por lo tanto las mismas se deben generar en la operación normal. Partiendo de este principio, surgen los siguientes escenarios:

1. Si la nota a emitir se expide electrónicamente:

   a. Afectando a una factura electrónica: Se realiza la emisión de la nota en operación normal de facturación, tomando en cuenta informar la referencia a documentos en el atributo documentosReferenciados del objeto FacturaGeneral, enviando dos objetos de tipo DocumentosReferenciados indicando lo siguiente:

   i. Objeto 1 (para generar DiscrepancyResponse): los campos codigoEstatusDocumento; codigoInterno=‘4’ y cufeDocReferenciado.

   ii. Objeto 2 (para generar Billingreference): los campos codigoInterno=‘5’; cufeDocReferenciado; fecha; tipoCUFE y numeroDocumento.

   b. Afectando a una factura de contingencia: La emisión de la nota en este escenario dependerá de:

   i. Factura de Contingencia se encuentra transmitida a la DIAN: Se realiza la emisión de la nota en operación normal de facturación, tomando en cuenta informar la referencia a documentos en el atributo documentosReferenciados del objeto FacturaGeneral, enviando dos objetos de tipo DocumentosReferenciados indicando lo siguiente:

   Objeto 1 (para generar DiscrepancyResponse): los campos codigoEstatusDocumento; codigoInterno=‘4’ y cufeDocReferenciado=’CUDE del documento’.

   Objeto 2 (para generar Billingreference): los campos codigoInterno=‘5’; cufeDocReferenciado=’CUDE del documento’; fecha; tipoCUFE y numeroDocumento.

   i. Factura de contingencia no se ha transmitido a la DIAN: Se realiza la emisión de la nota “en contingencia” (indicando consecutivo y fecha de expedición de la factura afectada), con compromiso de entrega posterior a la DIAN, sincronizada con la radicación de la factura de contingencia ante el ente.

2. Si la nota a emitir se expide “en contingencia”:

   a. Afectando a una factura electrónica: Se realiza la emisión de la nota “en contingencia” (indicando consecutivo y fecha de expedición de la factura afectada), con compromiso de entrega posterior a la DIAN, sincronizada con la radicación de la factura de contingencia ante el ente.

   b. Afectando a una factura de contingencia: Se realiza la emisión de la nota “en contingencia” (indicando consecutivo y fecha de expedición de la factura afectada), con compromiso de entrega posterior a la DIAN, sincronizada con la radicación de la factura de contingencia ante el ente.