Manual DLL hkafact21 - Emisión V4

Objetivo

El presente manual tiene como propósito dar a conocer los detalles de los cambios a nivel del consumo de la librería HKAFACT21 para validación previa respecto a la versión del modelo de facturación de validación posterior (HKAFACT).

Alcance

El presente documento abarca desde la instalación de la API hasta las funciones utilizables para el consumo del Servicio Web de Integración para el modelo de facturación de validación previa. La librería hkafact21 es compatible con cualquier desarrollo cuya base sea plataformas WIN32

Nota: En el mismo se describen cada uno de los strings que constituyen el objeto factura. Para obtener mayor información sobre la obligatoriedad de los campos (requeridos/opcionales) ver MANUAL DE INTEGRACION DIRECTA (EMISIÓN - VAL. PREVIA)

Definiciones y Términos

• C++: lenguaje de programación diseñado para extender al lenguaje de programación C con mecanismos que permiten la manipulación de objetos. En ese sentido, desde el punto de vista de los lenguajes orientados a objetos, el C++ es un lenguaje híbrido, con la particularidad de poder redefinir los operadores, y de crear nuevos tipos que se comporten como tipos fundamentales.
• DLL: Biblioteca de enlace dinámico o más comúnmente DLL (sigla en inglés de dynamic-link library) es el término con el que se refiere a los archivos con código ejecutable que se cargan bajo demanda de un programa por parte del sistema operativo.
• SDK: Un kit de desarrollo de software es un conjunto de herramientas de desarrollo de software que le permite al programador o desarrollador de software crear una aplicación informática para un sistema concreto.
• Servicio Web de Integración: Servicio Web de The Factory HKA Colombia SAS puesto a disposición a propietarios de software administrativos o de gestión para la generación de factura electrónica.

Procedimiento

Instalación: En el SDK descargado, se encontrará con tres herramientas; la librería de integración (hkafact21.dll), el presente manual y un demo funcional de código. Antes de comenzar a hacer uso de la librería en el desarrollo, lo primero que se debe hacer es registrar y referenciar la librería en nuestro proyecto. Esto se consigue siguiendo los siguientes pasos:

1. Creamos una nueva carpeta.
2. Descomprimimos el contenido del SDK en la capeta previamente creada.
3. Copiamos la librería hkafact21.dll.
4. Pegamos la librería en la carpeta System32 de Windows.
5. Finalmente, declaramos las distintas funciones a utilizar de la librería.

@IMPORTANTE:

1. En el caso de que al final de la cadena (Identificador), el campo se encuentre vacío se debe agregar un pipe “|” al final.
2. Si el identificador no es obligatorio, este pueden enviarse con el identificador seguido de un pipe (Ejemplo: ID02A = "02A|").
3. Si los identificadores son repetibles puede concatenarse con el separador “% “seguido del identificador con los campos correspondientes a la cadena que desea repetir.

MÉTODO ENVIAR

Función que permite generar el documento electrónico.

Declaración

 INT Enviar (string URL, string tokenEmpresa, string tokenPassword, string DatosCliente, string FacturaGlobal, string AnticAutCargDesc, string CpDr, string EntMerc, string ImpuestosFactura, string MpOcTe, string TcTcaIa, string DetalleDeFactura , string Extras, string Adjuntos, string SectorSalud, bool debugMode)

String URL

• URL del servicio de emisión.

String tokenEmpresa

• Token asignado por la plataforma de TFHKA.

String tokenPassword

Token asignado por la plataforma de TFHKA.

String datosCliente

Datos que componen la información del adquiriente.

Cliente_DatosGenerales

(20 Campos, 19 pipes “|”):

ID01= "01"
|nombreRazonSocial|tipoPersona|segundoNombre|apellido|numeroDocumento|tipoIdentificacion
|email|telefono|notificar|actividadEconomicaCIIU|nombreComercial|nombreContacto
|nota|numeroIdentificacionDV
|telefax|Extensible1.controlInterno1|
Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

Cliente_Destinatario

(11 Campos, 9 pipes “|”):

ID01B= "01A"
|CanalDeEntrega|email|fechaProgramada|mensajePersonalizado|nitProveedorReceptor
|telefono|Extensible1.controlInterno1|Extensible1.controlInterno2
|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

