Guia de cURL

Paso a paso

1. 1

   Que es cURL y por que aprenderlo

   cURL existe desde 1997, es open source, y viene preinstalado en Mac, Linux, Windows 10+ y Windows 11. Saber usarlo es como saber usar Excel: no es glamorous pero es super util y todos los developers lo terminan necesitando.

2. 2

   Abre una terminal

   Windows: presiona Win+R, escribe "cmd" o "powershell", Enter. Mac: Cmd+Espacio, escribe "Terminal", Enter. Linux: Ctrl+Alt+T (en la mayoria de distros).

3. 3

   Verifica que tienes cURL instalado

   Escribe: curl --version y presiona Enter. Deberias ver algo como "curl 7.81.0" seguido de las caracteristicas. Si dice "comando no encontrado", tienes Windows 7 o anterior: descarga cURL de curl.se/windows.

4. 4

   En otra ventana, ve a /docs/ y abre cualquier endpoint

   Por ejemplo https://api.cfdi4.com/docs/endpoints. Cada endpoint tiene un boton "cURL" que copia el comando al portapapeles.

5. 5

   Click en el boton "cURL" de un endpoint

   Esto copia un comando largo a tu portapapeles. Se ve asi: curl -X POST https://api.cfdi4.com/api/v1/usuario/datos-fiscales -H "User-Agent: MiApp/1.0" -H "Authorization: Bearer sat_xxxxx" -H "Content-Type: application/json" -d '{"rfc":"XAXX010101000"}'

6. 6

   Reemplaza "sat_xxxxx" con tu API key real

   Pega el comando en un editor de texto (Notepad, VSCode), busca "sat_" y reemplaza toda la string con tu API key real.

7. 7

   Pega el comando modificado en tu terminal y presiona Enter

   Veras una explosion de texto JSON. Eso es la respuesta del servidor.

8. 8

   Para ver la respuesta formateada con colores, instala "jq"

   Mac: brew install jq. Ubuntu/Debian: sudo apt install jq. Windows: descarga de https://stedolan.github.io/jq/download/

9. 9

   Pipe la respuesta a jq para formatearla

   Agrega | jq al final del comando: curl ... | jq. Veras el JSON con colores, identado y collapsible. Mucho mas legible.

10. 10

    Para guardar la respuesta en un archivo, agrega -o archivo.json

    curl ... -o respuesta.json guarda el JSON sin imprimirlo. Util para analisis posterior o para automatizar.

11. 11

    Para ver solo el tiempo de respuesta, agrega -w "%{time_total}"

    curl -o /dev/null -s -w "Tiempo: %{time_total}s\n" https://api.cfdi4.com/health. El flag -o /dev/null descarta el body, -s es silent mode.

12. 12

    Para ver los headers de respuesta, agrega -i

    curl -i https://api.cfdi4.com/health. La "-i" (include headers) muestra los headers HTTP antes del body. Util para debuggear caching, CORS, etc.

13. 13

    Para hacer un POST con body desde archivo, usa --data-binary @archivo

    Crea un archivo body.json con tu JSON, despues: curl -X POST ... --data-binary @body.json. Util cuando el JSON es muy largo o tiene caracteres especiales.

14. 14

    Para repetir el request cada 5 segundos (monitoreo), usa watch + curl

    watch -n 5 "curl -s https://api.cfdi4.com/health | jq". watch viene preinstalado en Mac/Linux. En Windows puedes usar un loop bash o un script.

15. 15

    Para seguir redirects (3xx), usa -L

    Por defecto cURL NO sigue redirects. Si el servidor responde 301 o 302, veras el codigo pero no el body final. Agrega -L (location) para seguirlos.

16. 16

    Para ignorar errores SSL (NO recomendado en produccion), usa -k

    En desarrollo local con certificados self-signed, cURL falla con error SSL. -k los ignora. NUNCA uses -k en produccion: es un riesgo de seguridad.

17. 17

    Crea un script bash con tus comandos favoritos

    Crea un archivo test.sh con varios curls: #!/bin/bash; curl -s https://api.cfdi4.com/health; echo ""; curl -s -X POST ... Dale permisos con chmod +x test.sh y ejecutalo cuando quieras.

{
  "cfdi_codigo": 1,
  "cfdi_texto": "OK",
  "data": { ... }
}