Cambios de la API

La API pública es la que vive bajo /v1 (autenticación). Dentro de v1 solo agregamos: operaciones nuevas, campos opcionales nuevos, campos nuevos en las respuestas, códigos de error nuevos. Lea con tolerancia los campos y códigos que no conozca. Un cambio que rompería un cliente que funciona (quitar o renombrar una operación o un campo, volver obligatorio un campo opcional) sale como /v2, anunciado aquí antes, con /v1 disponible al lado. La única salida dentro de v1 es la de una operación marcada Obsoleto: se anuncia aquí con su reemplazo, que ya funciona ese día, y con la fecha de retiro; hasta esa fecha responde igual que siempre.

Las rutas bajo /api/… y /_x/query/… son del panel y esta página no las cubre.

Cada entrada lleva su fecha (hora de Bogotá) y se marca como Agregado, Cambiado, Obsoleto o Retirado.

2026-10-09: un solo nombre por campo de paginación

Retirado

• endCursor y hasNextPage ya no vienen en una respuesta paginada. Desde el 30 de septiembre traían los mismos valores que nextCursor y hasMore, que toda respuesta paginada sigue trayendo y que desde hoy son los únicos nombres. Lea nextCursor y hasMore; nada más de la paginación cambia. Salieron sin período de obsolescencia porque eran segundos nombres de campos que la misma respuesta conserva, retirados por el framework sobre el que está construida la API; un campo sin reemplazo en la misma respuesta siempre lo tendrá.

Cambiado

• En la última página nextCursor es null: lo es exactamente cuando hasMore es false. Un cliente que repite mientras tenga un nextCursor ahora se detiene en la última página en vez de pedir una vacía después.

2026-09-30: lecturas de un objeto, un solo sobre de paginación, más creaciones idempotentes

Agregado

• Cuatro lecturas de un solo objeto: getCase (GET /v1/get-case, cases:read), getNotification (GET /v1/get-notification, notifications:read), getSendConfirmation (GET /v1/get-send-confirmation, notifications:read) y getImport (GET /v1/get-import, cases:read). Responden el objeto mismo, no una lista de una fila. Si no existe, o no es de su firma, la respuesta es 404 X_NOT_FOUND (errores).
• evidenceDownloadInfo (evidence:read): el nombre, el tamaño en bytes, el SHA-256 y la versión de formato (zipVersion) del paquete de evidencia de una notificación, con la llamada HTTP que lo descarga. No registra nada; la descarga (POST /v1/download-evidence) sí. Vea Paquete para el perito.
• Un solo sobre de paginación en todos los listados: con _first=<filas> la respuesta trae rows, nextCursor (lo que envía como _after para pedir la página siguiente) y hasMore (si hay otra). endCursor y hasNextPage siguen en la respuesta con los mismos valores, para los clientes que ya los leen. caseList, notificationList, listImports, ledgerList y orgActivity recorren ahora el listado completo con _first y _after; su limit y su cursor siguen funcionando. Desde hoy también se paginan bounceAlerts, caseRecipients, caseMemorials, partyAddresses, importSendables y listDeadlines. exportNotifications entrega hasta 5.000 líneas por archivo; cuando hay más responde truncated: true y un nextCursor, que se envía como cursor, con los mismos filtros, para el archivo siguiente.
• Idempotency-Key en siete operaciones más: send-notification, create-message-template, save-party-address, attach-document, confirm-upload, request-import-upload y confirm-import-upload. Un reintento con la misma clave y el mismo cuerpo devuelve la primera respuesta; la misma clave con otro cuerpo, 409 X_IDEMPOTENCY_CONFLICT (reintentos idempotentes). create-webhook-endpoint sigue sin clave: su respuesta trae el secreto de firma, que no se guarda para repetirlo.
• En openapi.json, cada operación declara en security el alcance exacto que exige su token.

Cambiado

• Un limit o un _first mayor que el máximo de un listado se rechaza con 400 X_INPUT_INVALID, que nombra el máximo; ningún listado lo recorta en silencio. Los tamaños de página y sus máximos están en Límites.
• send-notification con el mismo Idempotency-Key devuelve la primera solicitud pendiente en lugar de registrar otra.
• listDeadlines recibe la posición como cursor. after es su nombre anterior y se sigue aceptando; los dos con valores distintos responden 422 X_DEADLINE_CURSOR_CONFLICT.
• downloadEvidence ya no es una herramienta MCP: un asistente pide evidenceDownloadInfo y descarga por HTTP. En /v1, POST /v1/download-evidence no cambia.
• En una entrega de webhook, links.notification apunta ahora a GET /v1/get-notification?notificationId=…&orgId=… (webhooks); apuntaba a notification-detail, retirada abajo.

Retirado

Cuatro lecturas que respondían un arreglo de una fila se retiraron el 30 de septiembre de 2026, el mismo día en que salieron sus reemplazos de un objeto. Ningún token fuera de nuestro propio panel las había llamado, así que salieron sin periodo de obsolescencia; una operación que un cliente usa siempre lo tendrá. Una llamada a una de ellas responde ahora 404.

• Del catálogo MCP: downloadEvidence (vea Cambiado).

2026-09-27: v1

Agregado

• La API versionada en https://www.notificado.co/v1, autenticada solo con Authorization: Bearer <token> y un token de agente de /cuenta/api. El mismo token y los mismos seis alcances que el servidor MCP.
• Rutas legibles: cada operación en /v1/<su nombre en kebab-case>: createCase → POST /v1/create-case, caseList → GET /v1/case-list.
• Las operaciones de los seis alcances: procesos y partes, cargas, borradores de notificación y adjuntos, memoriales, pedir un envío (un abogado lo confirma en el panel), lecturas de notificaciones y evidencia, términos.
• Una operación fuera de los alcances del token responde 404, como si no existiera; sin token o con uno inválido, 401 con WWW-Authenticate.
• Un límite de 120 solicitudes por minuto por token, con RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset en cada respuesta y 429 + Retry-After al superarlo.
• Idempotency-Key en create-case, add-party, request-upload, create-notification y create-memorial (reintentos idempotentes).
• Toda negativa como application/problem+json con un code estable, una cause y un fix (errores), cada código en el catálogo de errores.
• El documento OpenAPI de exactamente esta API, con su esquema de seguridad bearer, en https://www.notificado.co/v1/openapi.json.
• Un inicio rápido con curl y TypeScript para el flujo completo.

Cambiado

• Las rutas del panel pasaron de rutas derivadas (/api/cases/create) a rutas legibles (/api/create-case). Nunca fueron un contrato público; las integraciones van sobre /v1.