Cliente_DetallesTributarios

(6 Campos, 5 pipes “|”):

ID01B= "01B"
|codigoImpuesto|Extensible1.controlInterno1|Extensible1.controlInterno2
|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

Cliente_InformacionLegal

(8 Campos, 7 pipes “|”):

ID01E= "01E"
|codigoEstablecimiento|nombreRegistroRUT|numeroIdentificacion|numeroIdentificacionDV|
numeroMatriculaMercantil|prefijoFacturacion|tipoIdentificacion

Cliente_ResponsabilidadesRut

(7 Campos, 6 pipes “|”):

ID01F= "01F"
|obligaciones|regimen|Extensible1.controlInterno1|Extensible1.controlInterno2
|Extensible1.nombre|Extensible1.valor
|prefijoFacturacion|tipoIdentificacion

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

DireccionCliente

(30 Campos, 29 pipes “|”):

ID01C= "01C"
|aCuidadoDe|aLaAtenciónDe|bloque|buzon|calle|calleAdicional|ciudad|codigoDepartamento|
correccionHusoHorario|departamento|departamentoOrg|direccion|distrito|habitacion|lenguaje
|municipio|nombreEdificio|numeroEdificio|numeroParcela|pais|piso|region|subDivision|ubicación
|zonaPostal|Extensible1.controlInterno1|Extensible1.controlInterno2|
Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

DireccionFiscalCliente

(30 Campos, 29 pipes “|”):

ID01D= "01D"
|aCuidadoDe|aLaAtenciónDe|bloque|buzon|calle|calleAdicional|ciudad|codigoDepartamento
|correccionHusoHorario|departamento|departamentoOrg|direccion|distrito|habitacion|lenguaje
|municipio|nombreEdificio|numeroEdificio|numeroParcela|pais|piso|region|subDivision|ubicación
|zonaPostal|Extensible1.controlInterno1|Extensible1.controlInterno2
|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

datos_Cliente= ID01 %ID01A%ID01B%ID01E%ID01F%%ID01C %%ID01D

OBSERVACIONES:

• Los identificadores 01A, 01B, 01F son repetibles

String FacturaGlobalL

Datos generales del objeto factura.

FacturaGlobal

(23 Campos, 22 pipes “|”):

datos_factura= "02"
|tipoDocumento|consecutivoDocumento|rangoNumeracion|fechaEmision|fechaVencimiento|moneda
|propina|totalDescuentos|totalSinImpuestos|totalMonto|cantidadDecimales|fechaFinPeriodoFacturacion
|fechaInicioPeriodoFacturacion|fechaPagoImpuestos|redondeoAplicado|tipoOperacion|
totalAnticipos|totalBaseImponible|totalBrutoConImpuesto|totalCargosAplicados
|totalProductos|tipoSector

String AnticAutCargDesc

Anticipos, autorizaciones, Cargos y descuentos aplicados en el comprobante.

Anticipos

(11 Campos, 10 pipes “|”):

ID02A= "02A"
|fechaDeRecibido|fechadePago|horaDePago|id|instrucciones|montoPagado|
Extensible1.controlInterno1
|Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

Autorizado

(15 Campos, 14 pipes “|”):

ID02B= "02B"
|email|nombreComercial|nombreContacto|nota|numeroDocumento|numeroDocumentoDV
|razonSocial|telefax|telefono|tipoIdentificacion|Extensible1.controlInterno1
|Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

cargosDescuentos

(12 Campos, 11 pipes “|”):

ID02C= "02C"
|codigo|descripcion|indicador|monto|montoBase|porcentaje|secuencia|Extensible1.controlInterno1
|Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

AnticAutCargDesc = ID02A %%ID02B %%ID02C%%

OBSERVACIONES:

• Los identificadores 02A, 02B son repetibles

String CpDr

Condiciones de pago y documentos referenciados para el comprobante.

CondicionPago

(20 Campos, 19 pipes “|”):

ID02D= "02D"
|codigoEvento|comentario|duracionPeriodo|duracionPeriodoMedida|fechaVencimiento|identificador
|medioPagoAsociado|monto|montoMulta|montoPenalidad|periodoDesde|periodoHasta|porcentajeDescuento
|porcentajePago|referenciaAnticipo|Extensible1.controlInterno1|
Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

