Guia de Postman
El cliente de API mas popular del mundo. Tiene collections, environments, tests automatizados y mucho mas. Lo usan empresas como Shopify, Slack y GitHub.
Un cliente de API es una app que te permite enviar peticiones HTTP (GET, POST, PUT, DELETE) sin escribir codigo. Imagina que es un "navegador especializado en APIs": en vez de pedir paginas web, pide datos a un servidor y te muestra la respuesta formateada.
Postman es el mas usado del mundo porque te permite guardar colecciones de peticiones, configurar variables de entorno (como tu API key), y compartir collections con tu equipo. Es como un Word para APIs: lo que en Word es un .docx, en Postman es una collection.
En esta guia vamos a importar la coleccion oficial de SAT API, configurar tu API key una sola vez, y hacer tu primera llamada real al SAT. Cuando termines, vas a entender el flujo basico: importar collection → configurar auth → enviar peticion → ver respuesta.
Conceptos que necesitas saber
API
Application Programming Interface. Es una forma en que dos programas se hablan. En este caso, tu app (o Postman) habla con el servidor de SAT API usando HTTP.
REST
Un estilo de diseno de APIs donde cada URL representa un "recurso" (ej: /clientes, /rfcs) y los verbos HTTP (GET, POST, DELETE) indican que quieres hacer con el.
JSON
JavaScript Object Notation. Es el formato en que se envian los datos. Se ve como {"clave": "valor"}. Es el "idioma" de las APIs modernas.
Bearer Token
Es como una "llave" que te identifica. Lo mandas en el header Authorization: Bearer tu_llave. Si la llave es valida, el servidor te deja entrar.
Collection
Una carpeta con multiples peticiones HTTP guardadas. En vez de escribir la misma peticion 50 veces, la guardas una vez y la reutilizas.
Environment
Un conjunto de variables (como api_key, base_url) que cambian segun el entorno (dev, staging, produccion). Asi puedes tener la misma collection apuntando a distintos servers.
Paso a paso
-
1
Que es Postman y por que lo vamos a usar
Postman es una app de escritorio (tambien tiene version web en go.postman.com) que existe especificamente para probar APIs. La usan mas de 30 millones de developers en el mundo. En esta guia la instalamos en escritorio porque es mas comodo para principiantes.
-
2
Ve a postman.com/downloads
Abre tu navegador y ve a https://www.postman.com/downloads. Veras 4 botones grandes: Windows, Mac, Linux x64, Linux ARM. Elige el que corresponda a tu sistema operativo.
-
3
Instala Postman
Windows: ejecuta el .exe descargado. Mac: arrastra el .dmg a Aplicaciones. Linux: descomprime el .tar.gz y ejecuta el binario dentro. La instalacion toma menos de 1 minuto.
-
4
Abre Postman por primera vez
Al abrir por primera vez, te pide crear una cuenta gratuita. <strong>Puedes saltarla</strong> haciendo click en el icono de la X o en "Skip signing in" abajo a la izquierda. Funciona igual sin cuenta.
-
5
Click en "Import" (esquina superior izquierda)
Es el boton con un icono de carpeta con una flecha apuntando hacia arriba. Al hacer click se abre un dialogo con 4 tabs: File, Folder, Link, Raw text, Code repository.
-
6
Selecciona el tab "Link" en el dialogo
Es el tercer tab. Veras un campo de texto que dice "Enter a URL or paste raw text". Ahi es donde vamos a pegar la URL de nuestra coleccion.
-
7
Copia la URL de la coleccion SAT API
En otra pestana del navegador, abre https://api.cfdi4.com/docs/postman-spec. Esa URL es un archivo JSON (la coleccion oficial de Postman v2.1). Click derecho > Copiar direccion, o selecciona el texto y Ctrl+C.
-
8
Pega la URL en Postman y click "Continue"
Regresa a Postman, pega la URL en el campo. Veras un preview con un item llamado "SAT API". Click "Continue" para confirmar.
-
9
Click "Import" para finalizar la importacion
Postman descarga el archivo, lo parsea y crea una nueva coleccion llamada "SAT API" en tu sidebar izquierdo. Veras una carpeta con subcarpetas: Authentication, Usuarios, RFCs, Vault, etc.
-
10
Expande la coleccion "SAT API" y elige un endpoint
Por ejemplo, expande "Usuarios" o "Datos fiscales" y click en una peticion. En la derecha se abre el detalle de la peticion: URL, metodo (GET/POST), headers, body.
-
11
Ve a la tab "Authorization" de la peticion
Es la segunda tab del panel central. Veras un dropdown con tipo "Inherit auth from parent" (que significa "usar el de la coleccion"). Esa es la opcion que queremos.
-
12
Click derecho en la coleccion "SAT API" > "Edit"
Esto te lleva a la configuracion de la coleccion, donde puedes poner el Bearer Token una sola vez para TODAS las peticiones de la coleccion. Mucho mejor que ponerlo peticion por peticion.
-
13
En la tab "Authorization" de la coleccion, selecciona tipo "Bearer Token"
Veras un campo "Token" en el lado derecho. Ahi es donde pegas tu API key de SAT API (la que empieza con sat_).
-
14
Pega tu API key en el campo "Token"
Ve a https://panel.cfdi4.com/mi-cuenta en otra pestana, busca tu API key (solo se muestra una vez al crearla, si no la tienes genera una nueva). Cuidando de no copiar espacios al inicio ni al final.
-
15
Click "Save" para guardar la configuracion de la coleccion
Listo. A partir de ahora TODAS las peticiones de la coleccion "SAT API" usaran automaticamente tu Bearer Token. No tienes que ponerlo en cada peticion.
-
16
Click "Send" en cualquier peticion
Veras la respuesta del servidor en el panel inferior: status code (200, 401, 404, etc), tiempo de respuesta, tamano, y el body JSON formateado.
-
17
Lee la respuesta JSON
Si todo salio bien, veras algo como {"cfdi_codigo": 1, "cfdi_texto": "OK", "data": {...}}. El campo "cfdi_codigo: 1" significa exito. Si ves otro numero, consulta el catalogo de errores en /docs/errores.
-
18
Guarda la peticion si hiciste cambios
Si modificaste headers, params o body, click Ctrl+S (Cmd+S en Mac) para guardar. Asi no pierdes tu trabajo.
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.