Proceso
Como requerimiento inicial, es necesario a través de la integración directa, rellenar el objeto del método Enviar con los datos del comprobante de pago a emitir, para luego -si la respuesta es satisfactoria-, descargar y obtener los archivos PDF, XML y CDR del comprobante emitido; caso contrario, recibir el código de error correspondiente.
Proceso del Modelo Online
Consideraciones
- El Analista de Integraciones asignado a su cuenta le enviará las credenciales de acceso del ambiente de Pruebas en un correo de bienvenida. Si olvidó o desea restaurar sus credenciales de acceso al servicio, puede restablecerlas desde el Portal de Emisión, en la sección Catálogos-->Cajas Registradoras-->Obtener usuario de integración. Haga clic y el sistema habilitará una ventana, en la cual deberá ingresar un correo electrónico válido, al que se enviarán el usuario y contraseña que usará para Integraciones
- Su desarrollo deberá incluir el manejo de funciones asíncronas, manejo de excepciones así como las validaciones pertinentes a cada campo de datos, atendiendo a las longitudes, tipos y formatos de cada uno
- Los catálogos de validaciones de SUNAT se encuentran disponibles para su descarga pública, en el portal del ente tributario CPE SUNAT
- El manejo del envío de documentos de venta (facturas, boletas, notas asociadas) se realiza por medio de un objeto; esto implica el llenado directamente sobre el request del método Enviar.
- El manejo del envío de las guías de remisión electrónicas se realiza también mediante un objeto, llenando directamente sobre el request del método GuiaRemision
- La emisión de Comprobantes de Retención, Comprobantes de Percepción, se realizará el envío de un archivo TXT codificado en base64, según los anexos descritos disponibles en esta wiki
- Para el consumo de los métodos, los nodos aparecen publicados en forma alfabética
Paso a Paso
Enviar un documento electrónico
- Rellenar objeto de los métodos Enviar o GuiaRemision
Para enviar un documento de venta, es necesario que su sistema de facturación consuma el servicio web de The Factory HKA, para lo cual deberá invocar al método Enviar y llenar los campos correspondientes a los datos de cada documento de venta a emitir, con el fin de generar los archivos XML con la firma digital y realizar la transmisión hacia OSE/SUNAT, con el fin de obtener su validación y aprobación. Para el caso de las Guías de Remisión Electrónicas, deberá hacer el mismo procedimiento, invocando el método GuiaRemision
- Generar un archivo TXT para el método RetencionPercepcion
Para enviar un comprobante (de retención o percepción) es necesario que su sistema envía un archivo TXT con un layout específico (y posteriormente codificado en base64), descrito en el artículo Layout de Comprobantes de Retención/Percepción
Conexión para la emisión
Según sea el caso, se debe invocar el método Enviar, RetencionPercepcion o GuiaRemision, todos disponibles en el servicio web de The Factory HKA. Al método se deben enviar los datos correspondientes al documento generado en el paso 1 en el caso de enviar un comprobante de retención/Percepción; o llenar el objeto del request para documentos de venta o guías de remisión. Estos métodos abren el canal de comunicación hacia el servicio de The Factory HKA, quien, a su vez, encapsula toda la lógica del proceso y hace posible la generación del documento electrónico firmado en formato XML, así como la transmisión a OSE/SUNAT.
Finalmente, la respuesta especificará el proceso de validación por parte de The Factory HKA, a través de un código de éxito o error, devolviendo igualmente el UUID del documento (Universally Unique IDentifier / tipo-serie-correlativo).
Documentos incluidos en el método Enviar:
- Factura
- Boleta de venta
- Nota de crédito
- Nota de débito
Documentos incluidos en el método RetencionPercepcion:
- Comprobante de Retención
- Comprobante de Percepción
Documentos incluidos en el método GuiaRemision:
Conexión para descarga de documentos
Si la respuesta de validación fue exitosa, su sistema de facturación puede obtener y mostrar los documentos emitidos en formato PDF y XML, a través del método DescargaArchivo. De igual forma, se puede utilizar el mismo método para descargar el CDR, que le permitirá obtener la respuesta que emite OSE/SUNAT con el estatus de aprobación del documento.
Conexión para Comunicación de Baja y Reversión
En caso de que necesite anular un determinado documento emitido, puede invocar el servicio web de The Factory HKA para comunicar la baja o revertir el documento observado, a través de los métodos ComunicacionBaja y Reversión.
Es importante tener en cuenta que el plazo para realizar la comunicación de baja es de 7 días calendario y para realizarla es requisito que los documentos hayan sido aceptados por OSE/SUNAT.
Comprantes incluidos para el método ComunicacionBaja:
- Factura
- Boleta de venta
- Nota de crédito
- Nota de débito
Comprobantes incluidos para el método Reversión:
NOTA: No existe la anulación de una Guía de Remisión Electrónica emitida desde los SEE- Del Contribuyente. En este caso, deberá realizar una nueva guía de remisión y relacionar la anterior.
Métodos del servicio web de The Factory HKA
Se han implementado diferentes métodos que le permitirán realizar el proceso de facturación electrónica de manera rápida y eficaz. En la especificación de cada uno de ellos se indica la funcionalidad del método, el parámetro que se debe ingresar, y la estructura y ejemplos de las respuestas que puede obtener al ejecutar estos métodos.
El enlace de acceso a nuestro ambiente de pruebas es https://demoint.thefactoryhka.com.pe/Service.svc.
Enviar
Artículo principal: Web Service SOAP - Método Enviar
El método Enviar permite la generación de los siguientes documentos:
- Factura Electrónica
- Boleta de Venta Electrónica
- Nota de Crédito Electrónica
- Nota de Débito Electrónica
| Descripción
|
Método para enviar documentos (factura, boleta de venta, nota de crédito y nota de débito) a OSE/SUNAT
|
| Respuesta Exitosa
|
Código de aceptación | Mensaje de aceptación | Serie - correlativo del documento y XML timbrado
|
CargarCertificado
| Descripción
|
Método de carga de certificado electrónico en la cuenta del usuario que se usará para firmar electrónicamente los documentos y comprobantes a consignar para OSE/SUNAT.
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
CargarCertificado
|
| Cantidad de Campos:
|
5
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
| <tem:certificadoBase64>
|
Certificado autorizado, cifrado en base 64
|
|
| <tem:certificadoClaveBase64>
|
Clave del certificado, cifrada en base 64
|
|
ComunicacionBaja
| Descripción
|
Método para dar de baja a los documentos de venta (factura, boleta de venta, nota de crédito y nota de débito) enviados al OSE/SUNAT
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
ComunicacionBaja
|
| Cantidad de Campos:
|
5
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
| <tem:documento>
|
Tipo, serie y correlativo de documento a dar de baja
|
AN|...16
|
TT-XZZZ-NNNNNNNN
Donde TT hace referencia al tipo de documento según catálogo N° 01
X hace referencia al tipo de documento:
F: Factura o notas asociadas
B: Boletas o notas asociadas
ZZZ hace referencia a la serie
NNNNNNNN hace referencia al correlativo
|
| <tem:motivo>
|
Motivo de la anulación del documento
|
AN|...100
|
DescargaArchivo
| Descripción
|
Método para descargar los diferentes archivos relacionados con los documentos de venta (PDF, XML, CDR) enviados al OSE/SUNAT
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
DescargaArchivo
|
| Cantidad de Campos:
|
4
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
| <tem:documento>
|
Tipo, serie y correlativo de documento a dar de baja
|
AN|...16
|
TT-XZZZ-NNNNNNNN
Donde TT hace referencia al tipo de documento según catálogo N° 01
X hace referencia al tipo de documento:
F: Factura o notas asociadas
B: Boletas o notas asociadas
ZZZ hace referencia a la serie
NNNNNNNN hace referencia al correlativo
|
| <tem:tipoArchivo>
|
Tipo de archivo a descargar
|
AN|3
|
PDF: Para descargar el pdf (representación impresa)
XML: Para descargar el xml (documento electrónico)
CDR: Para descargar la Constancia de Recepción de OSE/SUNAT
|
EstatusDocumento
| Descripción
|
Método para consultar estatus de documentos (factura, boleta de venta, nota de crédito y nota de débito) en el servicio The Factory HKA, para verificar si ya se envió a OSE/Sunat
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
EstatusDocumento
|
| Cantidad de Campos:
|
3
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
| <tem:documento>
|
RUC,Tipo, serie y correlativo de documento a consultar
|
AN|...16
|
RUC-TT-XZZZ-NNNNNNNN
Donde TT hace referencia al tipo de documento según catálogo N° 01
X hace referencia al tipo de documento:
ZZZ hace referencia a la serie
NNNNNNNN hace referencia al correlativo
|
FoliosRestantes
| Descripción
|
Método para consultarla cantidad de folios restantes para el usuario
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
FoliosRestantes
|
| Cantidad de Campos:
|
3
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
Reversion
| Descripción
|
Método para anular un comprobante de retención o percepción
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
Reversion
|
| Cantidad de Campos:
|
4
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
| <tem:documento>
|
Tipo, serie y correlativo de documento a revertir
|
AN|...16
|
TT-XZZZ-NNNNNNNN
Donde TT hace referencia al tipo de documento según catálogo N° 01
X hace referencia al tipo de documento:
R: Retenciones
P: Percepciones
ZZZ hace referencia a la serie
NNNNNNNN hace referencia al correlativo
|
| <tem:motivo>
|
Motivo de la anulación del documento
|
AN|...100
|
ValidaAcceso
| Descripción
|
Método para validar las credenciales de acceso
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
ValidaAcceso
|
| Cantidad de Campos:
|
3
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
GuiasRemision
Artículo principal: Web Service SOAP - Método GuiasRemision
El método GuiasRemision permite la generación de los siguientes documentos:
- Guía Remisión Electrónicas UBL 2.0
- Guía Remisión Electrónicas UBL 1.0
| Descripción
|
Método para enviar documentos (Guías de Remisión 1.0 - 2.0) a OSE/SUNAT
|
| Respuesta Exitosa
|
Código de aceptación | Mensaje de aceptación | Serie - correlativo del documento y XML timbrado
|
CancelarListado
| Descripción
|
Método para cancelar un listado enviado.
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
CancelarListado
|
| Cantidad de Campos:
|
4
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
| <tem:tipoCancelar>
|
Tipo de listado a cancelar
|
|
Logo
| Descripción
|
Método de carga del logo de la empresa que se usará para generar electrónicamente las representaciones de documentos y comprobantes consignados a OSE/SUNAT.
|
| Respuesta Exitosa
|
Código, Mensaje
|
Parámetros de Entrada
| Nombre del método
|
Logo
|
| Cantidad de Campos:
|
5
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:usuario>
|
Usuario de Integración Emitido por el Sistema
|
|
| <tem:clave>
|
Contraseña de Integración Emitido por el Sistema
|
|
| <tem:extension>
|
Extensión de la imagen (jpg, png, ...)
|
|
| <tem:logo>
|
logo
|
|
ListadoSerie
| Descripción
|
Permite realizar una petición para realizar las siguientes acciones por el tipo en las series asociadas a la empresa.
|
| Respuesta Exitosa
|
Código (devuelve 0 si es exitoso), Mensaje
|
Parámetros de Entrada
| Nombre del método
|
ListadoSerie
|
| Cantidad de Campos:
|
9
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:usuario>
|
Usuario de Integración
|
|
| <tem:clave>
|
Clave de Integración
|
|
| <tem:tipo>
|
Tipo de acción a realizar
|
Tipo 1: Te permite crear una serie
Tipo 2: Busca todas las series que posee la empresa.
Tipo 3: Actualiza la serie por nomenclatura de la serie
Tipo 4: Elimina la serie por nomenclatura de la serie
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <per:folio_actual>
|
Folio Actual de la Serie
|
N|8
|
|
| <per:folio_inicial>
|
Folio Inicial de la Serie
|
N|8
|
|
| <per:serie>
|
Nomenclatura de la Serie
|
AN|4
|
|
| <per:tipo_asignacion>
|
Tipo de Asignación Manual o Automático
|
A|1
|
Automático : A
Manual : M
|
| <per:tipo_documento>
|
Tipo de Documento asociado a la Serie
|
N|2
|
Catálogo N°01
|
ListadoSucursal
| Descripción
|
Permite realizar una petición para realizar las siguientes acciones por el tipo en las sucursales asociadas a la empresa.
|
| Respuesta Exitosa
|
Código (devuelve 0 si es exitoso), Mensaje
|
Parámetros de Entrada
| Nombre del método
|
ListadoSucursal
|
| Cantidad de Campos:
|
4 -11
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:token>
|
Token de acceso
|
|
| <tem:serial>
|
Serial del dispositivo
|
|
| <tem:tipo>
|
Tipo de acción a realizar
|
Tipo 1: te permite crear una sucursal
Tipo 2: busca todas las sucursales asociadas a la empresa.
Tipo 3: Actualiza la sucursal por código.
Tipo 4: Borra la sucursal por código.
|
Datos Sucursal (Objeto / Listado)
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:codigo>
|
código de la sucursal
|
string
|
| <tem:descripcion>
|
Descripción de la sucursal
|
|
| <tem:direccion>
|
Dirección de la sucursal
|
|
| <tem:pais>
|
Siglas del país Ejemplo: PE
|
|
| <tem:telefono>
|
Teléfonos de la sucursal
|
|
| <tem:tipoEstablecimiento>
|
Tipo de establecimiento
|
|
| <tem:ubigeo>
|
Codigo ubigeo de la ubicación de la sucursal
|
|
ListadoProductos
| Descripción
|
Permite realizar el listado , creación , actualización y eliminación de los distintos productos.
|
| Respuesta Exitosa
|
Código (devuelve 0 si es exitoso), Mensaje
|
Parámetros de Entrada
| Nombre del método
|
ListadoProductos
|
| Cantidad de Campos:
|
11
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:usuario>
|
Usuario de Integración
|
|
| <tem:clave>
|
Clave de Integración
|
|
| <tem:tipo>
|
Tipo de acción a realizar
|
Tipo 1: Te permite crear un producto
Tipo 2: Busca todos los productos que posee la empresa.
Tipo 3: Actualiza el producto por códigoUser
Tipo 4: Elimina el producto por códigoUser
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <per:codigoGs1>
|
Código GS1 del Producto.
|
N|13
|
|
| <per:codigoSunat>
|
Código Sunat del Producto.
|
N|8
|
|
| <per:codigoUser>
|
Código del Producto que asigna el Usuario internamente.
|
AN|30
|
|
| <per:descripcion>
|
Descripción del Producto
|
AN|500
|
|
| <per:impuesto>
|
Código de Tipo de Afectación del IGV
|
N|4
|
Catálogo N°07
|
| <per:unidad>
|
Unidad de Medida del Producto
|
AN|3
|
|
| <per:valorUnitario>
|
Valor Unitario del Producto
|
12,10
|
|
ListadoClientes
| Descripción
|
Permite realizar una petición para realizar las siguientes acciones por el tipo en los clientes asociados a la empresa.
|
| Respuesta Exitosa
|
Código (devuelve 0 si es exitoso), Mensaje
|
Parámetros de Entrada
| Nombre del método
|
ListadoClientes
|
| Cantidad de Campos:
|
9
|
| Campo
|
Descripción
|
Tipo|Longitud
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
| <tem:usuario>
|
Usuario de Integración
|
|
| <tem:clave>
|
Clave de Integración
|
|
| <tem:tipo>
|
Tipo de acción a realizar
|
Tipo 1: Te permite crear un cliente
Tipo 2: Busca todos los clientes que posee la empresa.
Tipo 3: Actualiza la información del cliente por RUC
Tipo 4: Elimina la información del cliente por RUC
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <per:direccion>
|
Dirección
|
AN|200
|
|
| <per:email>
|
Correo Electrónico del Cliente
|
AN|200
|
|
| <per:enviarEmail>
|
Activar Notificaciones Via Correo Electrónico
|
A|2
|
SI o NO
|
| <per:numDocumento>
|
Número de Documento del Cliente
|
AN|15
|
|
| <per:pais>
|
País del Cliente
|
A|2
|
Catálogo N°04
|
| <per:razonSocial>
|
Razón Social del Cliente
|
AN|100
|
|
| <per:telefono>
|
Número de Telefono del Cliente
|
N|15
|
|
| <per:tipoDocumento>
|
Tipo de Documento del Cliente
|
N|2
|
Catálogo N°06
|
| <per:ubigeo>
|
Ubigeo de la Dirección del Cliente
|
N|2
|
|
EnvioCorreo
| Descripción
|
Permite enviar via correo electrónico los archivos XML,PDF y CDR
|
| Respuesta Exitosa
|
Código (devuelve 0 si es exitoso), Mensaje
|
Parámetros de Entrada
| Nombre del método
|
EnvioCorreo
|
| Cantidad de Campos:
|
11
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
|
| <tem:usuario>
|
Usuario de Integración
|
|
|
| <tem:clave>
|
Clave de Integración
|
|
|
| <tem:numeracion>
|
Numeración del Documento a Enviar
|
AN|13
|
ZZZZ-NNNNNNNN, donde:
ZZZZ corresponde a la serie
NNNNNNNN al número de documento
|
| <tem:tipo>
|
Tipo de Documento
|
N|2
|
Catálogo N° 06
|
| <tem:destinatarios>
|
Correo electronico del destinatario. Debe ser una dirección válida para el envío correcto del documento electrónico.
Para enviar varios correos, deben separarse con el caracter , (coma) o ; (punto y coma)
|
AN|2000
|
|
EstatusCorreo
| Descripción
|
Permite realizar una petición para obteber información sobre el historial de envios del documento consultado.
|
| Respuesta Exitosa
|
Código (devuelve 0 si es exitoso), Mensaje
|
Parámetros de Entrada
| Nombre del método
|
EstatusCorreo
|
| Cantidad de Campos:
|
3
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <tem:usuario>
|
Usuario de Integración
|
|
|
| <tem:clave>
|
Clave de Integración
|
|
|
| <tem:documento>
|
Número de Documento a Consultar
|
AN|28
|
RUC-TipoDeDocumento-Serie-Correlativo
|
DescargarListado
| Descripción
|
Permite enviar via correo electrónico los archivos XML,PDF y CDR
|
| Respuesta Exitosa
|
Código (devuelve 0 si es exitoso), Mensaje
|
Parámetros de Entrada
| Nombre del método
|
DescargarListado
|
| Cantidad de Campos:
|
5
|
| Campo
|
Descripción
|
Tipo|Longitud
|
Formato
|
| <tem:ruc>
|
RUC del emisor
|
N|11
|
|
| <tem:usuario>
|
Usuario de Integración
|
|
|
| <tem:clave>
|
Clave de Integración
|
|
|
| <tem:lote>
|
Numeración del lote
|
|
|
| <tem:ticket>
|
numero del ticket (respuesta de GeneraListado)
|
|
|