DocumentosReferenciados

(18 Campos, 17 pipes “|”): Puedo no enviarse 02E1

ID02E= "02E"
|codigoEstatusDocumento|codigoInterno|cufeDocReferenciado|fecha|fechaFinValidez|fechaInicioValidez
|numeroDocumento|tipoCUFE|tipoDocumento|tipoDocumentoCodigo|Extensible1.controlInterno1|
Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor|conceptoRecaudo|
monto|numeroIdentificacion ¬02E1|descripción

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

CpDr = ID02D%%ID02E

OBSERVACIONES:

• Los identificadores 02D, 02E son repetibles

String EntMerc (Este indientificador no es obligatorio)

Datos referentes a la entrega de la mercancía.Anticipos, autorizaciones, Cargos y descuentos aplicados en el comprobante.

entregaMercancia

ID02F= "02F"
|fechaEfectivaSalida|fechaEstimada|fechaReal|fechaSolicitada|identificacionTransporte|
matriculaTransporte|Extensible1.controlInterno1|Extensible1.controlInterno2|
Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

datosTransportista

ID02F1= "02F1"
|email|indicadordeAtencion|indicadordeCuidado|nombreContacto|nombreResponsableEntrega
|nota|numeroIdentificacion|numeroIdentificacionDV|numeroMatriculaMercantil|prefijoFacturacion
|telefax|telefono|tipoIdentificacion|transportadorNombre|transportadorNumeroDocumento
|transportadorNumeroDocumentoDV|transportadorTipoIdentificacion|Extensible1.controlInterno1
|Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

detallesTributariosTransportista

ID02F1A= "02F1A"
|codigoImpuesto|Extensible1.controlInterno1|Extensible1.controlInterno2|Extensible1.nombre
|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

direccionTransportista

ID02F1B= "02F1B"
|aCuidadoDe|aLaAtenciónDe|bloque|buzon|calle|calleAdicional|ciudad|codigoDepartamento
|correccionHusoHorario|departamento|departamentoOrg|direccion|distrito|habitacion
|lenguaje|municipio|nombreEdificio|numeroEdificio|numeroParcela|pais|piso|region
|subDivision|ubicación|zonaPostal|Extensible1.controlInterno1|Extensible1.controlInterno2
|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

responsabilidadRUT

ID02F1C= "02F1C"
|obligaciones|regimen|Extensible1.controlInterno1|Extensible1.controlInterno2
|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

transportadorDireccion

ID02F1D= "02F1D"
|aCuidadoDe|aLaAtenciónDe|bloque|buzon|calle|calleAdicional|ciudad
|codigoDepartamento|correccionHusoHorario|departamento|departamentoOrg
|direccion|distrito|habitacion|lenguaje|municipio|nombreEdificio|numeroEdificio
|numeroParcela|pais|piso|region|subDivision|ubicación|zonaPostal|Extensible1.controlInterno1
|Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

direccionDespacho

ID02F2= "02F2"
|aCuidadoDe|aLaAtenciónDe|bloque|buzon|calle|calleAdicional|ciudad
|codigoDepartamento|correccionHusoHorario|departamento|departamentoOrg
|direccion|distrito|habitacion|lenguaje|municipio|nombreEdificio|numeroEdificio
|numeroParcela|pais|piso|region|subDivision|ubicación|zonaPostal|
Extensible1.controlInterno1|Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena

direccionEntrega

ID02F3= "02F3"
aCuidadoDe|aLaAtenciónDe|bloque|buzon|calle|calleAdicional|ciudad|codigoDepartamento
|correccionHusoHorario|departamento|departamentoOrg|direccion|distrito|habitacion
|lenguaje|municipio|nombreEdificio|numeroEdificio|numeroParcela|pais|piso
|region|subDivision|ubicación|zonaPostal|Extensible1.controlInterno1|
Extensible1.controlInterno2|Extensible1.nombre|Extensible1.valor

Nota: Si Extensible1.valor se debe enviar un pipe (|) al final de la cadena
Si se envía: EntMerc = ID02F%%ID02F1%%

Si no se desea envía: EntMerc = ""

Observaciones:

• Los identificadores ID02F1A, 02F1B1, 02F1C, 02F1D1, 02F2A, 02F3A son repetibles