Listar empresas
GET /v1/empresas
Empresas de la cuenta, de la más antigua a la más reciente.
Permiso
La clave necesita empresas:leer. Ver Permisos.
Parámetros
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
limite | consulta | integer | Elementos por página, de 1 a 100. De 1 a 100. Por defecto, 25. |
cursor | consulta | string | null | Valor de siguiente_cursor de la página anterior. Caduca a las 24 horas. |
actualizado_desde | consulta | string · date-time | null | Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por actualizado_en. |
Petición
La clave se lee de la variable de entorno VINTU_API_KEY. Ver Inicio rápido.
curl -G "https://api.vintu.io/v1/empresas" \
--data-urlencode "limite=25" \
-H "Authorization: Bearer $VINTU_API_KEY"const url = new URL("https://api.vintu.io/v1/empresas");
url.searchParams.set("limite", "25");
const respuesta = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.VINTU_API_KEY}` },
});
if (!respuesta.ok) {
const { error } = await respuesta.json();
throw new Error(`${respuesta.status} ${error.codigo}: ${error.mensaje} (${error.id_peticion})`);
}
const cuerpo = await respuesta.json();
console.log(cuerpo);import os
import requests
respuesta = requests.get(
"https://api.vintu.io/v1/empresas",
params={"limite": "25"},
headers={"Authorization": f"Bearer {os.environ['VINTU_API_KEY']}"},
timeout=30,
)
if not respuesta.ok:
error = respuesta.json()["error"]
raise RuntimeError(f"{respuesta.status_code} {error['codigo']}: {error['mensaje']} ({error['id_peticion']})")
print(respuesta.json())Respuesta
200 · Correcto.
| Cabecera | Descripción |
|---|---|
X-Request-ID | Identificador de la petición; cítalo al pedir soporte. |
X-Vintu-Mode | lectura_degradada cuando la coordinación no responde y los límites se aplican por réplica. |
RateLimit-Limit | Peticiones por minuto admitidas. |
RateLimit-Remaining | Peticiones que quedan en la ventana. |
RateLimit-Reset | Segundos hasta que se recupera el cupo. |
Campos
| Campo | Tipo | Descripción |
|---|---|---|
datos | array de object | Elementos de esta página. |
datos[].id | string · uuid | Identificador público de la empresa. |
datos[].ruc | string | RUC de 11 dígitos. |
datos[].razon_social | string | Razón social registrada en la cuenta. |
datos[].creado_en | string · date-time | Alta de la empresa en Vintu. |
datos[].actualizado_en | string · date-time | Último cambio de la empresa. |
siguiente_cursor | string | null | Pásalo en cursor para pedir la página siguiente; nulo en la última. Caduca a las 24 horas y solo vale para la misma consulta. |
marca_superior | string · date-time | null | Instante en que empezó el recorrido; lo que cambie después no entra en él. Úsalo como actualizado_desde de la sincronización siguiente; como ese filtro incluye el propio instante, deduplica por id. |
Ejemplo con datos ficticiosJSON
{
"datos": [
{
"id": "00000000-0000-4000-8000-0000000000c1",
"ruc": "20000000002",
"razon_social": "Comercial Ejemplo S.A.C.",
"creado_en": "2026-11-10T14:32:05.120000+00:00",
"actualizado_en": "2026-11-10T14:32:05.120000+00:00"
}
],
"siguiente_cursor": "CURSOR_DE_EJEMPLO",
"marca_superior": "2026-11-12T09:15:41.004000+00:00"
}Errores
Todos con el cuerpo {"error": {"codigo", "mensaje", "id_peticion"}}. Compara contra
codigo; el mensaje puede cambiar. Ver Errores.
| Estado | Códigos | Cuándo |
|---|---|---|
| 401 | INVALID_API_KEY | Clave ausente, mal formada, inexistente o revocada (INVALID_API_KEY). |
| 403 | SCOPE_REQUIREDAPI_PLAN_REQUIREDACCESS_DENIED | La clave no tiene el permiso de la operación (SCOPE_REQUIRED), el plan no incluye la API (API_PLAN_REQUIRED) o la cuenta no tiene acceso activo (ACCESS_DENIED). |
| 422 | VALIDATION_ERRORINVALID_CURSORCURSOR_EXPIRED | Parámetro inválido (VALIDATION_ERROR), cursor de otra consulta (INVALID_CURSOR) o cursor caducado a las 24 horas (CURSOR_EXPIRED). |
| 429 | RATE_LIMITED | Se superó el límite de peticiones (RATE_LIMITED). Espera lo que indica Retry-After. |
| 503 | DEPENDENCY_UNAVAILABLELOCAL_CAPACITY | Servicio no disponible temporalmente (DEPENDENCY_UNAVAILABLE o LOCAL_CAPACITY). Reintenta tras Retry-After. |