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

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>