Explorar la API con Postman

La mejor manera de explorar la API SIGN DE V2 es usar una aplicación llamada Postman. Una alternativa es usar la herramienta de línea de comandos Linux/Unix curl.

Esta guía usa Postman para proporcionar ejemplos de todas las operaciones necesarias para configurar un TSS con tus clientes y transacciones asociados. Puede verificar los detalles de cada solicitud y respuesta, y probar fácilmente diferentes escenarios.

¿Qué es Postman?

Postman es una aplicación de software gratuita que facilita la exploración de APIs.

Una colección de Postman y un entorno de Postman proporcionan un sistema de prueba que incluye toda la configuración necesaria para una API particular. Simplemente cargue estos dos archivos en Postman y estará listo para comenzar a explorar y probar.

📘Entorno de prueba

Se recomienda (pero no es obligatorio) usar esta guía junto con el fiskaly HUB.

Ten en cuenta que este es un entorno de prueba, para pruebas y evaluación. Su persistencia no está garantizada. Todos los datos del entorno de prueba se borran periódicamente sin previo aviso.

📘Clientes existentes de V1

Esta es una demostración del entorno de prueba, para la cual necesitará crear nuevas cuentas temporales usadas solo para pruebas y evaluación.

Si es un cliente con una cuenta V1, tus organizaciones y claves API siguen siendo válidas para V2. ¡No necesita cambiar nada en producción!

---

Configuración

1. Descargar Postman

   Descarga la versión gratuita de Postman desde postman.com/downloads.

   Está disponible para las tres plataformas principales: Linux, macOS y Windows. Alternativamente, también hay una versión web de Postman.

2. Crear una clave API

   Antes de comenzar con Postman, necesita crear una clave y un secreto API a través del fiskaly HUB.

   

3. Descargar tu entorno personalizado

   Ve a la página de inicio rápido de la API V2 e introduce tu clave y secreto API para obtener tu entorno Postman personalizado.

   

---

Importar el entorno de la API V2

Para explorar la API SIGN DE V2 usando Postman, primero debe importar sus archivos de configuración.

1. Abrir el diálogo de importación de Postman

   Inicie Postman y, desde el diálogo de importación, selecciona Cargar archivos.

   

2. Seleccionar los archivos de colección y entorno

   Selecciona los archivos de colección y entorno que descargó anteriormente.

   

3. Verificar su espacio de trabajo

   Ahora debería poder ver 1 Colección y 1 Entorno en el espacio de trabajo de Postman.

   

4. Seleccionar el entorno

   Selecciona el entorno SIGN DE API V2 en el menú desplegable de entornos.

   

💡Tip

Para asegurarse de que está usando la versión más actualizada de la API de producción, descarga los últimos archivos de colección y entorno desde la página de inicio rápido de la API V2.

---

Ejecutar la demostración

La Colección Postman API V2 incluye ejemplos completos de cada solicitud involucrada en la configuración de un entorno TSS, desde la autenticación inicial hasta las exportaciones de datos.

Puede ejecutar estas solicitudes usando el Ejecutor de colecciones de Postman.

1. Abrir el Ejecutor de colecciones

   Selecciona Colecciones, luego Escenario estándar, y haz clic en el botón Ejecutar.

   

2. Ejecutar la colección

   Postman lista el conjunto de solicitudes a ejecutar. Haz clic en el botón Ejecutar SIGN DE API V2.

   

3. Verificar los resultados

   Debería ver un código de estado 200 del servidor para cada solicitud, lo que indica que la solicitud fue exitosa.

   

   Otras respuestas posibles incluyen 400 (problema con la solicitud) o 500 (problema con el servidor).

La demostración muestra el orden de solicitudes para:

• Autenticación inicial del administrador
• Crear y gestionar un TSS
• Crear y gestionar clientes
• Transacciones
• Exportar datos del TSS

Las siguientes secciones examinan estas solicitudes con más detalle.

---

Comprender las variables

