descripción de la interfaz de programación
DESCRIPTION
Consiste en un dispositivo con el cual las aplicaciones web, se pueden comunicar con las impresoras fiscales por medio a un API que les ofrece todas la funciones y de esta forma pueda interactuar con la impresora desde el browser, es una excelente solución para todos aquellos programadores que quieran implementar las impresoras fiscales desde sus aplicaciones web o por medio a una red.NOTA: En proceso de homologación y por el momento solo funciona com impresoras EPSON.TRANSCRIPT
Descripción de la interfaz de programación (API) en su versión 7
Introducción En este documento se describe la interfaz de programación para la aplicación que interactúa con la impresora, denominada como interfaz de ahora en adelante. La interfaz es una aplicación que funciona como proxy entre las aplicaciones de usuarios y la impresora fiscal. Su propósito es servir las peticiones entrantes y transformar esas peticiones en instrucciones que las impresoras fiscales puedan ejecutar.
Modo de funcionamiento La transmisión de información entre la interfaz y las aplicaciones de usuarios es por medio del protocolo HTTP1. La interfaz solo acepta peticiones del tipo GET y POST. Aquellas peticiones cuyo verbo sea POST, el cuerpo debe de estar en formato JSON. La interfaz en cambio, sin importar cual sea el verbo de la petición, siempre retornará una respuesta con formato JSON2. El formato de las respuestas es el siguiente: Respuesta exitosa: { "status": "success", "message": "", "response": {...} } Respuesta no exitosa { "status": "error", "message": "Error message", "response": null } 1 El protocolo HTTPS no está soportado por defecto, para utilizar HTTPS, debe contactar al proveedor del software para habilitar las conexiones seguras. 2 A menos que se esté descargando un libro de ventas.
Cada respuesta siempre trae consigo un código HTTP que describe correctamente el resultado de las operaciones. De esta forma se pueden detectar los errores rápidamente sin que sea necesario analizar el cuerpo de la respuesta, esto es particularmente útil para llamadas AJAX desde lenguajes de programación como JavaScript1.
Peticiones En esta sección se describen las peticiones aceptadas por la interfaz.
GET /software_version Devuelve la versión actual del software de la interfaz. Respuesta de ejemplo: { "status": "success", "message": "", "response": { "version": "7.0-pre", "name": "FiscalInterface Marcos" } }
1 Las peticiones hechas desde JavaScript podrían estar supuestas a restricciones de dominios desde los navegadores web.
Nota Un código HTTP 500 devuelto por el API, no necesariamente representa un error interno de la interfaz, también representa un error interno de la impresora al ejecutar una acción. En estos casos es necesario analizar el cuerpo de la respuesta para determinar la fuente del error.
¡Advertencia! La codificación del texto que imprime la impresora fiscal no está correctamente definido en las especificaciones a la fecha de redacción de este documento. Por tanto, para evitar inconvenientes a la hora de impresión, se recomienda utilizar textos con codificación ASCII al transmitir datos a la interfaz.
GET /state Esta llamada devuelve información de la impresora y del estado fiscal interno. Respuesta de ejemplo: { "message": "", "response": { "fiscal_status": { "document": "none", "memory": "good", "mode": "training", "substate": "fiscal_auditory", "techmode": false, "open": false }, "printer_status": { "cover": "closed", "errors": "none", "moneybox": "closed", "printer": "receipt", "state": "online" } }, "status": "success" } El campo fiscal_status contiene información respecto del sistema de la impresora. Lo siguiente son los posibles valores de los campos de fiscal_status. Campo Descripción document Documento en proceso.
• none – Sin documentos en proceso. • final – Factura para consumidor final. • fiscal – Factura con crédito fiscal. • nofiscal – Reservado. • report – Reporte electrónico.
memory Estado de memoria fiscal.
• good – Memoria fiscal en perfecto estado. • depleted – Memoria fiscal casi llena. • full – Memoria fiscal llena. • broken – Memoria fiscal defectuosa.
mode Modo de funcionamiento del equipo. • blocked • manufacture • training • fiscal
substate Subestados • none • reserved • scanner • logo • fiscal_auditory – Auditoría de memoria en proceso. • fiscal_transaction – Auditoria de memoria transacional en
proceso. • slip – Documento en slip en proceso.
techmode Modo técnico.
• true • false
open Jornada fiscal.
• true – Jornada fiscal abierta. • false – Jornada Fiscal cerrada.
El campo printer_status provee información respecto al hardware. Lo siguiente son los posibles valores de los campos de printer_status. Campo Descripción
cover Estado de la tapa de la impresora. • closed • open
state Estado de la impresora. • online • offline
errors Errores: • none – Sin errores. • errors – Con errores.
moneybox Estado del cajón de dinero. • open • closed
printer Estación de impresión seleccionada. • receipt • slip • validation • MICR
GET /printer_information Devuelve información respecto al hardware de la impresora. Respuesta de ejemplo: { "status": "success", "message": "", "response": { "id": "107017", "serial": "P4YF002268" } } GET /advance_paper ó GET /advance_paper/:number Avanza el papel de la impresora. Por defecto 10 líneas, :number especifica la cantidad de líneas de papel que se deben avanzar. :number debe ser un número entre 1 y 99. Respuesta de ejemplo: { "status": "success", "message": "", "response": {} }
GET /cut_paper Corta el papel de la línea de impresión. Respuesta de ejemplo: { "status": "success", "message": "", "response": {} }
GET /zclose ó GET /zclose/print Cierra una jornada fiscal, realizando un cierre Z. Si se especifica print, provocará que se imprima el cierre Z. Respuesta de ejemplo: { "status": "success", "message": "", "response": { "znumber": 98 } } devuelta Campo Descripción
znumber Número de cierre Z. GET /new_shift/ ó GET /new_shift/print Cambio de cajero o cambio de turno. Si se especifica print, provocará que la impresora imprima el informe de cajero, el cual contiene la información parcial desde el último cambio de cajero o desde el inicio de la jornada fiscal. Respuesta de ejemplo: { "status": "success", "message": "", "response": {} }
¡Advertencia! El empleado de caja no debe tener acceso a esta llamada y ser capaz de ejecutarla por medio de algún botón u otro método. De ser así, será capaz de adjudicar cargos al siguiente turno. Si lo que se desea es la información parcial del turno actual, se debe utilizar un informe X en su lugar.
GET /X Realiza un informe X. Respuesta de ejemplo: { "status": "success", "message": "", "response": {} } GET /information/day ó GET /information/shift Obtiene información con respecto al día o al turno actual. Respuesta de ejemplo: { "status": "success", "message": "", "response": { "init_date": "28-10-2014", "init_time": "16:00:08", "last_znumber": 98, "invoices": 3, "documents": 0, "cancelled": 0, "first_nif": "1070170000001220", "last_nif": "1070170000001222", "total_final": 200, "total_final_itbis": 30.51, "total_fiscal": 400, "total_fiscal_itbis": 61.02, "total_final_note": 0, "total_final_note_itbis": 0, "total_fiscal_note": 0, "total_fiscal_note_itbis": 0, "total_paid": 600 } } devuelta Campo Descripción init_date Fecha de inicio. init_time Hora de inicio. last_znumber Número del último cierre Z. invoices Cantidad de documentos de venta. documents Cantidad de documentos no fiscales o
precuentas. cancelled Cantidad de documentos cancelados. first_nif NIF inicial. last_nif NIF final. total_final Total de facturas para consumidor final. total_final_itbis Total de ITBIS de facturas para consumidor final. total_fiscal Total de facturas fiscales. total_fiscal_itbis Total de ITBIS de facturas fiscales. Total_final_note Total de nota de crédito para consumidor final. Total_final_note_itbis Total de ITBIS de nota de crédito para
consumidor final. Total_fiscal_note Total de nota de crédito con crédito fiscal. Total_fiscal_note_itbis Total de ITBIS de nota de crédito con crédito
fiscal. total_paid Total pagado.
GET /document_header Obtiene la cabecera utilizada para generar los documentos no fiscales o precuentas. Respuesta de ejemplo: { "status": "success", "message": "", "response": { "text": "Lorem ipsum dolor sit amet" } }
POST /document_header Cambia el encabezado de los documentos no fiscales o precuentas. Campos de entrada Campo Descripción text Texto que servirá como encabezado de las facturas no fiscales o
precuentas. máx 400 caracteres. Respuesta de ejemplo: { "status": "success", "message": "", "response": {} }
GET /daily_book/:day/:month/:year Obtiene el libro de ventas diario, para el día, mes y año especificados en el path por: :day, :month y :year respectivamente. Respuesta de ejemplo: (ninguna) Una llamada exitosa devuelve el libro de venta mensual como un archivo de texto de extensión .txt y como nombre el serial de la impresora fiscal de donde se extrajo el libro de ventas. En caso de error, se retornará un JSON normalmente señalando la causa del error.
¡Advertencia! Esta llamada no devuelve información serializada en JSON en caso de éxito.
Información Una forma para identificar si todo ha ido bien es comprobar un código HTTP de 200 devuelto por la interfaz. Una vez que se comprueba la llamada exitosa, el nombre del archivo está incluido en el campo Content-‐Disposition, según lo dispuesto por el documento RFC-‐6266. http://tools.ietf.org/html/rfc6266
¡Advertencia! Esta llamada requiere una cantidad de procesamiento considerable de parte de la impresora fiscal. Tiene un tiempo de duración considerable y la impresora no acepta más peticiones durante este tiempo.
POST /invoice Imprime una factura fiscal o un documento de no venta o precuenta. Campos de entrada Campos Descripción type1 Especifica el tipo de factura para imprimir. Admite los
siguientes valores:
• document – documento de no venta o precuenta. • nofiscal – documento de no venta o precuenta. • final – Factura para consumidor final. • fiscal – Factura con derecho a crédito fiscal. • special – Factura con derecho a crédito fiscal con
exoneración de ITBIS. • final_note – Factura nota de crédito a consumidor
final. • fiscal_note – Factura nota de crédito con derecho a
crédito final. • special_note – Factura con derecho a crédito fiscal
con exoneración de ITBIS.
copy Realiza una copia del documento. Admite los siguientes valores:
• true – Imprime una copia. • false – No imprime copia extra.
Nota: Campo opcional, por defecto no se imprimen copias.
cashier Especifica el número de la caja donde está conectada impresora. Nota: Este campo solo admite valores numéricos. Es obviado al tratarse de un documento no fiscal o precuenta.
subsidiary Especifica el número de la sucursal donde está la caja de la impresora. Nota: Este campo solo admite valores numéricos. Es obviado al tratarse de un documento no fiscal o precuenta.
ncf2 Especifica el NCF de la factura. Nota: Este campo es opcional para facturas para consumidor final. Este campo es obviado si se trata de un documento no fiscal o precuenta.
1 Los valores document y nofiscal se pueden usar de forma intercambiable. 2 Los documentos de no venta o precuentas no imprimen muestran el NCF porque no son documentos de venta como su nombre lo dice.
reference_ncf Especifica el NCF de referencia para facturas notas de crédito. Nota: Este campo es obligatorio cuando se emita una nota de crédito y es obviado al tratarse de un documento no fiscal o precuenta.
client Especifica la razón social del comprador. Nota: Este campo es obligatorio cuando se emitan facturas con derecho a crédito fiscal.
rnc Especifica el RNC del comprador. Nota: Este campo es obligatorio cuando se emitan facturas con derecho a crédito fiscal.
items Este campo es una array de objetos que contienen los campos con los detalles de los ítems que se imprimirá en la factura. Nota: Por su extensión, este campo será descrito de forma independiente.
payments Este campo es una array de objetos que contienen los campos con los detalles de los pagos de la factura. Nota: Por su extensión, este campo será descrito de forma independiente.
discounts1 Este campo puede ser un array de objetos o un simple objeto. Contiene los descuentos a nivel de subtotal de la factura. Nota: Por su extensión, este campo será descrito de forma independiente.
charges Este campo puede ser un array de objetos o un simple objeto. Contiene los cargos a nivel de subtotal de la factura. Nota: Por su extensión, este campo será descrito en una tabla aparte.
comments Este campo es un array que contiene todos los comentarios que serán impresos en la factura. Nota: Admite máx. 10 comentarios y cada línea de comentario debe ser menor o igual a 40 caracteres.
1 En las facturas, los descuentos serán impresos primero que los cargos sin importar el orden en que hayan sido enviados.
Descripción de los objetos del campo items. Campo Descripción description Descripción del ítem de venta. extra_description Array de descripciones extras del ítem de venta. quantity Cantidad de ítems. Este valor debe ser mayor
que cero. price Precio unitario del ítem con ITBIS incluido.
Nota: Este valor puede ser cero1, pero no puede ser negativo.
itbis Por ciento de ITBIS. Solo admite uno de los siguientes valores:
• 18 • 13 • 11 • 8 • 5 • 02
discount Aplica un descuento para aplicar al ítem en porciento. Nota: El valor de este campo debe ser menor que 100%
charges Aplica un cargo para aplicarlo al ítem en porciento. Nota: El valor de este campo debe ser mayor que 100%
1 Ver apéndice. 2 Los ítems con ITBIS de tasa cero son los exentos de ITBIS. p. ej. El agua.
Descripción de los objetos del campo payments. Campo Descripción type Especifica el tipo de pago. Los valores admitidos
por este campo son: • cash – efectivo. • Check – cheque. • credit_card – Tarjeta de crédito. • debit_card – Tarjeta de debito. • card – Tarjeta. • coupon – Cupón. • other – Otro. • credit_note – Nota de crédito.
amount Monto de pago. Nota: Los valores deben ser mayor que cero.
description Descripción del pago. Descripción de los objetos del campo discounts Campo Descripción amount Monto del descuento.
Nota: Los valores deben ser mayor que cero.
description Descripción del descuento. Descripción de los objetos del campo charges Campo Descripción amount Monto del cargo.
Nota: Los valores deben ser mayor que cero.
description Descripción del cargo.
Nota importante Esta llamada asume que el impuesto está incluido en los precios.
Ejemplos de llamadas JSON Campos de entrada para imprimir una factura para consumidor final, con un ítem con un valor de 100 $RD y una tasa de impuesto de 18% en la caja 1 de la sucursal 2. Pago en efectivo de 500 $RD. { "type": "final", "cashier": 1, "subsidiary": 2, "items": [ { "description": "Lorem Ipsum.", "quantity": 1, "price": 100, "itbis": 18 } ], "payments": [ { "type": "cash", "amount": 500 } ] }
Campos de entrada para imprimir una factura con derecho a crédito fiscal con dos comentarios, dos ítems, uno con una tasa de ITBIS de 18% y con un costo de 100 $RD y otros dos ítems del mismo tipo exentos de impuestos con un costo de 50 $RD cada uno . Pago de 400 $RD con tarjeta de crédito. En la caja 2 de la sucursal 4. { "type": "fiscal", "cashier": 2, "subsidiary": 4, "ncf": "A000010011001000000", "client": "Client name", "rnc": "40223036317", "items": [ { "description": "Lorem Ipsum.", "quantity": 1, "price": 100, "itbis": 18 }, { "description": "Dolor sit amet.", "quantity": 2, "price": 50, "itbis": 0 } ], "payments": [ { "type": "credit_card", "amount": 400, "description": "Tarjeta Mastercard" } ], "comments": ["comentario1", "comentario2"] }
Ejemplo de una factura para crédito fiscal que contempla el uso de descuento, cargos y varias formas de pago. { "type": "fiscal", "cashier": 1, "subsidiary": 2, "ncf": "A000010011001000002", "client": "Comprador", "rnc": "40223036317", "items": [ { "description": "Lorem Ipsum.", "quantity": 1, "price": 310, "itbis": 18 } ], "charges": [ { "description": "Cargo combustible", "amount": 0.6 },{ "description": "Impuestos DGA", "amount": 0.15 } ], "discounts": [ { "description": "Descuento promo", "amount": 68 } ], "payments": [ { "type": "cash", "amount": 100 },{ "type": "debit_card", "amount": 300 } ], "comments": [ "Gracias por visitarnos, vuelva pronto" ] }
Conclusión A la hora de trabajar con la interface, todo lo descrito por este documento antepone cualquier otro documento o especificación. En caso de que haya algún caso que no esté descrito, se deberá proceder según lo indicado por los estándares de programación y en caso de existir un caso particular no descrito por este documento ni por los estándares de programación, se deberá hacer un reporte al proveedor indicando el error en los procedimientos y la documentación. Internamente la interfaz utiliza métodos y funciones de alta precisión para el manejo de cantidades decimales, de modo que la integridad de las cantidades manejadas por la interfaz está garantizada. La información descrita en este documento es de carácter confidencial y no debe ser utilizadas por personas que no estén autorizadas por Marcos Organizador De Negocios S.R.L. Este documento ha sido escrito y redactado por Manuel A. Güílamo. ¿Dudas o sugerencias? [email protected] [email protected]
Apéndice
Formato de decimales de las precuentas Por defecto el separador de los miles es la coma “,”, y no hay forma de cambiarlo a través del API descrita en este documento. Se optado por utilizar la coma como separador de miles porque es el separador por defecto utilizado en República Dominicana y porque la interfaz está dirigida para el uso en este país. En futuras versiones se incluirán opciones para sobrescribir este propiedad.
Ajuste por redondeo Debido a los errores de redondeos causados por la utilización de números decimales en los ordenadores o por el precio de algunos ítems, el software tiene una tolerancia máxima de -‐0.02 centavos para los pagos, es decir, que si la suma de los pagos de una factura resulta insuficiente y el monto restante por pagar es menor o igual a 0.02 centavos, se realizará un ajuste por redondeo de forma automática. El ajuste por redondeo consiste en aplicar un descuento por el monto restante por pagar, siempre y cuando dicho monto restante resulte de un posible error de redondeo, es decir, menor o igual a 0.02 centavos1.
Ítems con precio cero La posibilidad de incorporar ítems con valor cero, es una característica muy útil aunque no lo parezca a simple vista. Gracias a esta propiedad es posible listar las características de un producto o servicio en una factura. A modo de ejemplo tómese un restaurantes de hamburguesas, donde cada ingrediente extra que un cliente añade a su hamburguesa posee un costo adicional. ¿Cómo se imprimiría una factura que refleje el costo de una hamburguesa con queso extra y sin cebollas extras, de modo que el cliente pueda ver los costos adicionales de su compra y que el encargado de ventanilla pueda ver antes de preparar la hamburguesa que ingredientes adicionales lleva y cuales no? La respuesta es, utilizando ítems de precio cero, tal y como lo muestra la siguiente imagen:
1 http://www.impresoras-‐fiscales.com.ar/manuales/web/epson/redondeo.htm
