Servicios de Manejo de Documentos Electrónicos para Receptor - Índice Manual Integración Recepción Electrónica

De tfhkacolwiki
Revisión del 20:14 11 dic 2025 de Paguirre (discusión | contribs.)
(difs.) ← Revisión anterior | Revisión actual (difs.) | Revisión siguiente → (difs.)
Ir a la navegación Ir a la búsqueda

Métodos del Servicio Web HKA Recepción

El Servicio de Recepción maneja un conjunto de funcionalidades que soportan la gestión de las facturas emitidas por proveedores de bienes y servicios a clientes de The Factory HKA Colombia, cuando estos proveedores no tienen a The Factory HKA Colombia como Proveedor Tecnológico de Facturación Electrónica.

El servicio de HKA Recepción se encuentra dispuesto para realizar dos conjuntos de acciones:

  • Recepción de Documentos Electrónicos
  • Gestión de Documentos Electrónicos

Recepción de Documentos Electrónicos

Contempla las funcionalidades que permiten remitir los documentos que soportan el documento electrónico, entre ellas se encuentran los métodos disponibles:

Método Envío de XML AttachedDocument “EnviarXML”

Permite enviar el archivo XML AttachedDocument que representa Documento Fiscal Electrónico, el cual fue emitido por un proveedor de bienes y servicios a un cliente The Factory HKA Colombia, el archivo XML se debe remitir en Base64. Opcionalmente se puede remitir los llamados Metadatos


REQUEST
Parámetros a Enviar
Tipo Identificador Descripción
Class metadata Lista Optativa de cuarteto, que permite especificar atributos adicionales referentes al Documento Fiscal Electrónico; los cuartetos son de la forma (code, value, internal1 (optativo), internal2 (optativo)); estableciendo una asociación entre el elemento code (que representa el código de metadata ) y el resto de los “atributos” del cuarteto en cuestión.
String archivo Archivo XML en Base64 que contiene el documento electrónico que se desea enviar
tokenEmpresa Dato suministrado por The Factory HKA Colombia (40 caracteres)
tokenPassword


RESPONSE
Parámetros a Recibir
Tipo Identificador Descripción
String codigo Código de retorno, Tabla 2
documentoId Consecutivo del documento remitido.
estatusDocumento Estatus final del documento del Documento.
mensaje Mensaje descriptivo del resultado de la operación.
numeroIdentificacion Número de identificación del emisor del documento remitido.
resultado Contiene información adicional (Procesado/Error)
tipoIdentificacion Tipo de identificación del emisor del documento remitido.

Ejemplo de entrada 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:wcf="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP">
    <soapenv:Header/>
    <soapenv:Body>
        <tem:EnviarXML>
            <tem:request>
                <wcf:archivo>PD94b…………..bnQ+</wcf:archivo>
                <wcf:metadata>
                    <wcf:metadata>
                        <wcf:Metadata>
                            <wcf:code>01</wcf:code>
                            <wcf:internal1/>
 <wcf:internal2/>
                            <wcf:value/>
                        </wcf:Metadata>
                    </wcf:metadata>
                </wcf:metadata>
                <wcf:tokenEmpresa>89……………52</wcf:tokenEmpresa>
                <wcf:tokenPassword>b3……………43</wcf:tokenPassword>
            </tem:request>
        </tem:EnviarXML>
    </soapenv:Body>
</soapenv:Envelope>


Ejemplo de salida 

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
        <EnviarXMLResponse xmlns="http://tempuri.org/">
            <EnviarXMLResult xmlns:a="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
                <a:codigo>203</a:codigo>
                <a:documentoId>AHJ07</a:documentoId>
                <a:estatusDocumento>Cargado</a:estatusDocumento>
                <a:mensaje>Documento Enviado Satisfactoriamente - Problema(s) con Metadato(s) : Valor(es) suministrado(s) para Metadato(s) no corresponde(n) a la(s) lista(s) definida(s)</a:mensaje>
<a:numeroIdentificacion>45......34</a:numeroIdentificacion>
                <a:resultado>Procesado</a:resultado>
                <a:tipoIdentificacion>31</a:tipoIdentificacion>
            </EnviarXMLResult>
        </EnviarXMLResponse>
    </s:Body>
</s:Envelope>


Método Envío de Representación Gráfica (EnviarRepGrafica)

Permite a un Receptor enviar el archivo que corresponde a la representación gráfica de una fatura electrónica, identificado con el número documento, emitido por un proveedor de bienes y servicios identificado al Receptor ya mencionado; el archivo debe remitirse codificado en Base64.


