API del sistema TPVPunto de entrada único desde tu POS a fiskaltrust.Middleware.
Crea recibos, ejecuta pagos, emite recibos digitales y exporta diarios a través de una API HTTP basada en procesos
La API te permite centrarte en tu sistema mientras fiskaltrust se ocupa de la infraestructura de recibos. En lugar de tratar los recibos como una función secundaria o un complemento para el consumidor, la API de recibos gestiona los recibos como un componente del sistema regulado de primera clase. Lo integras una vez y confías en una API unificada y de código abierto que se mantiene a medida que evolucionan las normativas y los requisitos operativos.
La API del Sistema de TP V de fiskaltrust sirve como interfaz central entre los sistemas de TPV y el Middleware de fiskaltrust. Ofrece un amplio conjunto de funcionalidades, como la fiscalización (o firma) de recibos, la ejecución de pagos a través de varios proveedores, la impresión digital de recibos y la exportación de datos desde el Middleware.
Mediante puntos finales sencillos y coherentes, la API admite funciones clave: /echo para pruebas de conectividad, /order para registrar datos de pedidos, /pay para la asignación de pagos, /sign para el sellado conforme de transacciones, /issue para generar recibos digitales o imprimibles, y /journal para exportaciones listas para auditoría.
Puntos finales de la API de fácil lectura
PosSystem-API internacional
- /echo,chequeo y reinicio.
- /order,registrar la información del pedido y el estado o resultado de la consulta.
- /pay,ejecuta los pagos, espera a que se completen con tiempos de espera, recupera el resultado.
- /sign,finalizar los recibos con las normas nacionales y el encadenamiento de hash.
- /issueCrea y actualiza el recibo emitido, incluido el estado de la entrega.
- /journal,recuperar entradas individuales o rangos para auditorías y cierres.
API para distribuidores de TPV. Creada para integraciones estables, transparentes y a prueba de auditorías en .
Diseñada para un uso multiplataforma, la API admite implantaciones locales e instancias alojadas en la nube en centros de datos europeos. Proporciona almacenamiento a prueba de revisiones y se integra con el Middleware fiskaltrust para actualizaciones automáticas de conformidad.
Partes de la API y el Middleware son de código abierto, lo que ofrece transparencia y estabilidad a largo plazo. Con documentación abierta y un modelo de datos uniforme, esto reduce el esfuerzo de mantenimiento y mantiene las soluciones de TPV a prueba de auditorías.
Una API, un comportamiento coherente, independientemente de los requisitos específicos de cada país.
Conceptos básicos
La API trata una transacción como un viaje. Cada paso cambia el estado en el servidor. En cada llamada pasas un identificador de operación único. Si la red se cae, repites la misma llamada con el mismo identificador.
El backend deduplica y devuelve el primer resultado completado. Este diseño proporciona reintentos seguros y resultados predecibles para los pasos fiscales críticos.
- Punto de entrada central al Middleware para la fiscalización, los pagos, la emisión y las exportaciones.
- Patrones de llamada procesuales y con estado que se comportan como una máquina de estados.
- Idempotencia mediante cabecera x-operation-id con respuestas deterministas al reintentar.
- Ganchos de retrollamada para observar las transiciones de estado durante operaciones largas.
Una solicitud con x-operation-id entra en el Middleware
Middleware procesamiento
Reintentar con el mismo x-operation-id
Completado resultado
Punto final de devolución de llamada x-operation-callback-state
Autenticación y versionado
El acceso está limitado por CashBox. Utilizas CashBoxId y AccessToken del Portal. La API sigue el versionado semántico. Los cambios de última hora se limitan a las versiones principales y pueden fijarse en la URL cuando sea necesario.
- Credenciales: CashBoxId y AccessToken.
- Versionado semántico, el último por defecto, con posibilidad de anclaje explícito.
Desarrollador de TPV
Autenticación CashBoxId + AccessToken
V1
V2
V3
PatronesAPI asíncronos
La API te permite centrarte en tu sistema mientras fiskaltrust se ocupa de la infraestructura de recibos. En lugar de tratar los recibos como una función secundaria o un complemento para el consumidor, la API de recibos gestiona los recibos como un componente del sistema regulado de primera clase. Lo integras una vez y confías en una API unificada y de código abierto que se mantiene a medida que evolucionan las normativas y los requisitos operativos.
Cabeceras e idempotencia
Cada llamada crítica acepta cabeceras de control. x-operation-id es tu clave de idempotencia. x-operation-lifetime define cuánto tiempo es válida la operación. Puedes establecer una URL de devolución de llamada por llamada para recibir mensajes de estado sin sondeo.
- x-operation-id, único por operación para deduplicar los reintentos.
- x-operation-lifetime, ventana de aceptación en milisegundos.
- x-operation-callback-state, notificar en cada cambio de estado.
- Opcional x-terminal-id y x-possystem-id para atribución.
Estado de entrega y recepción
Después de emitir, puedes recuperar el contenido emitido, actualizarlo o consultar el estado de la entrega. Existen puntos finales de bloqueo que esperan hasta un tiempo máximo de espera e informan de si se ha entregado o no. Esto simplifica los flujos de usuario en la compra y evita el sondeo ocupado.
Entornos
La API proporciona entornos sandbox y de producción para cada punto final. Utiliza el entorno aislado para las pruebas de integración y automatizadas. Promueve las mismas llamadas a producción cuando estén listas. La AynchronousAPI, las cabeceras y las llamadas de retorno se comportan igual en ambos entornos.
Tratamiento de errores
Las peticiones devuelven códigos de estado HTTP estándar. Las peticiones malformadas o las cabeceras que faltan producen errores de cliente. Los fallos de autenticación devuelven no autorizado. El servidor informa de los errores inesperados con detalles del problema, si están disponibles. Los reintentos con el mismo identificador de operación devuelven el primer resultado finalizado.
Utiliza una interfaz abierta y documentada que se adapte a medida que cambie la normativa.
Cómo funciona en 3 pasos
Configuras una Caja en el Portal y obtienes credenciales. Tu TPV llama al carro, al pedido y al pago para construir el recorrido. Completas con firmar y emitir, y luego lees los asientos para el cierre diario o las auditorías. Repites los pasos fallidos con seguridad reutilizando el identificador de la operación.
1.
Inscríbete en fiskaltrust.Portal.
2.
Crea una caja y conéctala a tu TPV o ERP.
3.
Conduce el viaje: carro, pedido, pago, firma, emisión.
Aspectos esenciales para desarrolladores
Empieza por la especificación OpenAPI y la documentación en vivo. Revisa los diagramas de la SynchronousAPI y el contrato de cabecera. Construye reintentos con idempotencia y devoluciones de llamada. Utiliza el sandbox para validar las transiciones de estado y el comportamiento de entrega de recibos antes de la producción.
- Página de documentos de la API del sistema TPV y archivo OpenAPI.
- Diagramas de temporización y estado de la SynchronousAPI.
- Sandbox endpoints para eco, carrito, pedido, pago, firma, emisión, diario.
¿Preguntas sobre la integración? Nuestro equipo técnico está a sólo un mensaje de distancia.
Contacta con nosotros