Explorar guías rápidas · APIs
Referencia rápida de cURL
Usa cURL para probar y diagnosticar APIs HTTP con patrones prácticos para métodos, encabezados, autenticación, cuerpos JSON, archivos, redirecciones, tiempos de espera, reintentos, inspección de respuestas y diagnóstico seguro en producción.
En esta página
- Problema
- Respuesta rápida
- Código / comandos
- 1. Solicitud GET simple
- 2. Enviar un método HTTP explícito
- 3. Añadir un encabezado Accept
- 4. Enviar JSON
- 5. Usar --json para solicitudes JSON
- 6. Enviar JSON desde un archivo
- 7. Enviar los bytes sin procesar del cuerpo de la solicitud desde un archivo
- 8. Añadir un token Bearer
- 9. Autenticación Basic
- 10. Clave de API en un encabezado
- 11. Clave de API en la cadena de consulta
- 12. Añadir varios encabezados
- 13. Enviar parámetros de consulta de forma segura
- 14. Enviar datos de formulario codificados como URL
- 15. Enviar datos de formulario multipart
- 16. Subir un archivo directamente
- 17. Descargar un archivo con un nombre concreto
- 18. Conservar el nombre de archivo proporcionado por el servidor
- 19. Seguir redirecciones
- 20. Mostrar los encabezados y el cuerpo de la respuesta
- 21. Guardar los encabezados de la respuesta por separado
- 22. Mostrar solo los encabezados de la respuesta
- 23. Imprimir solo el código de estado HTTP
- 24. Imprimir el estado y los tiempos
- 25. Imprimir los tiempos de DNS y TLS
- 26. Fallar ante errores HTTP conservando una salida útil
- 27. Usar una salida apta para scripts
- 28. Establecer un tiempo de espera de conexión
- 29. Establecer un tiempo de espera global
- 30. Reintentar fallos transitorios
- 31. Ten cuidado al reintentar POST/PATCH/DELETE
- 32. Usar una clave de idempotencia cuando la API la admita
- 33. Ampliar los reintentos solo cuando esté justificado
- 34. Inspeccionar el detalle verboso de la solicitud y la respuesta
- 35. Nunca pegues la salida verbosa en público sin revisarla
- 36. Usar la salida de traza para depurar el protocolo en profundidad
- 37. Forzar HTTP/1.1 para comparar
- 38. Solicitar HTTP/2 cuando esté admitido
- 39. Inspeccionar la versión HTTP negociada
- 40. Inspeccionar la IP remota
- 41. Sobrescribir el DNS para una sola solicitud
- 42. No edites /etc/hosts solo para probar un endpoint
- 43. Establecer el encabezado Host con cuidado
- 44. Usar un proxy de forma explícita
- 45. Omitir el proxy para hosts concretos
- 46. Mostrar los encabezados de la solicitud con -v, pero sin exponer tokens
- 47. Enviar cookies
- 48. Guardar las cookies de la respuesta
- 49. Enviar más tarde las cookies guardadas
- 50. Enviar un User-Agent personalizado
- 51. Añadir un ID de correlación
- 52. Inspeccionar los encabezados de límite de tasa
- 53. Respetar Retry-After
- 54. Enviar solicitudes GET condicionales con ETag
- 55. Enviar solicitudes condicionales por fecha de modificación
- 56. Descargar y reanudar un archivo grande
- 57. Limitar la velocidad de descarga para pruebas controladas
- 58. Indicar compatibilidad con respuestas comprimidas
- 59. Inspeccionar el tipo de contenido
- 60. Detectar páginas de error HTML de proxies o gateways
- 61. Escribir el cuerpo y el estado por separado en un script de shell
- 62. Comprobar el código de salida del proceso de cURL
- 63. Un HTTP 500 puede producir el código de salida 0 de cURL sin --fail
- 64. Usar HEAD solo para metadatos cuando el servidor lo admita
- 65. Probar manualmente una solicitud preflight de CORS
- 66. Probar directamente un endpoint OPTIONS
- 67. Enviar JSON con PATCH
- 68. Enviar DELETE
- 69. Evitar poner secretos directamente en la línea de comandos
- 70. Usar un archivo de configuración para solicitudes repetibles
- 71. Usar .netrc solo cuando su modelo de seguridad encaje
- 72. Probar la verificación TLS de forma normal
- 73. Evitar -k / --insecure como solución habitual
- 74. Usar un certificado de CA personalizado cuando corresponda
- 75. Usar un certificado de cliente cuando se requiera mTLS
- 76. Depurar el nombre de host/TLS por separado del comportamiento HTTP
- 77. Comparar el comportamiento de la API con y sin redirecciones
- 78. Ten cuidado al enviar credenciales a través de redirecciones
- 79. Comprobar el tamaño del cuerpo de la respuesta
- 80. Imprimir una línea de diagnóstico compacta
- Qué significa el resultado
- Qué revisar
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 429 Too Many Requests
- 5xx
- Tiempo de DNS elevado
- Conexión rápida pero TTFB alto
- Fallo de TLS
- Notas de producción
- cURL es una herramienta de reproducción excelente
- Protege los secretos
- Los reintentos deben respetar la idempotencia
- --insecure cambia el modelo de seguridad
- El diagnóstico de rendimiento necesita varios tiempos
- La sintaxis del shell difiere entre entornos
- Las llamadas de producción que cambian el estado requieren una intención explícita
- Errores comunes
- 1. Confundir Accept y Content-Type
- 2. Evaluar el éxito HTTP solo con el código de salida de cURL
- 3. Usar -k para «arreglar» TLS
- 4. Imprimir tokens en logs verbosos
- 5. Reintentar solicitudes POST a ciegas
- 6. Construir cadenas de consulta a mano sin codificarlas
- 7. Usar --data para payloads binarios
- 8. Suponer que HEAD se comporta exactamente igual que GET
- 9. Ignorar las redirecciones
- 10. Tomar una sola muestra de tiempo como prueba de rendimiento
- Siguiente paso
- Para profundizar
Problema
Necesitas llamar o diagnosticar rápidamente una API HTTP desde una terminal.
Las tareas de ingeniería típicas incluyen:
- enviar solicitudes GET, POST, PUT, PATCH o DELETE
- añadir encabezados y autenticación
- enviar JSON de forma segura
- subir o descargar archivos
- inspeccionar los encabezados de la respuesta y los códigos de estado
- seguir redirecciones
- diagnosticar problemas de TLS, DNS, tiempo de espera, proxy o conectividad
- probar reintentos sin duplicar por accidente solicitudes no seguras
- reproducir un problema de la API fuera de la aplicación
El objetivo es que la solicitud sea explícita, observable y lo bastante segura como para usarla durante un diagnóstico real en producción.
Respuesta rápida
Solicitud básica a una API JSON:
curl \
--request GET \
--url "https://api.example.com/v1/reports/123" \
--header "Accept: application/json" \
--header "Authorization: Bearer $API_TOKEN"
POST con JSON:
curl \
--request POST \
--url "https://api.example.com/v1/reports" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $API_TOKEN" \
--data '{
"reportType": "sales",
"startDate": "2026-10-01",
"endDate": "2026-10-31"
}'
Para el diagnóstico, empieza con:
curl \
--silent \
--show-error \
--location \
--dump-header headers.txt \
--output body.json \
--write-out "%{http_code}\n" \
"https://api.example.com/health"
Código / comandos
1. Solicitud GET simple
curl "https://api.example.com/v1/status"
Úsala cuando el endpoint no requiera encabezados ni autenticación.
2. Enviar un método HTTP explícito
curl \
--request PATCH \
"https://api.example.com/v1/users/123"
Usa --request cuando el método no quede implícito por otra opción.
En muchos casos habituales:
--dataimplica POST, salvo que se especifique otro método--headrealiza una solicitud de tipo HEAD--upload-filesuele usar la semántica de PUT, salvo que se sobrescriba
Ser explícito mejora la legibilidad de los ejemplos reutilizables.
3. Añadir un encabezado Accept
curl \
--header "Accept: application/json" \
"https://api.example.com/v1/users/123"
Accept indica al servidor qué formato de respuesta prefiere el cliente.
4. Enviar JSON
curl \
--request POST \
--url "https://api.example.com/v1/users" \
--header "Content-Type: application/json" \
--data '{
"name": "Javi",
"active": true
}'
Content-Type describe el cuerpo de la solicitud.
No lo confundas con Accept.
5. Usar --json para solicitudes JSON
En versiones modernas de cURL:
curl \
--json '{
"name": "Javi",
"active": true
}' \
"https://api.example.com/v1/users"
--json es un atajo que envía JSON y establece los encabezados JSON correspondientes.
Si das soporte a entornos más antiguos, usa en su lugar Content-Type explícito + --data.
6. Enviar JSON desde un archivo
curl \
--request POST \
--header "Content-Type: application/json" \
--data @payload.json \
"https://api.example.com/v1/reports"
Es más seguro y más fácil de mantener para cuerpos de solicitud grandes.
7. Enviar los bytes sin procesar del cuerpo de la solicitud desde un archivo
curl \
--request POST \
--header "Content-Type: application/json" \
--data-binary @payload.json \
"https://api.example.com/v1/reports"
Usa --data-binary cuando el payload deba enviarse sin el procesamiento de tipo formulario que aplica cURL.
8. Añadir un token Bearer
curl \
--header "Authorization: Bearer $API_TOKEN" \
"https://api.example.com/v1/profile"
Prefiere las variables de entorno antes que poner secretos directamente en el historial del shell.
9. Autenticación Basic
curl \
--user "$API_USER:$API_PASSWORD" \
"https://api.example.com/v1/admin"
No incluyas credenciales en el código de scripts que se suben al control de versiones.
10. Clave de API en un encabezado
curl \
--header "X-API-Key: $API_KEY" \
"https://api.example.com/v1/data"
El nombre del encabezado varía según la API.
Usa el esquema de autenticación documentado por el proveedor.
11. Clave de API en la cadena de consulta
curl \
"https://api.example.com/v1/data?api_key=$API_KEY"
Evita este patrón salvo que sea obligatorio.
Los secretos en la cadena de consulta pueden filtrarse a:
- los logs
- el historial del navegador
- los proxies
- los sistemas de monitoreo
Los encabezados suelen ser más seguros para las credenciales.
12. Añadir varios encabezados
curl \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--header "X-Correlation-ID: test-123" \
"https://api.example.com/v1/orders"
Los ID de correlación son útiles para relacionar la solicitud del cliente con los logs del servidor.
13. Enviar parámetros de consulta de forma segura
curl \
--get \
--url "https://api.example.com/v1/reports" \
--data-urlencode "merchant=ACME & Sons" \
--data-urlencode "startDate=2026-10-01"
--data-urlencode evita errores de codificación manual.
14. Enviar datos de formulario codificados como URL
curl \
--request POST \
--data-urlencode "username=javi" \
--data-urlencode "scope=reports read" \
"https://auth.example.com/token"
Esto envía:
application/x-www-form-urlencoded
lo cual es habitual en flujos de OAuth/obtención de tokens.
15. Enviar datos de formulario multipart
curl \
--form "description=monthly report" \
--form "file=@report.csv" \
"https://api.example.com/v1/uploads"
Usa --form para subidas multipart.
16. Subir un archivo directamente
curl \
--upload-file report.csv \
"https://storage.example.com/files/report.csv"
Úsalo cuando el endpoint espere que el cuerpo de la solicitud sea el propio archivo.
Comprueba el método y el modelo de autenticación que espera la API.
17. Descargar un archivo con un nombre concreto
curl \
--output report.csv \
"https://api.example.com/v1/reports/123/download"
18. Conservar el nombre de archivo proporcionado por el servidor
curl \
--remote-name \
"https://example.com/files/report.csv"
Úsalo solo cuando confíes en el origen y en el directorio de destino.
19. Seguir redirecciones
curl \
--location \
"https://example.com/download"
Sin --location, cURL normalmente informa de la respuesta de redirección en lugar de seguirla.
20. Mostrar los encabezados y el cuerpo de la respuesta
curl \
--include \
"https://api.example.com/v1/status"
--include coloca los encabezados de la respuesta antes del cuerpo en el mismo flujo de salida.
Útil de forma interactiva, menos práctico para la automatización.
21. Guardar los encabezados de la respuesta por separado
curl \
--dump-header headers.txt \
--output body.json \
"https://api.example.com/v1/status"
Úsalo cuando necesites inspeccionar los encabezados y el cuerpo por separado.
22. Mostrar solo los encabezados de la respuesta
curl \
--head \
"https://example.com/resource"
Esto solicita una petición HEAD.
Ten en cuenta que no todas las APIs implementan HEAD de forma útil.
23. Imprimir solo el código de estado HTTP
curl \
--silent \
--output /dev/null \
--write-out "%{http_code}\n" \
"https://api.example.com/health"
En Windows PowerShell, /dev/null no existe de forma nativa. Usa un destino nulo adecuado para el entorno o guarda la respuesta en un archivo.
24. Imprimir el estado y los tiempos
curl \
--silent \
--output /dev/null \
--write-out \
"status=%{http_code} total=%{time_total}s connect=%{time_connect}s ttfb=%{time_starttransfer}s\n" \
"https://api.example.com/health"
Útil para separar:
- el tiempo de conexión
- el retraso del servidor/TTFB
- el tiempo total de transferencia
No trates una sola muestra como un benchmark de rendimiento.
25. Imprimir los tiempos de DNS y TLS
curl \
--silent \
--output /dev/null \
--write-out \
"dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
"https://api.example.com/health"
Úsalo para distinguir:
- el retraso de DNS
- el retraso de la conexión TCP
- el retraso del handshake TLS
- el retraso de la aplicación/del servidor
26. Fallar ante errores HTTP conservando una salida útil
curl \
--fail-with-body \
--show-error \
"https://api.example.com/v1/resource"
--fail-with-body devuelve un código de salida de fallo para las respuestas de error HTTP y conserva el cuerpo de la respuesta.
Suele ser más útil para scripts que --fail a secas.
Comprueba la versión de cURL si la opción no está disponible en entornos más antiguos.
27. Usar una salida apta para scripts
curl \
--silent \
--show-error \
--fail-with-body \
"https://api.example.com/v1/resource"
Esta combinación significa:
--silent: suprime el indicador de progreso--show-error: sigue imprimiendo los errores de cURL--fail-with-body: código distinto de cero ante errores HTTP, conserva el cuerpo
28. Establecer un tiempo de espera de conexión
curl \
--connect-timeout 5 \
"https://api.example.com/health"
Limita cuánto tiempo espera cURL para establecer la conexión.
29. Establecer un tiempo de espera global
curl \
--max-time 30 \
"https://api.example.com/v1/reports/123"
Limita la duración total de la solicitud.
Usa valores alineados con la latencia real esperada de la API.
30. Reintentar fallos transitorios
curl \
--retry 3 \
--retry-delay 2 \
--retry-max-time 30 \
"https://api.example.com/health"
Usa los reintentos sobre todo para operaciones que se pueden repetir de forma segura.
31. Ten cuidado al reintentar POST/PATCH/DELETE
Un reintento puede duplicar efectos secundarios si la API no es idempotente.
Para las operaciones de escritura, prefiere:
- claves de idempotencia admitidas por la API
- ID de solicitud del lado del servidor
- contratos de reintento seguros
No reintentes a ciegas las llamadas que cambian el estado.
32. Usar una clave de idempotencia cuando la API la admita
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Idempotency-Key: $REQUEST_ID" \
--data @payload.json \
"https://api.example.com/v1/payments"
El nombre del encabezado y su comportamiento dependen de cada API.
No inventes un mecanismo de idempotencia que el servidor no admita.
33. Ampliar los reintentos solo cuando esté justificado
Las versiones modernas de cURL admiten:
curl \
--retry 3 \
--retry-all-errors \
"https://api.example.com/health"
Esto amplía los tipos de fallo que se reintentan.
Úsalo con precaución, sobre todo en solicitudes que cambian el estado.
34. Inspeccionar el detalle verboso de la solicitud y la respuesta
curl \
--verbose \
"https://api.example.com/v1/status"
Útil para:
- los encabezados de la solicitud
- los encabezados de la respuesta
- las redirecciones
- la negociación TLS
- el comportamiento del proxy
- la reutilización de conexiones
Ten cuidado: la salida verbosa puede exponer credenciales.
35. Nunca pegues la salida verbosa en público sin revisarla
Las trazas verbosas pueden incluir:
encabezados Authorization
cookies
claves de API
nombres de host internos
tokens de sesión
Oculta los secretos antes de compartir logs o tickets.
36. Usar la salida de traza para depurar el protocolo en profundidad
curl \
--trace-ascii trace.txt \
"https://api.example.com/v1/status"
Úsalo solo cuando sea necesario.
Los archivos de traza pueden contener encabezados y cuerpos sensibles.
Trátalos como secretos hasta haberlos revisado.
37. Forzar HTTP/1.1 para comparar
curl \
--http1.1 \
"https://api.example.com/v1/status"
Úsalo al investigar comportamientos específicos de un protocolo.
38. Solicitar HTTP/2 cuando esté admitido
curl \
--http2 \
"https://api.example.com/v1/status"
La compatibilidad real depende de cómo se compiló cURL y de lo que negocie el servidor.
39. Inspeccionar la versión HTTP negociada
curl \
--silent \
--output /dev/null \
--write-out "%{http_version}\n" \
"https://api.example.com/v1/status"
Útil al depurar diferencias entre HTTP/1.1 y HTTP/2.
40. Inspeccionar la IP remota
curl \
--silent \
--output /dev/null \
--write-out "%{remote_ip}\n" \
"https://api.example.com/health"
Útil al diagnosticar DNS, balanceadores de carga o enrutamiento regional.
41. Sobrescribir el DNS para una sola solicitud
curl \
--resolve api.example.com:443:203.0.113.10 \
"https://api.example.com/health"
Esto mantiene el nombre de host original para:
- el SNI de TLS
- el encabezado Host
mientras se conecta a la IP especificada.
Úsalo solo para un diagnóstico controlado.
42. No edites /etc/hosts solo para probar un endpoint
--resolve suele ser más seguro, porque solo afecta a esa invocación de cURL.
43. Establecer el encabezado Host con cuidado
curl \
--header "Host: api.example.com" \
"https://203.0.113.10/health"
Esto no reemplaza por completo el comportamiento de TLS basado en el nombre de host.
Para probar HTTPS contra una IP concreta, --resolve suele ser mejor opción.
44. Usar un proxy de forma explícita
curl \
--proxy "http://proxy.example.com:8080" \
"https://api.example.com/health"
Útil para comprobar si los fallos de la aplicación están relacionados con el proxy.
45. Omitir el proxy para hosts concretos
curl \
--noproxy "api.example.com" \
"https://api.example.com/health"
Revisa variables de entorno como:
HTTP_PROXY
HTTPS_PROXY
NO_PROXY
cuando cURL se comporta de forma distinta según la máquina.
46. Mostrar los encabezados de la solicitud con -v, pero sin exponer tokens
En las llamadas autenticadas, plantéate probar temporalmente contra un endpoint no sensible u ocultar los secretos en los logs.
No envíes tokens reales de producción a sitios públicos para pegar texto.
47. Enviar cookies
curl \
--cookie "session_id=$SESSION_ID" \
"https://api.example.com/profile"
Úsalo solo cuando la API utilice deliberadamente autenticación/estado de sesión basados en cookies.
48. Guardar las cookies de la respuesta
curl \
--cookie-jar cookies.txt \
"https://api.example.com/login"
49. Enviar más tarde las cookies guardadas
curl \
--cookie cookies.txt \
"https://api.example.com/profile"
Protege los archivos de cookies como si fueran credenciales.
50. Enviar un User-Agent personalizado
curl \
--user-agent "javi-builds-api-test/1.0" \
"https://api.example.com/health"
Útil cuando los logs del servidor o los límites de tasa distinguen entre clientes.
51. Añadir un ID de correlación
REQUEST_ID="$(uuidgen)"
curl \
--header "X-Correlation-ID: $REQUEST_ID" \
"https://api.example.com/v1/reports"
El nombre exacto del encabezado depende de la API.
Usa un identificador de solicitud estable al correlacionar los logs del cliente y del servidor.
52. Inspeccionar los encabezados de límite de tasa
curl \
--include \
"https://api.example.com/v1/data"
Busca encabezados específicos de la API, como:
RateLimit-*
X-RateLimit-*
Retry-After
Los nombres de los encabezados varían según la implementación.
53. Respetar Retry-After
Si el servidor devuelve:
429 Too Many Requests
junto con un encabezado Retry-After, sigue esa indicación en lugar de saturar el endpoint.
54. Enviar solicitudes GET condicionales con ETag
Primero inspecciona:
curl \
--include \
"https://api.example.com/v1/config"
Si la respuesta incluye:
ETag: "abc123"
entonces:
curl \
--header 'If-None-Match: "abc123"' \
"https://api.example.com/v1/config"
Un 304 Not Modified puede evitar descargar contenido que no ha cambiado.
55. Enviar solicitudes condicionales por fecha de modificación
curl \
--header "If-Modified-Since: Wed, 01 Oct 2026 12:00:00 GMT" \
"https://api.example.com/v1/config"
Úsalo solo cuando el servidor admita una semántica de última modificación significativa.
56. Descargar y reanudar un archivo grande
curl \
--continue-at - \
--output large-file.zip \
"https://example.com/large-file.zip"
La reanudación depende de que el servidor admita solicitudes de rango (range requests).
57. Limitar la velocidad de descarga para pruebas controladas
curl \
--limit-rate 1M \
--output file.bin \
"https://example.com/file.bin"
Útil para simular clientes con recursos limitados.
58. Indicar compatibilidad con respuestas comprimidas
curl \
--compressed \
"https://api.example.com/v1/data"
Esto solicita al servidor las codificaciones comprimidas admitidas y descomprime la respuesta automáticamente.
59. Inspeccionar el tipo de contenido
curl \
--silent \
--output /dev/null \
--write-out "%{content_type}\n" \
"https://api.example.com/v1/data"
Útil cuando un endpoint devuelve inesperadamente HTML en lugar de JSON.
60. Detectar páginas de error HTML de proxies o gateways
Si tu cliente espera JSON pero recibe un cuerpo HTML, inspecciona:
curl \
--include \
"https://api.example.com/v1/data"
Fíjate en:
- el código de estado
Content-TypeServer- los encabezados del gateway/proxy
Es posible que el fallo esté upstream de la aplicación.
61. Escribir el cuerpo y el estado por separado en un script de shell
status="$(
curl \
--silent \
--show-error \
--output response.json \
--write-out "%{http_code}" \
"https://api.example.com/v1/data"
)"
echo "HTTP $status"
Así se mantienen separados el cuerpo y el estado, legibles por máquina.
62. Comprobar el código de salida del proceso de cURL
curl \
--fail-with-body \
--silent \
--show-error \
"https://api.example.com/v1/data"
echo $?
En shells POSIX:
0
→ cURL consideró que la solicitud se completó correctamente
distinto de cero
→ fallo de transporte/protocolo o fallo HTTP con --fail*
No confundas el código de salida de cURL con el código de estado HTTP.
63. Un HTTP 500 puede producir el código de salida 0 de cURL sin --fail
De forma predeterminada, cURL puede transferir correctamente una respuesta 500.
Si los scripts deben fallar ante errores HTTP, usa:
--fail-with-body
e inspecciona también el estado HTTP.
64. Usar HEAD solo para metadatos cuando el servidor lo admita
curl --head "https://example.com/file.zip"
Útil para:
- la longitud del contenido
- el ETag
- la fecha de última modificación
- las redirecciones
Algunas APIs no implementan HEAD de forma coherente.
65. Probar manualmente una solicitud preflight de CORS
curl \
--request OPTIONS \
--header "Origin: https://app.example.com" \
--header "Access-Control-Request-Method: POST" \
--header "Access-Control-Request-Headers: authorization,content-type" \
"https://api.example.com/v1/reports"
Inspecciona encabezados de la respuesta como:
Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers
CORS lo aplican los navegadores, no cURL.
66. Probar directamente un endpoint OPTIONS
curl \
--request OPTIONS \
--include \
"https://api.example.com/v1/reports"
No des por hecho que todas las APIs exponen metadatos útiles sobre los métodos mediante OPTIONS.
67. Enviar JSON con PATCH
curl \
--request PATCH \
--header "Content-Type: application/json" \
--data '{
"status": "disabled"
}' \
"https://api.example.com/v1/users/123"
Ten cuidado con los endpoints de producción que cambian el estado.
68. Enviar DELETE
curl \
--request DELETE \
--header "Authorization: Bearer $API_TOKEN" \
"https://api.example.com/v1/users/123"
DELETE puede ser destructivo.
Prueba fuera de producción o contra un recurso desechable conocido, salvo que el cambio sea explícitamente intencionado.
69. Evitar poner secretos directamente en la línea de comandos
Arriesgado:
curl \
--header "Authorization: Bearer real-secret-token" \
...
Las líneas de comandos pueden quedar guardadas en el historial del shell o ser visibles mediante la inspección de procesos locales.
Prefiere variables de entorno o herramientas seguras de gestión de secretos.
70. Usar un archivo de configuración para solicitudes repetibles
Ejemplo de curl.conf:
silent
show-error
fail-with-body
header = "Accept: application/json"
Después:
curl --config curl.conf "https://api.example.com/v1/data"
No guardes secretos en un archivo de configuración que se suba al repositorio.
71. Usar .netrc solo cuando su modelo de seguridad encaje
cURL puede usar credenciales de .netrc.
Si lo usas:
- restringe los permisos del archivo
- no hagas commit de él
- entiende a qué hosts se aplica
En muchos flujos de trabajo de producción es preferible una gestión de secretos dedicada.
72. Probar la verificación TLS de forma normal
curl "https://api.example.com/health"
No desactives la verificación de certificados de forma predeterminada.
73. Evitar -k / --insecure como solución habitual
curl --insecure "https://api.example.com/health"
Esto desactiva la verificación de certificados TLS.
Úsalo solo para diagnósticos controlados, cuando entiendas el riesgo.
No lo normalices en scripts de producción.
74. Usar un certificado de CA personalizado cuando corresponda
curl \
--cacert company-root-ca.pem \
"https://internal-api.example.com/health"
Así se conserva la verificación TLS y se confía en la CA interna prevista.
75. Usar un certificado de cliente cuando se requiera mTLS
curl \
--cert client-cert.pem \
--key client-key.pem \
"https://mtls.example.com/v1/data"
Protege las claves privadas y el material de los certificados.
Los formatos y opciones exactos dependen de tu compilación de cURL y del empaquetado de los certificados.
76. Depurar el nombre de host/TLS por separado del comportamiento HTTP
Progresión útil:
resolución DNS
→ conexión TCP
→ handshake TLS
→ estado HTTP
→ cuerpo de la aplicación
Usa los tiempos, --verbose y --resolve de forma selectiva para aislar la capa que falla.
77. Comparar el comportamiento de la API con y sin redirecciones
Sin seguirlas:
curl \
--include \
"https://example.com/api"
Siguiendo las redirecciones:
curl \
--location \
--include \
"https://example.com/api"
Esto puede revelar problemas de autenticación o de enrutamiento ocultos tras una redirección.
78. Ten cuidado al enviar credenciales a través de redirecciones
Cuando las redirecciones cambian de host, entiende cómo se tratan los encabezados de autenticación y las cookies.
No fuerces el reenvío de credenciales a hosts no relacionados.
Revisa primero los destinos de las redirecciones.
79. Comprobar el tamaño del cuerpo de la respuesta
curl \
--silent \
--output /dev/null \
--write-out "%{size_download}\n" \
"https://api.example.com/v1/report"
Útil cuando una respuesta de la API que antes era pequeña se vuelve inesperadamente grande.
80. Imprimir una línea de diagnóstico compacta
curl \
--silent \
--show-error \
--output response.out \
--write-out \
"status=%{http_code} ip=%{remote_ip} dns=%{time_namelookup}s connect=%{time_connect}s ttfb=%{time_starttransfer}s total=%{time_total}s bytes=%{size_download}\n" \
"https://api.example.com/v1/data"
Es útil en las notas de incidentes porque recoge tanto el contexto de red como el contexto HTTP.
Qué significa el resultado
| Señal | Qué ayuda a identificar |
|---|---|
| Estado HTTP | Resultado de la aplicación/del gateway |
| Código de salida de cURL | Éxito o fallo del cliente/transporte/protocolo |
time_namelookup |
Tiempo de resolución DNS |
time_connect |
Tiempo hasta establecer la conexión TCP |
time_appconnect |
Tiempo hasta completar el handshake TLS |
time_starttransfer |
Tiempo hasta el primer byte de la respuesta |
time_total |
Duración total de la solicitud |
remote_ip |
IP del servidor/balanceador de carga realmente alcanzada |
content_type |
Representación de la respuesta devuelta |
size_download |
Tamaño del cuerpo de la respuesta |
| Encabezados de la respuesta | Pistas sobre caché, límite de tasa, autenticación, gateway y trazabilidad |
Un modelo mental útil es:
código de salida de cURL
→ ¿se completó correctamente la operación del cliente?
estado HTTP
→ ¿qué respondió el servidor HTTP?
cuerpo de la respuesta
→ ¿qué explicó la aplicación/el gateway?
Qué revisar
401 Unauthorized
Comprueba:
- token ausente/caducado
- esquema de autenticación incorrecto
- audiencia/scope incorrectos
- problemas de reloj en tokens firmados
No regeneres las credenciales de inmediato sin confirmar antes qué credencial envió realmente la solicitud.
403 Forbidden
Puede que la autenticación se haya completado pero la autorización haya fallado.
Comprueba:
- permisos
- rol/scope
- política del recurso
- restricciones de IP/red
404 Not Found
Comprueba:
- la ruta de la URL
- la versión de la API
- el ID del tenant/recurso
- el enrutamiento del gateway
- si el servicio oculta intencionadamente los recursos no autorizados como 404
429 Too Many Requests
Comprueba:
Retry-After- los encabezados de límite de tasa
- la concurrencia de solicitudes
- los bucles de reintento del cliente
No reintentes de forma agresiva.
5xx
Comprueba si la respuesta provino de:
- la aplicación
- el gateway de API
- el proxy inverso
- el balanceador de carga
Los encabezados y el cuerpo suelen revelar qué capa falló.
Tiempo de DNS elevado
Investiga el resolvedor y la ruta de red.
Conexión rápida pero TTFB alto
Probablemente se trate de un retraso de procesamiento del servidor/la aplicación/el gateway, más que de la configuración inicial de la red.
Fallo de TLS
Comprueba:
- el nombre de host
- la cadena de certificados
- el almacén de confianza
- los requisitos de certificado de cliente
- el reloj del sistema
Evita normalizar --insecure.
Notas de producción
cURL es una herramienta de reproducción excelente
Una solicitud cURL mínima puede separar:
un bug de la aplicación cliente
del
comportamiento de la API/la red/el servidor
Captura la solicitud más pequeña que siga reproduciendo el problema.
Protege los secretos
Los comandos, las trazas verbosas, el historial del shell, los logs de CI y los adjuntos de los tickets pueden exponer:
- tokens Bearer
- claves de API
- credenciales de autenticación Basic
- cookies
- certificados de cliente
Oculta los secretos antes de compartir.
Los reintentos deben respetar la idempotencia
Un GET suele poder reintentarse de forma segura.
Un POST puede crear estado duplicado, salvo que la API ofrezca explícitamente una semántica de idempotencia.
--insecure cambia el modelo de seguridad
Es una herramienta de diagnóstico, no una solución para producción.
Si se espera una CA privada, configura correctamente la confianza en esa CA.
El diagnóstico de rendimiento necesita varios tiempos
Un time_total lento por sí solo no te dice si el problema está en:
- el DNS
- la red
- TLS
- el procesamiento del servidor
- el tamaño de la descarga
Usa los campos de tiempo en conjunto.
La sintaxis del shell difiere entre entornos
La continuación de línea difiere entre:
- Bash/zsh:
\ - PowerShell: acento grave (backtick) o splatting/arrays
- Windows cmd.exe:
^
Las opciones de cURL son las mismas, pero las reglas de comillas difieren.
Las llamadas de producción que cambian el estado requieren una intención explícita
Antes de ejecutar POST/PATCH/DELETE contra producción, confirma:
- el endpoint
- el ID del recurso
- el entorno
- la identidad de autenticación
- el payload
- el efecto secundario esperado
Errores comunes
1. Confundir Accept y Content-Type
Accept describe la respuesta deseada.
Content-Type describe el cuerpo de la solicitud.
2. Evaluar el éxito HTTP solo con el código de salida de cURL
Un 500 puede seguir siendo una transferencia correcta, salvo que se use --fail*.
3. Usar -k para «arreglar» TLS
Esto oculta los problemas de certificados en lugar de resolverlos.
4. Imprimir tokens en logs verbosos
Oculta los secretos antes de compartir la salida.
5. Reintentar solicitudes POST a ciegas
Esto puede duplicar efectos secundarios.
6. Construir cadenas de consulta a mano sin codificarlas
Usa --data-urlencode.
7. Usar --data para payloads binarios
Usa --data-binary o --upload-file cuando importen los bytes sin procesar.
8. Suponer que HEAD se comporta exactamente igual que GET
Algunos servicios implementan HEAD de otra forma o no lo implementan.
9. Ignorar las redirecciones
Una redirección puede explicar un comportamiento inesperado de autenticación, del gateway o de enrutamiento.
10. Tomar una sola muestra de tiempo como prueba de rendimiento
Repite pruebas controladas y compáralas con la telemetría del lado del servidor.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.