Postman almacena valores importantes de la API en variables. Las variables se pueden reutilizar en diferentes solicitudes. Si cambia el valor de una variable, el nuevo valor se usa en todas esas solicitudes.

Cuando importa por primera vez el entorno SIGN DE API V2, contiene solo tres variables:

Variable	Descripción
baseUrl	La URL base de la API
api_key	Tu clave API
api_secret	Tu secreto API

Puede ver cómo se usa una variable en una solicitud de autenticación. Postman sustituye la variable {{baseUrl}} con el valor almacenado en el entorno SIGN DE API V2:

https://kassensichv-middleware.fiskaly.com/api/v2

Así que una solicitud de autenticación se envía realmente mediante POST a:

https://kassensichv-middleware.fiskaly.com/api/v2/auth

---

Realizar solicitudes

Hagamos una solicitud de autenticación. Es una solicitud POST enviada a {{baseUrl}}/auth.

El cuerpo de la solicitud usa variables de entorno:

{
  "api_key": "{{api_key}}",
  "api_secret": "{{api_secret}}"
}

Postman recibe la siguiente respuesta del servidor (el 200 OK en verde indica éxito):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_claims": {
    "env": "TEST",
    "organization_id": "0bd118a1-eed7-4065-9e6b-710ab3aaf445"
  },
  "access_token_expires_in": 600,
  "access_token_expires_at": 1626678863,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token_expires_in": 600,
  "refresh_token_expires_at": 1626678863
}

Obtenemos un token de acceso y un token de actualización. Postman almacena los nuevos valores en variables, que luego se usan en solicitudes posteriores.

📘Note

El token de acceso expira en 600 segundos en el entorno de prueba, después de lo cual la solicitud de autenticación debe ejecutarse de nuevo. En producción, esto es de aproximadamente 24 horas.

De manera similar, puede ver el encabezado y el cuerpo, y verificar la respuesta del servidor, para todas las demás solicitudes de esta colección.

---

Generación de código

Postman puede generar el código relevante para realizar solicitudes en una variedad de lenguajes de programación.

En este ejemplo, generaremos la solicitud de autenticación apropiada para curl.

1. Ejecutar la solicitud de autenticación

   Vuelva a ejecutar la solicitud de autenticación de la colección.

   

2. Abrir la barra lateral de fragmentos de código

   Haz clic en el icono Código en la barra lateral derecha.

   

3. Seleccionar su lenguaje

   Aparece la barra lateral de fragmentos de código. curl debería estar seleccionado por defecto; si no lo está, use el menú desplegable para seleccionarlo.

   

4. Copiar y usar el código generado

   Ahora puede ver los comandos curl que coinciden con esta solicitud de Postman. Ejecútelos en una terminal para autenticarte.

   

💡Tip

La generación de código es valiosa para scripts bash, donde puede almacenar los valores de los tokens en variables. Sin embargo, Postman hace esto automáticamente, lo que lo convierte en una herramienta conveniente para investigar APIs.

---

Referencia cruzada con el HUB

Las solicitudes de gestión de TSS y Clientes realizadas desde Postman se pueden ver en el fiskaly HUB.

Inmediatamente después de crear una nueva organización, el HUB indica que no hay Clientes, TSS, Transacciones ni Exportaciones.

Después de enviar una solicitud de autenticación seguida de una solicitud de Crear TSS desde la colección de Postman, actualiza la vista del HUB y verá el nuevo TSS listado.

Otras operaciones de Postman para gestionar TSS y Clientes también se reflejan en el HUB. El fiskaly HUB proporciona una visión general más simple de tu organización y puede gestionar directamente TSS y Clientes.

💡Tip

Use el HUB junto con Postman para verificar que sus solicitudes API están teniendo el efecto esperado en los recursos de tu organización.

---

Páginas relacionadas

Guía para nuevos clientes

Guía completa de configuración de la API

Manual del HUB

Gestión de organizaciones, TSS y clientes

Manejo de errores

Mejores prácticas para tiempos de espera y recuperación de errores