REQUEST
Parámetros a Enviar
Tipo Identificador Descripción
Bytes archivo Archivo PDF en Base64 que contiene la representación gráfica del documento electrónico que se desea enviar
String TipoDocumento Es el tipo de documento al cual se le va a remitir la representación gráfica.
extension Indica el formato del archivo remitido; los valores admitidos son: png, bmp, jpg, pdf, doc, docx, xls, xlsx, ppt, pptx, rar, zip
identificadorEmisor NIT del Emisor o Identificador Tributario del Emisor de la Factura
nombre Nombre del archivo de la Representación Gráfica
numeroDocumento Consecutivo del documento al cual se le remite la representación gráfica.
tipoIdentificadoremisor NIT del Emisor o Identificador Tributario del Emisor de la Factura
visible Indica si el archivo posteriormente puede ser o no descargado por el Emisor (Visible = 1, No visible = 0)
tokenEmpresa Dato suministrado por The Factory HKA Colombia (40 caracteres)
tokenPassword


RESPONSE
Parámetros a Recibir
Tipo Identificador Descripción
Int codigo Código de retorno, Tabla 2
String mensaje Mensaje descriptivo del resultado de la operación
String resultado, contiene información adicional (Procesado/Error)

Ejemplo de entrada 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:wcf="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP">
    <soapenv:Header/>
    <soapenv:Body>
        <tem:EnviarRepGrafica>
            <tem:request>
                <wcf:TipoDocumento>91</wcf:TipoDocumento>
                <wcf:archivo>JVB……FT0YK</wcf:archivo>
                <wcf:extension>ppt</wcf:extension>
                <wcf:identificadorEmisor>45…34</wcf:identificadorEmisor>
                <wcf:nombre>SOAP01-2</wcf:nombre>
                <wcf:numeroDocumento>SOAP019</wcf:numeroDocumento>
                <wcf:tipoIdentificacionemisor>31</wcf:tipoIdentificacionemisor>
                <wcf:tokenEmpresa>89……………52</wcf:tokenEmpresa>
                <wcf:tokenPassword>b3……………43</wcf:tokenPassword>
                <wcf:visible>1</wcf:visible>
            </tem:request>
        </tem:EnviarRepGrafica>
    </soapenv:Body>
</soapenv:Envelope>


Ejemplo de salida 

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
        <EnviarRepGraficaResponse xmlns="http://tempuri.org/">
            <EnviarRepGraficaResult xmlns:a="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
                <a:codigo>102</a:codigo>
                <a:mensaje>Token Password es Requerido</a:mensaje>
                <a:resultado>Error</a:resultado>
            </EnviarRepGraficaResult>
        </EnviarRepGraficaResponse>
    </s:Body>
</s:Envelope>


Método Envío de Anexo "EnvioAnexo"

Permite remitir un archivo adicional de una factura, diferente a la representación gráfica, identificando el numero documento al cual se encuentra asociado. El archivo a remitir debe estar codificado en Base64.


REQUEST
Parámetros a Enviar
Tipo Identificador Descripción
Bytes archivo Archivo en Base64 que representa un anexo de factura identificada por número de documento
String TipoDocumento Es el tipo de documento al cual se le remite el anexo.
extension Indica el formato del archivo remitido; los valores admitidos son: png, bmp, jpg, pdf, doc, docx, xls, xlsx, ppt, pptx, rar, zip
identificadorEmisor NIT del Emisor o Identificador Tributario del Emisor de la Factura
nombre Nombre del documento de la Representación Gráfica (Hasta 100 caracteres)
numeroDocumento Consecutivo del documento al cual se le remite el anexo. (Hasta 20 caracteres)
tipoidentificadoremisor Tipo de documento del Emisor Tabla 4
visible Indica si el archivo posteriormente puede ser o no descargado por el Emisor. (Visible = 1, No visible = 0)
tokenEmpresa Dato suministrado por The Factory HKA Colombia (40 caracteres)
tokenPassword


RESPONSE
Parámetros a Recibir
Tipo Identificador Descripción
Int codigo Código de retorno, Tabla 2
String mensaje Mensaje descriptivo del resultado de la operación
resultado Contiene información adicional (Procesado/Error)


Ejemplo de entrada 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:wcf="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP">
    <soapenv:Header/>
    <soapenv:Body>
        <tem:EnviarAnexo>
            <tem:request>
                <wcf:archivo>JVB…….</wcf:archivo>
                <wcf:extension>pdf</wcf:extension>
                <wcf:TipoDocumento>91</wcf:TipoDocumento>
                <wcf:identificadorEmisor>456…34</wcf:identificadorEmisor>
                <wcf:nombre>AHJ07-7</wcf:nombre>
                <wcf:numeroDocumento>AHJ07</wcf:numeroDocumento>
                <wcf:tipoIdentificacionemisor>31</wcf:tipoIdentificacionemisor>
                <wcf:tokenEmpresa>89……………52</wcf:tokenEmpresa>
                <wcf:tokenPassword>b3……………43</wcf:tokenPassword>
                <wcf:visible>1</wcf:visible>
            </tem:request>
        </tem:EnviarAnexo>
    </soapenv:Body>
