Ver un aviso de buzón
GET /v1/avisos/{id}
Un aviso por su id.
Permiso
La clave necesita avisos: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/avisos/00000000-0000-4000-8000-0000000000e1" \
-H "Authorization: Bearer $VINTU_API_KEY"const url = new URL("https://api.vintu.io/v1/avisos/00000000-0000-4000-8000-0000000000e1");
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/avisos/00000000-0000-4000-8000-0000000000e1",
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 del aviso. |
empresa_id | string · uuid | Empresa a la que llegó el aviso. |
entidad | string | sunat o sunafil. |
buzon | string | null | Buzón de origen: notificaciones o mensajes en SUNAT; fiscalizacion, cobranza, acciones_previas, formalizacion, sst u orientaciones en SUNAFIL. Nulo en avisos antiguos que no lo registraron. |
tipo | string | null | Tipo de notificación tal como lo clasifica el buzón. |
asunto | string | null | Asunto del aviso. |
fecha_notificacion | string · date-time | null | Fecha en que la entidad lo notificó; nula si no la publica. |
creado_en | string · date-time | Primera vez que Vintu lo leyó. |
actualizado_en | string · date-time | Último cambio del aviso. |
Ejemplo con datos ficticiosJSON
{
"id": "00000000-0000-4000-8000-0000000000e1",
"empresa_id": "00000000-0000-4000-8000-0000000000c1",
"entidad": "sunat",
"buzon": "notificaciones",
"tipo": "VALORES",
"asunto": "Notificación de ejemplo",
"fecha_notificacion": "2026-11-11T13:00:00+00:00",
"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. |