Diferencia entre revisiones de «Integración Directa - Web Service REST»

De Facturacion Electronica de Peru
Ir a la navegación Ir a la búsqueda
 
(No se muestra una edición intermedia del mismo usuario)
Línea 248: Línea 248:
|<!---Campo--->          style="color: blue; text-align:center" | documento
|<!---Campo--->          style="color: blue; text-align:center" | documento
|<!---Descripción--->    Tipo, serie y correlativo de documento a dar de baja
|<!---Descripción--->    Tipo, serie y correlativo de documento a dar de baja
|<!---Tipo|Longitud--->  style="text-align:center;"| AN<nowiki>|</nowiki>...16
|<!---Tipo|Longitud--->  style="text-align:center;"| AN<nowiki>|</nowiki>...28
|<!---Formato--->        style="text-align:center;"| TT-XZZZ-NNNNNNNN <br/>
|<!---Formato--->        style="text-align:center;"| RRRRRRRRRRR-TT-ZZZZ-NNNNNNNN <br/>
  Donde TT hace referencia al tipo de documento según catálogo N° 01 <br/>
Donde RRRRRRRRRRR hace referencia al RUC del emisor</br>
  X hace referencia al tipo de documento: <br/>
  TT hace referencia al tipo de documento según catálogo N° 01 <br/>
  F: Factura o notas asociadas <br/>
  ZZZZ hace referencia a la serie <br/>
  B: Boletas o notas asociadas <br/>
  ZZZ hace referencia a la serie <br/>
  NNNNNNNN hace referencia al correlativo
  NNNNNNNN hace referencia al correlativo
|-
|-
Línea 302: Línea 300:
|<!---Descripción--->    Tipo, serie y correlativo de documento a consultar
|<!---Descripción--->    Tipo, serie y correlativo de documento a consultar
|<!---Tipo|Longitud--->  style="text-align:center;"| AN<nowiki>|</nowiki>...16
|<!---Tipo|Longitud--->  style="text-align:center;"| AN<nowiki>|</nowiki>...16
|<!---Formato--->        style="text-align:center;"| TT-XZZZ-NNNNNNNN <br/>
|<!---Formato--->        style="text-align:center;"| RRRRRRRRRRR-TT-ZZZZ-NNNNNNNN <br/>
  Donde TT hace referencia al tipo de documento según catálogo N° 01 <br/>
Donde RRRRRRRRRRR hace referencia al RUC del emisor</br>
  X hace referencia al tipo de documento: <br/>
  TT hace referencia al tipo de documento según catálogo N° 01 <br/>
  F: Factura o notas asociadas <br/>
  ZZZZ hace referencia a la serie <br/>
  B: Boletas o notas asociadas <br/>
  ZZZ hace referencia a la serie <br/>
  NNNNNNNN hace referencia al correlativo
  NNNNNNNN hace referencia al correlativo
|-
|-

Revisión actual del 16:48 24 ene 2025

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á mediante el envío de un objeto, llenado directamente sobre el request del método RetencionPercepcion
  • Para el consumo de los métodos, los nodos aparecen publicados en forma alfabética

Paso a Paso

Enviar un documento electrónico

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; así como invocar el método RetencionPercepcion para el envío de los Comprobantes de Retención y/o Percepción.

Conexión para la emisión

Antes de realizar cualquier envío, previamente deberá consumirse el método Autenticacion que generará un token de seguridad, el cual será utilizado para todos los métodos del servicio. Según sea el caso, se debe invocar el método “Enviar” o “RetencionPercepcion”, ambos disponibles en el WS de The Factory HKA. El método se debe llenar con el objeto del request para documentos o comprobantes de venta. Este método es el encargado de abrir 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.
El enlace de acceso a nuestro ambiente de pruebas es https://demoint.thefactoryhka.com.pe/Service.svc.

Autenticacion

Descripción Permite la generación del token de acceso para el consumo del resto de los métodos, tomando como entrada

las credenciales generadas por Integraciones o desde el portal de emisión

Respuesta Exitosa Código, Mensaje

Parámetros de Entrada

Nombre del método Autenticacion
Cantidad de Campos: 4
Campo Descripción Tipo|Longitud Formato
clave Contraseña de Integración, emitida por el sistema
ruc RUC del emisor N|11
tipoAplicacion Indica el medio de envío. El valor fijo es I, de Integraciones N|1 I
usuario Usuario de Integración, emitido por el sistema


Enviar

Artículo principal: Web Service REST - 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

NOTA: El registro de los campos aparece en orden alfabético en este artículo, tal como en el objeto del método

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: 4
Campo Descripción Tipo|Longitud
certificadoBase64 Certificado autorizado, codificado en base 64
certificadoClaveBase64 Clave del certificado, codificado en base 64
ruc RUC del emisor N|11
token Token de seguridad, generado en el método Autenticacion

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: 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 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
documento Tipo, serie y correlativo de documento a dar de baja AN|...28 RRRRRRRRRRR-TT-ZZZZ-NNNNNNNN

Donde RRRRRRRRRRR hace referencia al RUC del emisor
TT hace referencia al tipo de documento según catálogo N° 01
ZZZZ hace referencia a la serie
NNNNNNNN hace referencia al correlativo

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

ruc RUC del emisor N|11
token Token de seguridad, generado en el método Autenticación

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.
Respuesta Exitosa Código, Mensaje

Parámetros de Entrada

Nombre del método EstatusDocumento
Cantidad de Campos: 3
Campo Descripción Tipo|Longitud Formato
documento Tipo, serie y correlativo de documento a consultar AN|...16 RRRRRRRRRRR-TT-ZZZZ-NNNNNNNN

Donde RRRRRRRRRRR hace referencia al RUC del emisor
TT hace referencia al tipo de documento según catálogo N° 01
ZZZZ hace referencia a la serie
NNNNNNNN hace referencia al correlativo

ruc RUC del emisor N|11
token Token de seguridad, generado en el método Autenticación

Reversión

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
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

motivo Motivo de la reversión AN|...200
ruc RUC del emisor N|11
token Token de seguridad, generado en el método Autenticacion

GuiaRemision

Artículo principal: Web Service REST - Método GuiaRemision

El método GuiaRemision permite la generación de los siguientes documentos:

  • Guía de Remisión Electrónica.

NOTA: El registro de los campos aparece en orden alfabético en este artículo, tal como en el objeto del método

Descripción Método para enviar documentos (Guías de Remisión Electrónicas) a SUNAT
Respuesta Exitosa Código de aceptación | Mensaje de aceptación | Serie - correlativo del documento y XML timbrado
Obtenido de «http://felwiki.thefactoryhka.com.pe/index.php?title=Integración_Directa_-_Web_Service_REST&oldid=1315»