Saltar al contenido
Vintu API
Tema de la documentación
Ir a la app

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"

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.