</soapenv:Envelope>


Ejemplo de salida 

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
        <EnviarAnexoResponse xmlns="http://tempuri.org/">
            <EnviarAnexoResult xmlns:a="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
                <a:codigo>200</a:codigo>
                <a:mensaje>Archivo enviado satisfactoriamente</a:mensaje>
                <a:resultado>Procesado</a:resultado>
            </EnviarAnexoResult>
        </EnviarAnexoResponse>
    </s:Body>
</s:Envelope>


Gestión de Documentos Electrónicos

Engloba las funcionalidades inherentes a la gestión propia de los documentos ya radicados, para ello se cuenta con los métodos:

Método Cambio de Estatus "CambioEstatus"

Este método permite la actualización del estado (o generación de eventos) de un Documento de Facturación Electrónica previamente emitido. Solo cuando el Adquiriente (Receptor de la factura electrónica) tiene a The Factory HKA Colombia como su Proveedor Tecnológico de Facturación Electrónica.

NOTA:Si el documento está en un estado DIAN y se requiere cambiar a otro estado y se genera una regla de rechazo, puede que se encuentre en espera para recibir respuesta de la DIAN del cambio de estado inicial, por lo cual se recomienda esperar 5 minutos antes de realizar un nuevo cambio de estado.

REQUEST
Parámetros a Enviar
Tipo Identificador Atributo Descripción
class EjecutadorPor Apellido Apellido de la persona encargada de realizar el cambio de estado.
Cargo Cargo u ocupación que desempeña la persona que realiza el cambio de estado en la organización, organismo o empresa.(opcional).
Departamento. Área en la que se encuentra la persona encargada del cambio de estado (opcional).
DV Digito verificador del NIT de la empresa.
NumeroIdentificacion NIT de la empresa.
TipoIdentificacion Tipo de identifiación de la empresa según la Tabla 4
Nombre Nombre de la persona encargada de realizar el cambi de estado o envio de eventos hacia la DIAN.
String TipoDocumento Es el tipo de documento al cual se le aplicará el cambio de estado (01 para facturas)
codigoRechazo Código de la razón por la cual se realiza el reclamo de la factura según Tabla 6.

IMPORTANTE: El codigoRechazo es requerido al realizar el reclamo de una factura.

identificadorEmisor NIT del Emisor o Identificador Tributario del Emisor de la Factura, de 6 a 20 dígitos
numeroDocumento Consecutivo del documento hasta 20 caracteres
status Código de Estatus del documento,requerido para la búsqueda*,se puede verificar en la siguiente Tabla 1
tipoIdentificacionemisor Tipo de identificador del Emisor del documento según Tabla 4
tokenEmpresa Dato suministrado por The Factory HKA Colombia (40 caracteres)
tokenPassword


RESPONSE
Parámetros a Recibir
Tipo Identificador Descripción
Int Código Código de retorno. Ver catálogo de respuesta del método
String mensaje Mensaje descriptivo del resultado de la operación
String resultado Contiene información adicional (Procesado/Error)


Ejemplo de entrada 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:wcf="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP">
   <soapenv:Header/>
   <soapenv:Body>
      <tem:CambioEstatus>
         <tem:request>
            <wcf:EjecutadoPor>
               <wcf:Apellido>López</wcf:Apellido>
               <wcf:Cargo>Pruebas</wcf:Cargo>
               <wcf:Departamento>Calidad</wcf:Departamento>
               <wcf:Identificacion>
                  <wcf:Dv/>
                  <wcf:NumeroIdentificacion>148777333351</wcf:NumeroIdentificacion>
                  <wcf:TipoIdentificacion>13</wcf:TipoIdentificacion>
               </wcf:Identificacion>
               <wcf:Nombre>Adriana</wcf:Nombre>
            </wcf:EjecutadoPor>
            <wcf:TipoDocumento>01</wcf:TipoDocumento>
            <wcf:codigoRechazo>02</wcf:codigoRechazo>
            <wcf:identificadorEmisor>90………26</wcf:identificadorEmisor>
            <wcf:numeroDocumento>AKLAA16</wcf:numeroDocumento>
            <wcf:status>10</wcf:status>
            <wcf:tipoIdentificacionemisor>31</wcf:tipoIdentificacionemisor>
            <wcf:tokenEmpresa>xxxxxxxxxx</wcf:tokenEmpresa>
            <wcf:tokenPassword>xxxxxxxxxxx</wcf:tokenPassword>
         </tem:request>
      </tem:CambioEstatus>
   </soapenv:Body>
