Ver una empresa
GET /v1/empresas/{id}
Una empresa de la cuenta por su id.
Permiso
La clave necesita empresas:leer. Ver Permisos.
Parámetros
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
id obligatorio | ruta | string · uuid | Identificador público del recurso. |
Petición
La clave se lee de la variable de entorno VINTU_API_KEY. Ver Inicio rápido.
curl "https://api.vintu.io/v1/empresas/00000000-0000-4000-8000-0000000000c1" \
-H "Authorization: Bearer $VINTU_API_KEY"const url = new URL("https://api.vintu.io/v1/empresas/00000000-0000-4000-8000-0000000000c1");
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/00000000-0000-4000-8000-0000000000c1",
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 |
|---|---|---|
id | string · uuid | Identificador público de la empresa. |
ruc | string | RUC de 11 dígitos. |
razon_social | string | Razón social registrada en la cuenta. |
creado_en | string · date-time | Alta de la empresa en Vintu. |
actualizado_en | string · date-time | Último cambio de la empresa. |
Ejemplo con datos ficticiosJSON
{
"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"
}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). |
| 404 | NOT_FOUND | El recurso no existe o no es de esta cuenta (NOT_FOUND). |
| 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. |