Guia de Insomnia
Cliente open-source, limpio y potente. Es el favorito de muchos developers senior por su interfaz minimalista y sus scripts de test.
Insomnia es un cliente de APIs que compite directamente con Postman. Su filosofia es: "menos clicks, mas API". La interfaz es mas limpia y tiene menos botones que Postman, lo que lo hace ideal si te agobian los IDEs muy cargados.
Es open source (codigo abierto), lo que significa que puedes auditar exactamente que hace con tus credenciales. Lo recomienda gente de Netflix, IBM y NASA.
En esta guia instalamos Insomnia, importamos la spec OpenAPI de SAT API, configuramos el Bearer Token y hacemos nuestra primera llamada. La diferencia clave con Postman: Insomnia usa spec OpenAPI (un estandar de la industria) en vez de su propio formato de collections.
Conceptos que necesitas saber
OpenAPI
Un estandar abierto (antes llamado Swagger) para describir APIs. Es un archivo YAML o JSON que dice: "mi API tiene estos endpoints, estos parametros, estas respuestas". Postman, Insomnia y muchas otras herramientas lo entienden.
Environment
Igual que en Postman: un conjunto de variables reutilizables (api_key, base_url) que puedes cambiar entre dev/staging/produccion sin tocar las peticiones.
Base Environment
Un environment "global" que se aplica a TODAS las peticiones sin tener que seleccionarlo. Util para poner tu API key una sola vez.
Response
Lo que el servidor te devuelve. Tiene 4 partes: status code (200, 404, 500), headers (metadata), body (los datos), tiempo de respuesta.
JSON Path
Una forma de extraer un campo especifico de un JSON. Como $.data.nombre extrae el campo "nombre" dentro de "data". Util cuando quieres ver un solo campo sin todo el JSON.
Paso a paso
-
1
Que es Insomnia y por que elegirlo sobre Postman
Insomnia fue creado por Kong (la empresa detras del API Gateway mas popular). Su diferenciador: interfaz minimalista, open source, y soporte nativo de OpenAPI. Si vienes de Postman te sentiras como en casa pero mas limpio.
-
2
Ve a insomnia.rest y descarga la version gratis
https://insomnia.rest/download. Elige tu OS. La app pesa ~80 MB (vs 200+ de Postman). Es mas ligera.
-
3
Instala y abre Insomnia
Windows: ejecuta el .exe. Mac: arrastra al Applications. Linux: AppImage o .deb. La primera vez te preguntara si quieres crear cuenta o saltar. <strong>Recomendamos saltar</strong> para empezar rapido.
-
4
Crea un nuevo "Design Document" (boton + en el sidebar)
El sidebar izquierdo es donde viven tus "documentos" (equivalente a collections de Postman). Click en el + azul para crear uno. Nombralo "SAT API".
-
5
Ve al menu "Application" > "Preferences" > "Data" > "Import Data"
Esto abre un dialogo. Veras opciones: "From File", "From URL", "From Clipboard".
-
6
Selecciona "From URL" y pega la spec de SAT API
Pega https://api.cfdi4.com/docs/openapi-spec. Es la spec OpenAPI 3.0 oficial. Insomnia la descarga, la parsea y crea automaticamente todas las peticiones.
-
7
Click "Import" y "Scan and Import"
Insomnia escanea el archivo y te muestra la lista de endpoints. Veras 33 endpoints organizados por tag (Authentication, Usuarios, RFCs, etc). Click "Import" para traerlos todos.
-
8
Expande el documento "SAT API" y elige una peticion
Por ejemplo, expande "Authentication" > "POST /api/v1/auth/login". La peticion se abre en el panel central.
-
9
En la tab "Auth" selecciona tipo "Bearer Token"
Veras un campo "TOKEN" abajo. Ahi pegas tu API key de SAT API. Esta config aplica solo a esta peticion. Para hacerlo global: usa "Base Environment" (siguiente paso).
-
10
Ve a "Manage Environments" (icono de folder en el sidebar)
Crea un nuevo environment llamado "SAT API - Produccion" (o el nombre que quieras). Este environment se aplicara a TODAS las peticiones.
-
11
En el environment, agrega una variable: api_key = tu_API_key
Click "+ Add Pair", nombre "api_key", valor tu API key real (la que empieza con sat_). Puedes agregar mas variables despues, como base_url.
-
12
Activa el environment en el dropdown superior derecho
Hay un dropdown que dice "No Environment" (o el nombre del que estes usando). Cambialo a "SAT API - Produccion" para activarlo.
-
13
Para que el Bearer Token use la variable, edita la peticion y en Auth selecciona "Bearer" con valor {{ api_key }}
Las dobles llaves {{ }} son la sintaxis de Insomnia para variables. Asi, si cambias la variable en el environment, todas las peticiones se actualizan.
-
14
Click "Send" en la peticion
Veras el response abajo: status code (200, 401, etc), tiempo en ms, tamano, y el body JSON.
-
15
Inspecciona la respuesta con el JSON viewer
Insomnia tiene un tree view para colapsar/expandir objetos JSON. Click en cualquier campo para ver su tipo y valor. Ideal para entender respuestas grandes.
-
16
Si quieres ver solo un campo, usa "Filter" en la tab Response
Hay un campo de busqueda arriba del JSON. Escribe el nombre de un campo (ej: "cfdi_codigo") y filtra al instante.
-
17
Usa "Generate Code" (icono </>) para convertir a codigo
Si quieres pasar de Insomnia a codigo real, click en el icono </>. Te genera snippets en Python, JavaScript, cURL, etc. Listo para copiar.
Verificar que funciona
Si todo salio bien, deberias ver una respuesta JSON con cfdi_codigo: 1. Si ves error 401, revisa que tu API key este bien copiada (sin espacios al inicio/final).
{
"cfdi_codigo": 1,
"cfdi_texto": "OK",
"data": { ... }
}Problemas comunes
Error 401: Unauthorized
Tu API key no es valida o no la pusiste bien. Revisa que: 1) Empiece con sat_, 2) No tenga espacios, 3) El RFC este activo en el panel.
Error 403: Forbidden
Tu user-agent es muy generico. Anade -H \"User-Agent: MiApp/1.0\" a tu peticion.
Error 429: Too many requests
Superaste el rate limit (60 req/min). Espera 60 segundos.
Error 500: Internal server error
El upstream del SAT esta teniendo problemas. Reintenta en unos minutos. Si persiste, contactanos.
Error 503: Service unavailable
El sistema esta en mantenimiento. Revisa panel.cfdi4.com para avisos.
No me aparece la coleccion al importar
Asegurate de usar la URL exacta. Algunos clientes requieren la spec OpenAPI, otros la coleccion Postman. Revisa el paso correspondiente.