</soapenv:Envelope>

Ejemplo de salida 


<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
        <CambioEstatusResponse xmlns="http://tempuri.org/">
            <CambioEstatusResult xmlns:a="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
                <a:codigo>103</a:codigo>
                <a:mensaje>Se produjo un error en el servicio...{"Codigo":"108","Mensaje":"No se pudo cambiar el status del Documento ABB01 emitido por NIT 45......34 a NIT 12.....9. Estatus no válido. No está permitido el status Precargado cuando se está en el estatus Acuse de recibo (DIAN)","Resultado":"Error"} por favor inténtelo más tarde</a:mensaje>
                <a:resultado>Error</a:resultado>
            </CambioEstatusResult>
        </CambioEstatusResponse>
    </s:Body>
</s:Envelope>


Método DescargarAcuseAceptacionXML

Permite obtener el archivo XML ApplicationResponse en Base64,correspondiente al evento de aceptación de la Factura Electrónica.

REQUEST
Parámetros a Enviar
Tipo Identificador Descripción
String TipoDocumento Es el tipo de documento del cual se desea descrgar el XML.
identificadorEmisor NIT del Emisor o Identificador Tributario del Emisor de la Factura
nombreFileApplicationResponse Nombre del documento que se encuentra en Lista de Anexo (Opcional)
nmeroDocumento Consecutivo del documento del cual se desea obtener el XML.
tipoDescarga Igual a 1
tipoIdentificacionemisor Identificador del Emisor Tabla 4
tokenEmpresa Dato suministrado por The Factory HKA Colombia (40 caracteres)
tokenPassword


RESPONSE
Parámetros a Recibir
Tipo Identificador Descripción
Bytes archivo Archivo en Base64 del documento
Int codigo Código de retorno, Tabla 4
sizeFile tamaño del documento
String crc Chequeo de Redundancia Cíclica
cufe Certificado Único de Facturación Electrónica.
mensaje Mensaje descriptivo del resultado de la operación
resultado Contiene información adicional (Procesado/Error)


Ejemplo de entrada 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:wcf="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP">
    <soapenv:Header/>
    <soapenv:Body>
         <tem:DescargarAcuseAceptacionXML>
     	<tem:request>
        	<wcf:TipoDocumento></wcf:TipoDocumento>
        	<wcf:identificadorEmisor>90……26</wcf:identificadorEmisor>
        	<wcf:nombreFileApplicationResponse>d9a1a014-9587-4901-af6e-190d0d1c2b0e.xml</wcf:nombreFileApplicationResponse>
        	<wcf:numeroDocumento>SETP990441830</wcf:numeroDocumento>
        	<wcf:tipoDescarga>1</wcf:tipoDescarga>
        	<wcf:tipoIdentificacionemisor>31</wcf:tipoIdentificacionemisor>
        	<wcf:tokenEmpresa>89…………52</wcf:tokenEmpresa>
        	<wcf:tokenPassword>b3…………43</wcf:tokenPassword>
     	</tem:request>
  	</tem:DescargarAcuseAceptacionXML>
    </soapenv:Body>
</soapenv:Envelope>


Ejemplo de salida 

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
         <DescargarAcuseAceptacionXMLResponse xmlns="http://tempuri.org/">
            <DescargarAcuseAceptacionXMLResult xmlns:a="http://schemas.datacontract.org/2004/07/WcfRecepcionSOAP" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
               <a:archivo>PD94bWwgd…………………</a:archivo>
                <a:codigo>200</a:codigo>
                <a:crc>022770951408403f9442f9d09e52be15</a:crc>
                <a:cufe>d9a1a014-9587-4901-af6e-190d0d1c2b0e.xml</a:cufe>
                <a:mensaje>Se retorna el archivo solicitado</a:mensaje>
                <a:resultado>Procesado</a:resultado>
                <a:size>14688</a:size>
            </DescargarAcuseRecibidoXMLResult>
  	</DescargarAcuseRecibidoXMLResponse>
    </s:Body>
</s:Envelope>
Obtenido de «http://felcowiki.thefactoryhka.com.co/index.php?title=Servicios_de_Manejo_de_Documentos_Electrónicos_para_Receptor_-_Índice_Manual_Integración_Recepción_Electrónica&oldid=9393»