Cómo integrar una API REST con token en 5 minutos
Guía práctica para integrar una API REST con token Bearer: primera llamada con curl, cómo leer el JSON, códigos HTTP y ejemplos en JavaScript y Python.
Tu jefe quiere que la razón social se llene sola cuando el vendedor escribe el RUC. Tienes la documentación de una API abierta en una pestaña, un token que te llegó por correo y ninguna experiencia con "eso de REST". Buenas noticias: integrar una API REST con token es mucho más simple de lo que parece, y en cinco minutos puedes tener la primera respuesta en pantalla.
En esta guía vas a entender qué es REST sin teoría de más, qué es un token Bearer y por qué viaja en una cabecera, cómo hacer la primera llamada con curl, cómo leer el JSON que vuelve y qué significan los códigos HTTP que vas a encontrarte. Terminamos con el mismo ejemplo en JavaScript y Python y con el punto que casi nadie explica al principio: dónde guardar el token para que no termine subido a un repositorio.
Qué es una API REST
Una API REST es un conjunto de direcciones web (URLs) que, en vez de devolver páginas para personas, devuelven datos para programas. Cada URL representa un recurso. En una API de datos peruanos, /ruc/20131312955 es el recurso "el contribuyente con RUC 20131312955", /dni/12345678 es una persona y /tipo-cambio es el tipo de cambio vigente.
Sobre esas URLs se usan los verbos de HTTP. GET sirve para leer, POST para crear, PUT o PATCH para modificar y DELETE para borrar. Para consultar RUC, DNI o tipo de cambio solo vas a usar GET, que es el mismo verbo que usa tu navegador cuando abres cualquier página. Eso significa que no hay nada exótico: una llamada a la API es una petición HTTP normal con una cabecera extra.
Dos reglas más completan la idea. Las peticiones son independientes entre sí (el servidor no recuerda la anterior, por eso cada una lleva su token), y la respuesta viene con un código de estado que resume cómo fue, antes incluso de mirar el contenido. El contenido, en casi todas las APIs modernas, es JSON.
Una URL completa se arma con tres partes: la base (https://api.endpoint.pe/v1), la ruta del recurso (/ruc/20131312955) y, a veces, parámetros de consulta después del signo de interrogación (?q=sunat, para buscar una empresa por su nombre). La documentación de cada API, por ejemplo la de endpoint.pe, te dice qué rutas existen y qué campos devuelve cada una.
El token Bearer
El token es una cadena larga y aleatoria que identifica tu cuenta. "Bearer" significa portador: quien lo presenta tiene acceso, sin usuario ni contraseña adicionales. Por eso se trata igual que una contraseña.
El token viaja en la cabecera Authorization de cada petición, con el prefijo Bearer y un espacio:
Authorization: Bearer TU_TOKEN
¿Por qué en una cabecera y no en la URL? Porque las URLs quedan registradas en logs de servidores, proxies e historiales de navegación. Las cabeceras no suelen registrarse, así que el token tiene menos lugares donde filtrarse. Si una API te ofrece pasar el token como parámetro de la URL, evítalo siempre que exista la alternativa de la cabecera.
El token lo obtienes desde el panel de tu cuenta después de registrarte. La cuenta gratuita incluye 150 consultas al mes sin tarjeta, suficiente para hacer todas las pruebas de esta guía y algo más.
Tu primera llamada con curl
curl es una herramienta de línea de comandos que viene instalada en Linux, macOS y Windows 10 en adelante. Sirve para hacer peticiones HTTP sin escribir código, y es la forma más rápida de comprobar que el token funciona y de ver con tus propios ojos qué devuelve la API.
curl https://api.endpoint.pe/v1/ruc/20131312955 \
-H "Authorization: Bearer TU_TOKEN"
Desglosemos la línea. curl es el programa. Lo que sigue es la URL del recurso: el RUC de SUNAT como entidad, un RUC público que sirve para pruebas. La opción -H añade una cabecera, y la que añadimos es la de autorización con el token. La barra invertida al final de la primera línea solo indica que el comando continúa en la siguiente.
Si estás en PowerShell, ten en cuenta que curl es un alias de otro comando con opciones distintas. Escribe curl.exe para usar el curl real.
Si todo va bien, la terminal te muestra algo así:
{
"success": true,
"message": "Consulta exitosa",
"data": {
"ruc": "20131312955",
"razon_social": "SUPERINTENDENCIA NACIONAL DE ADUANAS Y DE ADMINISTRACION TRIBUTARIA - SUNAT",
"estado": "ACTIVO",
"condicion": "HABIDO",
"ubigeo": "150101"
},
"meta": {
"fuente": "SUNAT",
"consultado_en": "2026-10-12T07:40:12Z",
"creditos_cobrados": 1,
"creditos_disponibles": 14621
}
}
La respuesta real incluye también la dirección del domicilio fiscal; la omitimos aquí por espacio. Para ver además el código de estado y las cabeceras de la respuesta, añade la opción -i al comando. Vas a ver una primera línea como HTTP/2 200, y ese número es lo que revisamos a continuación.
Leer el JSON y los códigos HTTP
JSON es texto con una estructura mínima: objetos entre llaves, listas entre corchetes, pares de clave y valor separados por dos puntos, y textos entre comillas dobles. Cualquier lenguaje lo convierte en una estructura nativa con una sola función (JSON.parse en JavaScript, json.loads en Python, json_decode en PHP). Nunca lo leas con expresiones regulares: una coma de más o un campo nuevo te rompe el sistema.
Un detalle que ahorra dolores de cabeza: el RUC y el ubigeo llegan como texto, no como número, aunque estén formados por dígitos. Así se conservan los ceros a la izquierda (el ubigeo del Callao empieza con 0) y evitas conversiones accidentales. Guárdalos como texto en tu base de datos también.
Antes de procesar el JSON, mira el código de estado. Los más habituales al consumir una API de datos son estos:
| Código | Qué significa | Qué hacer |
|---|---|---|
| 200 | Todo bien, el cuerpo trae el dato | Procesar el JSON |
| 400 | La petición está mal formada (por ejemplo, un RUC de 10 dígitos) | Validar el formato antes de enviar |
| 401 | Token inválido o ausente | Revisar la cabecera y el token |
| 402 | La cuenta no tiene créditos | Recargar créditos o revisar el plan |
| 404 | El recurso no existe (ese RUC no está registrado) | Mostrar "no encontrado"; no es un error de tu código |
| 429 | Demasiadas peticiones en poco tiempo | Esperar y reintentar |
| 500 en adelante | Falla del lado del servidor | Reintentar más tarde |
Toda respuesta de endpoint.pe viene envuelta: success dice si la consulta salió bien, message lo explica en español y data trae los datos (en los errores llega en null, junto con un código en error). Un 404 se ve así:
{
"success": false,
"message": "No se encontró información para la consulta.",
"error": "no_encontrado",
"data": null,
"meta": {
"consultado_en": "2026-10-12T07:40:12Z"
}
}
Fíjate en que un 404 no quiere decir que tu integración esté rota: simplemente ese número no corresponde a ningún contribuyente. En endpoint.pe las consultas sin resultado no consumen créditos, así que puedes tratarlo como un resultado legítimo ("RUC no existe") y no como una excepción. El manejo fino de cada código, con reintentos y tiempos de espera, lo cubrimos en manejo de errores y reintentos al consumir APIs.
El mismo ejemplo en JavaScript y Python
Lo que hiciste con curl se traduce casi línea por línea a cualquier lenguaje. En Node.js (versión 18 o superior) fetch viene incluido, así que no necesitas instalar nada:
const token = process.env.ENDPOINT_TOKEN;
async function consultarRuc(ruc) {
const res = await fetch(`https://api.endpoint.pe/v1/ruc/${ruc}`, {
headers: { Authorization: `Bearer ${token}` },
});
if (res.status === 404) return null;
if (!res.ok) throw new Error(`La API respondió ${res.status}`);
return (await res.json()).data;
}
const empresa = await consultarRuc('20131312955');
console.log(empresa.razon_social, empresa.estado, empresa.condicion);
En Python, con la librería requests (se instala con pip install requests):
import os
import requests
TOKEN = os.environ["ENDPOINT_TOKEN"]
def consultar_ruc(ruc: str) -> dict | None:
respuesta = requests.get(
f"https://api.endpoint.pe/v1/ruc/{ruc}",
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=10,
)
if respuesta.status_code == 404:
return None
respuesta.raise_for_status()
return respuesta.json()["data"]
empresa = consultar_ruc("20131312955")
print(empresa["razon_social"], empresa["estado"], empresa["condicion"])
Los dos ejemplos siguen el mismo patrón: construir la URL, enviar la cabecera, tratar el 404 como "no existe", lanzar un error para cualquier otro código que no sea exitoso y, solo entonces, convertir el JSON. El timeout en Python evita que tu programa se quede colgado si la red falla; en JavaScript puedes lograr lo mismo con AbortSignal.timeout. Si quieres ir más allá, tenemos guías específicas para consultar RUC con Node.js y consultar DNI con Python.
Dónde guardar el token
Los dos ejemplos leen el token de una variable de entorno, y no es casualidad. Las reglas son pocas y no tienen excepciones:
- Nunca en el código fuente. Un token escrito en un archivo
.jso.pytermina en el repositorio, y de ahí en el historial de Git para siempre, aunque lo borres después. - Nunca en el navegador. Cualquier persona puede abrir las herramientas de desarrollo y copiarlo. Si tu aplicación web necesita consultar RUC, el navegador llama a tu propio backend y es el backend quien llama a la API con el token.
- En variables de entorno o en un gestor de secretos. En desarrollo, un archivo
.envque esté en.gitignore. En producción, las variables de entorno del servidor o el gestor de secretos de tu proveedor de nube. - Un token por aplicación. Si el sistema de facturación y la tienda en línea usan tokens distintos, puedes revocar uno sin tumbar al otro.
En desarrollo local basta con esto antes de ejecutar el programa:
export ENDPOINT_TOKEN="tu_token_aqui"
node consulta.js
Revócalo desde el panel y genera uno nuevo. No intentes "limpiar" el repositorio: asume que cualquier token que haya estado en un commit está comprometido.
Las demás precauciones (rotación periódica, mínimos permisos, monitoreo de consumo) están en seguridad de tokens de API.
Si todavía estás comparando proveedores, en cómo elegir una API de consulta RUC y DNI en Perú tienes los criterios que importan y una prueba de tres llamadas para decidir con datos y no con la página de ventas.
En resumen
- Una API REST expone recursos en URLs y se consulta con peticiones HTTP normales; para datos solo usas
GET. - El token Bearer identifica tu cuenta y viaja en la cabecera
Authorization: Bearer TU_TOKEN, nunca en la URL. - La primera prueba se hace con curl en una sola línea; añade
-ipara ver el código de estado. - Lee siempre el código HTTP antes del JSON: 200 es éxito, 404 es "no existe" (y no cuesta créditos), 401 y 402 son problemas de cuenta, 429 es velocidad y 5xx es el servidor.
- El token vive en variables de entorno o en un gestor de secretos, jamás en el código ni en el navegador.
Preguntas frecuentes
¿Necesito instalar alguna librería especial?
No. curl viene con el sistema operativo, Node.js trae fetch desde la versión 18 y en Python basta con requests (o incluso urllib, que viene incluido). Un cliente HTTP generado o un SDK puede ser cómodo, pero no es necesario para consumir una API REST con token.
¿Puedo probar la API sin escribir código?
Sí. Puedes usar la consulta en vivo de la página principal para ver la respuesta de un RUC sin configurar nada, o una herramienta de escritorio para pruebas de APIs donde pegas la URL y la cabecera. curl sigue siendo la opción más rápida una vez que tienes el token.
¿Qué pasa si envío un RUC con formato incorrecto?
La API responde con un código 400 y un mensaje describiendo el problema. Lo ideal es validar el formato en tu propio sistema antes de llamar (11 dígitos, prefijo 10 o 20 y dígito verificador correcto), así ahorras la llamada y le muestras al usuario un mensaje inmediato.
¿Cuánto cuesta integrar y probar?
Nada al inicio: la cuenta gratuita de endpoint.pe incluye 150 consultas al mes sin tarjeta. Cada consulta exitosa en cualquier API cuesta un crédito, las consultas sin resultado no se cobran y los créditos prepago no vencen. Los detalles están en la página de precios.
