Integración Directa - Web Service SOAP
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.
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:
- Guía de Remisión
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:
- Retención
- Percepció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.
Método Enviar
| 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 |
Credenciales
| Ubicación en Objeto: | tem:Enviar/ |
|---|---|
| Cantidad de Campos: | 3 |
| Descripción General: | Contiene los datos de acceso para validar la identidad del usuario a enviar la información del documento |
| Recurrencia de la línea: | 1 |
| 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 |
Emisor
| Ubicación en Objeto: | tem:Enviar/tem:documentoElectronico/per:emisor/ |
|---|---|
| Cantidad de Campos: | 4 |
| Descripción General: | Contiene información base del emisor del documento electrónico. El resto de los campos solicitados en el XML se toman de lo que esté registrado en el Portal de Emisión |
| Recurrencia de la línea: | 0...1 |
| Campo | Descripción | Tipo|Longitud | Formato | Obligatorio | Opcional |
|---|---|---|---|---|---|
| <per:domicilioFiscal> | Dirección del domicilio fiscal | AN|...100 | F, B, NC, ND | ||
| <per:lugarExpedicion> | Código asignado por SUNAT para el establecimiento anexo declarado en el RUC | N|4 | F, B, NC, ND | ||
| <per:ruc> | RUC del emisor | N|11 | F, B, NC, ND | ||
| <per:serialCaja> | Serial numérico del equipo o aplicación en caso de que el emisor utilice un medio diferente al WS | AN|...15 | F, B, NC, ND |
Receptor
| Ubicación en Objeto: | tem:Enviar/tem:documentoElectronico/per:receptor |
|---|---|
| Cantidad de Campos: | 12 |
| Descripción General: | Contiene información del cliente |
| Recurrencia de la línea: | 0...1 |
| Campo | Descripción | Tipo|Longitud | Formato | Obligatorio | Opcional |
|---|---|---|---|---|---|
| <per:departamento> | Departamento de la dirección del cliente | AN|...100 | F, B, NC, ND | ||
| <per:direccion> | Dirección del cliente | AN|...100 | F, B, NC, ND | ||
| <per:distrito> | Distrito de la dirección del cliente | AN|...100 | F, B, NC, ND | ||
| <per:email> | Email del cliente. Debe ser una dirección válida para el envío correcto del documento electrónico | AN|...100 | F, B, NC, ND | ||
| <per:notificar> | Flag de notificación para envío de correo electrónico | AN|2 | SI para notificar NO en caso contrario |
F, B, NC, ND | |
| <per:numDocumento> | Número de documento del cliente | AN|...13 | F, NC, ND | B* | |
| <per:pais> | País al que hace referencia la dirección | AN|...100 | F, B, NC, ND | ||
| <per:provincia> | Provincia de la dirección del cliente | AN|...100 | F, B, NC, ND | ||
| <per:razonSocial> | Nombres y Apellidos o Razón social del cliente | AN|...100 | F, NC, ND | B* | |
| <per:telefono> | Teléfono del cliente | AN|...50 | F, B, NC, ND | ||
| <per:tipoDocumento> | Tipo de documento del cliente | AN|...13 | Catálogo N° 06 | F, NC, ND | B* |
| <per:ubigeo> | Ubigeo de la dirección del cliente | N|6 | Catálogo N° 13 | F, B, NC, ND |
* : En el caso de Boletas, debe viajar esta información de forma obligatoria cuando el monto total supera los S/ 700.
Delivery (Entrega de bien o servicio)
| Ubicación en Objeto: | tem:Enviar/tem:documentoElectronico/per:entregaBienoServicio |
|---|---|
| Cantidad de Campos: | 8 |
| Descripción General: | Contiene información de la dirección del lugar en el que se entrega el bien, siempre que este dato no obre como punto de llegada en la guía de remisión |
| Recurrencia de la línea: | 0...1 |
| Campo | Descripción | Tipo|Longitud | Formato | Obligatorio | Opcional |
|---|---|---|---|---|---|
| <per:codigoPais> | Código de país de la dirección para la entrega | AN|2 | Catálogo N° 04 | F, B | |
| <per:departamento> | Departamento de la dirección para la entrega | AN|...30 | F, B | ||
| <per:direccion> | Dirección para la entrega | AN|...200 | F, B | ||
| <per:distrito> | Distrito de la dirección para la entrega | AN|...30 | F, B | ||
| <per:paisUsoServicio> | País de uso del servicio o bien entregado | AN|2 | Catálogo N° 04 | F, B | |
| <per:provincia> | Provincia de la dirección para la entrega | AN|...30 | F, B | ||
| <per:ubigeo> | Ubigeo de la dirección para la entrega | AN|6 | Catálogo N° 13 | F, B | |
| <per:urbanizacion> | Urbanización de la dirección para la entrega | AN|...25 | F, B |
Comprobante
| Ubicación en Objeto: | tem:Enviar/ |
|---|---|
| Cantidad de Campos: | 8 |
| Descripción General: | Contiene información del comprobante electrónico |
| NOTA: | Los nodos son hijos directos del nodo tem:Enviar/ |
| Recurrencia de la línea: | 1 |
| Campo | Descripción | Tipo|Longitud | Formato | Obligatorio | Opcional |
|---|---|---|---|---|---|
| <per:codigoTipoOperacion> | Código de tipo de operación | AN|2 | Catálogo N° 51 | F, B, NC, ND | |
| <per:correlativo> | Correlativo del documento | N|...8 | F, B, NC, ND | ||
| <per:fechaEmision> | Fecha de emisión del documento en curso | AN|10 | YYYY-MM-DD | F, B, NC, ND | |
| <per:fechaVencimiento> | Fecha de vencimiento del documento | AN|10 | YYYY-MM-DD | F, B | |
| <per:horaEmision> | Hora de emisión del documento en curso | AN|8 | hh:mm:ss | F, B, NC, ND | |
| <per:idTransaccion> | Permite tener un control adicional con un ID interno, de lo que envían y reciben. Aparece luego en el SOAP Response | AN|...20 | F, B, NC, ND | ||
| <per:serie> | Serie del documento | AN|4 | XLLL, donde X puede valer: F: Factura o Notas asociadas |
F, B, NC, ND | |
| <per:tipoDocumento> | Tipo de documento en curso | AN|2 | Catálogo N° 01 | F, B, NC, ND |
Datos de Comprobante Relacionado
Datos de Comprobante relacionado – Información relacionada a Facturas
| Ubicación en Objeto: | tem:Enviar/tem:documentoElectronico/per:relacionado/per:Relacionado |
|---|---|
| Cantidad de Campos: | 5 |
| Descripción General: | Contiene información de los documentos relacionados con el documento en curso |
| Recurrencia de la línea: | 0...1 |
| Campo | Descripción | Tipo|Longitud | Formato | Obligatorio | Opcional |
|---|---|---|---|---|---|
| <per:numeroDocRelacionado> | Serie y número del documento relacionado con la operación que se factura | AN|...30 | ZZZZ-NNNNNNNN, donde: ZZZZ corresponde a la serie |
F | |
| <per:numeroGRRelacionada> | Número de la guía de remisión relacionada con la operación que se factura | AN|...30 | ZZZZ-NNNNNNNN, donde: ZZZZ corresponde a la serie |
F, B, NC | |
| <per:numeroOrdenCompra> | Número de la orden de compra | AN|...20 | Sin espacios, sin guiones, sin salto de línea | F, B, NC | |
| <per:tipoDocRelacionado> | Tipo del documento relacionado con la operación que se factura | N|2 | Catálogo N° 01 | F | |
| <per:tipoGRRelacionada> | Tipo de la guía de remisión relacionada con la operación que se factura | N|2 | Catálogo N° 01 | F, B, NC |
Datos de Comprobante relacionado – Información relacionada a Notas de Crédito y Débito
| Ubicación en Objeto: | tem:Enviar/tem:documentoElectronico/per:relacionadoNotas |
|---|---|
| Cantidad de Campos: | 4 |
| Descripción General: | Contiene información de los documentos afectados con la nota de crédito/débito en curso |
| Recurrencia de la línea: | 0...1 |
| Campo | Descripción | Tipo|Longitud | Formato | Obligatorio | Opcional |
|---|---|---|---|---|---|
| <per:codigoTipoNota> | Código de tipo de nota de crédito o débito | AN|2 | Catálogo N° 09 (Nota de Crédito) Catálogo N° 10 (Nota de Débito) |
NC, ND | |
| <per:numeroDocAfectado> | Serie y número del comprobante que se modifica | AN|...13 | ZZZZ-NNNNNNNN, donde: ZZZZ corresponde a la serie |
NC, ND | |
| <per:observaciones> | Motivo de emisión de la nota de crédito o débito | AN|...250 | Sin espacios, sin guiones, sin salto de línea | NC, ND | |
| <per:tipoDocAfectado> | Tipo de comprobante que se modifica | N|2 | Catálogo N° 01 | NC, ND |
Producto
| Ubicación en Objeto: | tem:Enviar/tem:documentoElectronico/per:producto/per:Producto |
|---|---|
| Cantidad de Campos: | 14 |
| Descripción General: | Contiene información base del producto, de forma individual |
| Recurrencia de la línea: | 1...n |
| Campo | Descripción | Tipo|Longitud | Formato | Obligatorio | Opcional |
|---|---|---|---|---|---|
| <per:cantidad> | Cantidad de unidades del ítem | N|(12,10) | F, B, NC, ND | ||
| <per:codigoGS1> | Sistema de codificación estándar que identifica de manera única y no ambigua cada referencia. Si no se cuenta con el código SUNAT, puede usarse éste | AN|...14 | F, B, NC, ND | ||
| <per:codigoPLU> | Código de producto del ítem, interno y de uso del establecimiento | AN|...30 | No debe tener saltos de línea | F, B, NC, ND | |
| <per:codigoPLUSunat> | Código de producto (SUNAT), basado en el estándar internacional de la ONU (UNSPSC: United Nations Standard Products and Services Code) | N|...8 | Catálogo N° 25 | * | F, B, NC, ND |
| <per:descripcion> | Descripción detallada del servicio prestado, bien vendido o cedido en uso, indicando las características | AN|...250 | F, B, NC, ND | ||
| <detalleProducto> | Informacion adicional para el producto | AN|...250 | F, B, NC, ND | ||
| <per:montoTotalImpuestoItem> | Monto total de impuestos por línea | N|(12,2) | F, B, NC, ND | ||
| <per:numeroOrden> | Número de orden del ítem | N|3 | Ordinal correlativo. no debe superar el número de ítems reportados | F, B, NC, ND | |
| <per:numeroPlacaVehiculo> | Información Adicional - Gastos art.37° Renta | AN|...100 | F | ||
| <per:precioVentaUnitarioItem> | Precio de venta unitario. Contiene impuestos | N|(12,10) | F, B, NC, ND | ||
| <per:unidadMedida> | Código de unidad de medida del ítem | AN|3 | Catálogo N° 03 | F, B, NC, ND | |
| <per:valorReferencialUnitario> | Valor referencial unitario en operaciones no onerosas, para identificar este tipo de operaciones (gratuitas, por ejemplo) | N|(12,10) | ** | F, B, NC, ND | |
| <per:valorUnitarioBI> | Valor de venta del ítem, no incluye los impuestos (base imponible) | N|(12,10) | F, B, NC, ND | ||
| <per:valorVentaItemQxBI> | Valor de venta del ítem (cantidad x base imponible) | N|(12,10) | F, B, NC, ND |
*: Este valor deberá ser obligatorio para las facturas de exportación
**: Se enviará este campo cuando el producto esté involucrado en una operación no onerosa