Descripción de la interfaz de programación

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.
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.
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:
{
"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.

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:
{
"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:
{
"message": "",
"response": {}
}
GET
/cut_paper
Corta
el
papel
de
la
línea
de
impresión.
Respuesta
de
ejemplo:
{
"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:
{
"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:
{
"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:
{
"message": "",
"response": {}
}
GET
/information/day
ó
GET
/information/shift
Obtiene
información
con
respecto
al
día
o
al
turno
actual.
Respuesta
de
ejemplo:
{
"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:
{
"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:
{
"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
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.
¡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

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.
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.
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.
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": [
{
"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": [
{
"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?
marcos@marcos.do
support@marcos.do

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

Descripción de la interfaz de programación

Descripción de la interfaz de programación

Más contenido relacionado

Destacado

Similar a Descripción de la interfaz de programación

Más de Eneldo Serrata

Descripción de la interfaz de programación