Masnet | API de escritura de Comunicados

Qué permite

Publicaciones: un comunicado en un canal, con título, resumen y un cuerpo en Markdown o HTML. Se guarda como borrador, se publica ahora o se programa, y puede retirarse, archivarse, desarchivarse y reactivarse.
Avisos destacados: un mensaje corto con severidad, vigencia y audiencia, que puede apuntar a una publicación o a un canal, o ser independiente. Se guarda como borrador, se activa ahora o se programa, y puede resolverse y reactivarse.
Una vista previa del contenido, que muestra cómo se convierte el texto y qué avisos y campañas afectaría publicarlo.
La lectura de los canales y de las audiencias otorgadas, y de los objetos que la propia integración creó.

Las personas destinatarias, las confirmaciones de lectura y los miembros de la empresa no existen en esta API, y tampoco hay rutas para borrar objetos: un objeto se retira o se resuelve y conserva su identidad.

Autenticación y concesión

Las solicitudes se autentican como las de la API de datos: un token OAuth 2.0 o una API key, enviados como Authorization: Bearer. El scope read:communications lee los canales, las audiencias y los objetos propios. El scope write:communications además escribe y no hereda la publicación: publicar es una concesión aparte.

El scope no basta. El administrador de la empresa otorga a la integración, en Empresa › Integraciones de la aplicación, el permiso de datos del dominio communications. Ese permiso exige el grupo de campos confidential y, para nombrar personas en una audiencia, también people. Sin permiso o sin scope, la API responde 403 insufficient_scope. Quien otorga o amplía el permiso necesita en la aplicación los permisos equivalentes a lo que delega.

La concesión se lee de nuevo en cada solicitud: lo que se revoque deja de valer de inmediato. Una extensión ausente equivale a una vacía y todo se deniega. Todo lo que se omite toma el valor que menos permite.

Rutas de campo

Un permiso de escritura lleva rutas del registro cerrado communications/1. Sin rutas explícitas se otorgan solo las de borradores. Las tres últimas exigen además can_publish.

Rutas de campo
Ruta	Qué permite	Exige `can_publish`
`publications.content`	Crear y editar publicaciones como borrador, y la vista previa del contenido. Se otorga por omisión.	No
`publications.publish`	Publicar o programar una publicación, o reactivarla.	Sí
`highlights.content`	Crear y editar avisos como borrador. Se otorga por omisión.	No
`highlights.activate`	Activar o programar un aviso, o reactivarlo. Exige también `highlights.content`.	Sí
`lifecycle`	Retirar, archivar y desarchivar publicaciones, y resolver avisos.	Sí

Qué limita la concesión

Extensión del permiso
Campo del permiso	Efecto
`allowed_channel_ids` (hasta 100)	Canales en los que la integración escribe. Es también el único conjunto de canales que puede usar como destino de un aviso.
`allowed_reader_group_ids` (hasta 100)	Grupos de lectores que puede usar en una audiencia `selected`.
`allowed_user_ids` (hasta 200)	Personas que puede usar en una audiencia `selected`. Exige el grupo de campos `people`.
`can_publish`	Habilita las rutas de publicación.
`max_severity`	Severidad máxima de un aviso: `info`, `important`, `critical`, en ese orden. Por omisión, `info`.
`can_create_standalone_highlights`	Avisos independientes, sin publicación ni canal de destino.
`allow_channel_audience`	Audiencia `channel` en un aviso con destino. Exige al menos un canal otorgado.
`allow_tenant_audience`	Audiencia `tenant` en un aviso independiente. Exige `can_create_standalone_highlights`.

Rutas

Todas cuelgan de https://daas.masnet.com/api/v1/integrations/data/communications. La clave de idempotencia es obligatoria en cada escritura, salvo en la vista previa de contenido.

Rutas de Comunicados
Método y ruta	Uso	Ruta de campo	Éxito
`GET /channels`	Canales otorgados: `id`, `name` y `archived`.	Lectura	`200`
`GET /audiences`	Modos de audiencia disponibles (`selected`, `channel`, `tenant`) y las referencias opacas `ref` de los grupos y personas otorgados. No incluye a los miembros.	Lectura	`200`
`POST /content-preview`	Convierte el contenido y calcula su resumen. No escribe.	`publications.content`	`200`
`PUT /publications/{external_id}`	Crea o actualiza una publicación.	`publications.content`; con `state: published`, también `publications.publish`	`201` al crear, `200` al actualizar
`GET /publications/{external_id}`	Lee una publicación propia.	Lectura	`200`
`POST /publications/{external_id}/withdraw`	Retira la publicación.	`lifecycle`	`200`
`POST /publications/{external_id}/archive`	Archiva una publicación publicada.	`lifecycle`	`200`
`POST /publications/{external_id}/unarchive`	Devuelve una publicación archivada a publicada.	`lifecycle`	`200`
`POST /publications/{external_id}/reactivate`	Reactiva una publicación retirada.	`publications.content` y `publications.publish`	`200`
`PUT /highlights/{external_id}`	Crea o actualiza un aviso.	`highlights.content`; con `state: active`, también `highlights.activate`	`201` al crear, `200` al actualizar
`GET /highlights/{external_id}`	Lee un aviso propio.	Lectura	`200`
`POST /highlights/{external_id}/resolve`	Resuelve el aviso: lo retira sin borrarlo.	`lifecycle`	`200`
`POST /highlights/{external_id}/reactivate`	Reactiva un aviso vencido o resuelto.	`highlights.content` y `highlights.activate`	`200`

Los cuerpos son JSON y se rechazan si traen un campo desconocido. Los comandos (withdraw, archive, unarchive, resolve) llevan el cuerpo {}. Un campo de empresa, autoría, entorno, propiedad, privilegios o permisos se rechaza con un código propio, no se ignora.

Cada respuesta correcta lleva el objeto en data y, cuando corresponde, la cabecera ETag. Una creación responde además Location, y la repetición de una operación ya aplicada, Idempotency-Replayed: true. Un error lleva forbidden_field, unknown_field u otro código de Errores.

Identidad y concurrencia

El external_id de la ruta es el identificador estable del objeto en su sistema: de 1 a 128 caracteres ASCII que empiezan con letra o dígito y admiten . _ : - (^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$). Identifica al objeto dentro del espacio de la integración, el entorno y el tipo: dos integraciones pueden usar el mismo external_id, y un objeto de otra integración o empresa responde 404 unavailable, igual que uno inexistente.

Mecanismos de concurrencia
Mecanismo	Cómo se usa
`source_revision`	Entero mayor o igual que 1 que su sistema hace crecer con cada cambio del objeto. La API lo guarda como la última revisión aceptada.
`Idempotency-Key`	De 8 a 128 caracteres `A-Z a-z 0-9 . _ : -`, una por intención. La misma clave con la misma solicitud (ruta, cuerpo y precondiciones) devuelve el resultado anterior sin repetir el efecto y marca `Idempotency-Replayed: true`. Con otra solicitud responde `409 idempotency_conflict`. Se conserva 72 horas.
`If-None-Match: *`	Obligatoria para crear. Sin ella, `428 precondition_required`.
`If-Match`	Obligatoria para actualizar y para cada comando, con el `etag` vigente del objeto (cabecera `ETag` o miembro `etag`). Otro valor responde `409 version_conflict`.

Qué responde un PUT

Resultado de un PUT
Situación	Resultado
El objeto no existe	Con `If-None-Match: *`, lo crea y responde `201`. Sin ella, `428 precondition_required`.
`source_revision` mayor que la última aceptada	Con `If-Match` y el `etag` vigente, aplica el cambio y responde `200`. Con `If-None-Match`, `409 already_exists`.
Misma `source_revision` y mismo cuerpo	Devuelve el resultado anterior sin escribir.
Misma `source_revision` y otro cuerpo	`409 source_revision_conflict`, con `details.current_source_revision`.
`source_revision` menor	`409 stale_source_revision`, con `details.current_source_revision`.
El objeto está retirado, resuelto o vencido	`409 terminal_state`. Un `PUT` no lo reactiva: se usa el comando `reactivate`.
Una persona tomó el control del objeto	`409 manual_control`, sin efecto.

Ante un tiempo de espera o un 503, repita la solicitud con la misma Idempotency-Key. Los bloqueos y los fallos de serialización de la base responden 503 temporarily_unavailable con Retry-After: 5 y también se reintentan con la misma clave. Véanse idempotency_key_required, idempotency_conflict, version_conflict, source_revision_conflict, stale_source_revision.

Publicaciones

Campos de una publicación
Campo	Descripción
`source_revision`	Obligatorio. Entero mayor o igual que 1.
`channel_id`	Obligatorio. UUID de un canal otorgado. No cambia después de crear la publicación (`409 immutable_channel`).
`title`	Obligatorio. De 1 a 160 caracteres.
`summary`	Opcional. Hasta 400 caracteres. Si se omite, se deriva del contenido.
`reference_date`	Opcional. Fecha civil `AAAA-MM-DD`.
`content`	Obligatorio. `{ "format": "markdown" \| "html", "value": "…" }`. Véase Contenido.
`state`	`draft` (por omisión) guarda un borrador. `published` guarda el borrador y lo publica en la misma operación.
`scheduled_at`	Instante RFC 3339 con zona explícita. Solo con `state: published`. Si es posterior en más de 5 segundos, la publicación queda programada y se publica sola. Si no, se publica de inmediato. No se puede programar una publicación ya publicada o archivada.
`preview_digest`	Resumen de 64 caracteres hexadecimales de la vista previa. Obligatorio al publicar de nuevo una publicación que tiene avisos o campañas afectados. Si se envía, debe corresponder al contenido, al `external_id` y a la `source_revision`.
`confirm_linked_highlight_effects`	`true` cuando hay avisos críticos o con confirmación de lectura afectados.
`accept_lossy_conversion`	`true` para publicar contenido que se convirtió con advertencias.

Un PUT con state: draft solo escribe el borrador: la edición visible de una publicación ya publicada no cambia hasta publicar. La respuesta distingue la edición published, el draft y la scheduled, cada una con title, summary, reference_date, revision_digest, origin y las warnings de la conversión.

Estados y comandos

Estados de una publicación
Operación	Desde	Hacia
`PUT` con `state: draft`	Sin objeto, o cualquier estado salvo `withdrawn`	`draft` si no existía. Si no, el mismo estado, con una edición en borrador
`PUT` con `state: published`	Sin objeto, borrador, publicada, archivada o bloqueada	`published`, o `scheduled` con `scheduled_at` futuro
`archive`	`published`	`archived`
`unarchive`	`archived`	`published`
`withdraw`	`published`, `scheduled`, `blocked` o `archived`	`withdrawn`
`reactivate`	`withdrawn`	`published`

Los estados posibles son draft, scheduled, published, archived, withdrawn y blocked. Un comando que no corresponde al estado responde 409 invalid_transition.
Retirar una publicación retira también los avisos activos o programados que apuntan a ella y bloquea las campañas de Encuestas que la usan de contexto.
reactivate lleva el mismo cuerpo que el PUT sin state, con If-Match y una source_revision mayor, y exige contenido posterior al retiro (409 new_revision_required).
Publicar de nuevo una publicación que tiene avisos activos exige el preview_digest y, si alguno es crítico o pide confirmación de lectura, confirm_linked_highlight_effects: true. Si la concesión de hoy no cubre esos avisos, la respuesta es 403 linked_highlight_effect_not_authorized.

Contenido y vista previa

content.value es Markdown o HTML. La API lo convierte a un árbol de nodos communication_nodes/1, que es lo que ven las personas, y devuelve en la vista previa los nodos, las advertencias y los resúmenes. El HTML se sanea: no se conserva nada activo.

Gramática del contenido
Admitido	Detalle
Bloques	Párrafos, títulos de nivel 2 a 4, listas ordenadas y no ordenadas, citas y bloques de código.
En línea	Texto, énfasis, negrita, código y enlaces.
Enlaces	Solo direcciones `https://` absolutas y sin credenciales, de hasta 2.048 caracteres. Otra forma responde `422 unsafe_link`.
Rechazado	HTML con elementos activos, como `script`, `style`, `iframe`, `form` o `svg`, o con atributos de eventos o direcciones peligrosas (`422 unsafe_html`).

Lo que no tiene equivalente no se rechaza: se convierte con una advertencia. Una conversión con advertencias es lossy: true y solo se publica con accept_lossy_conversion: true.

Advertencias de conversión
Advertencia	Cuándo aparece
`heading_level_adjusted`	Un título fuera de los niveles admitidos se ajusta.
`image_removed`	Se retiró una imagen.
`table_flattened`	Una tabla se convirtió en texto.
`unsupported_element`	Se descartó un elemento sin equivalente. `detail` nombra la etiqueta.
`list_start_ignored`	Una lista ordenada no empezaba en 1.
`link_title_removed`	Se retiró el título de un enlace.
`nested_link_flattened`	Un enlace dentro de otro se convirtió en texto.
`control_characters_removed`	Se retiraron caracteres de control.

Vista previa

POST /content-preview recibe el mismo contenido que un PUT de publicación más el external_id, y no escribe. Devuelve los nodos del cuerpo (body), las warnings con su code y detail, lossy, el revision_digest del contenido y el preview_digest que liga ese contenido con la identidad, la revisión y los efectos de hoy. Si publicar renovaría una publicación con avisos o campañas enlazados, informa linked_highlight_effects (con external_id, severity y requires_ack), affected_count, requires_effect_confirmation y affected_campaigns.

Límites del contenido
Límite del contenido	Valor
Texto de entrada (`content.value`)	100 KiB en UTF-8 (`413 content_too_large`)
Nodos del árbol	2.000 (`422 too_many_nodes`)
Anidación	16 niveles (`422 too_deep`)
Árbol serializado	256 KiB (`422 tree_too_large`)

Avisos destacados

Campos de un aviso
Campo	Descripción
`source_revision`	Obligatorio. Entero mayor o igual que 1.
`state`	`draft` (por omisión) guarda un borrador. `active` lo activa en la misma operación.
`title`	Obligatorio. De 1 a 80 caracteres.
`message`	Obligatorio. De 1 a 240 caracteres.
`severity`	`info` (por omisión), `important` o `critical`. No puede superar el `max_severity` otorgado.
`priority`	Entero de -1.000 a 1.000. Por omisión, 0.
`target`	Ausente o `null` para un aviso independiente. `{ "kind": "communication_channel", "channel_id": "…" }` apunta a un canal otorgado. `{ "kind": "communication_publication", "external_id": "…" }` apunta a una publicación de la misma integración y entorno, y el canal se deduce de ella.
`audience`	Obligatorio. `{ "mode": "channel" }` hereda la audiencia del canal y solo vale con destino. `{ "mode": "tenant" }` es para toda la empresa y solo vale en un aviso independiente. `{ "mode": "selected", "group_refs": […], "user_refs": […] }` usa las referencias de `GET /audiences`, de 1 a 100 en total.
`starts_at`, `ends_at`	Obligatorios. Instantes RFC 3339 con zona explícita. El fin es posterior al inicio y la vigencia dura como máximo 90 días, 30 si la severidad es `critical`.
`requires_ack`	`true` pide confirmación de lectura. Por omisión, `false`.

Con state: active y un starts_at pasado, el aviso queda activo. Con un starts_at futuro queda programado y se activa solo. Con un ends_at pasado, la respuesta es 422 window_elapsed.
Un PUT con state: draft guarda la edición sin cambiar la que ven las personas.
Los estados posibles son draft, scheduled, active, expired, withdrawn y blocked. La vista distingue la edición active y el draft, y cada una trae material_digest y origin.
resolve retira un aviso activo, programado o bloqueado sin borrarlo y deja su identidad. reactivate lleva el mismo cuerpo que el PUT sin state, con If-Match y una source_revision mayor, y solo vale desde expired o withdrawn.

Errores frecuentes: severity_not_granted, audience_not_granted, standalone_not_granted, invalid_target, target_unavailable, invalid_window, audience_required.

Control y revocación

Cada objeto informa control: integration mientras lo gobierna la integración y local si una persona tomó el control en la aplicación. Con control: local, toda escritura externa responde 409 manual_control y no tiene efecto. Una persona puede devolver el control desde la aplicación: la última source_revision aceptada queda como piso, y solo una revisión estrictamente mayor avanza.

Quitar el permiso de Comunicados o revocar la integración libera sus objetos: pasan a control local, lo programado queda blocked (blocked_reason grant_removed o integration_revoked), y se conservan la identidad y el historial. Quitar un canal libera solo lo de ese canal (channel_removed).
Volver a otorgar el permiso no reclama lo liberado: la integración recibe 409 manual_control hasta que una persona devuelva el control.
El sistema revalida contra la concesión de hoy lo que la integración dejó programado antes de cada efecto. Si ya no lo cubre, lo bloquea con authority_lost o linked_effect_not_authorized y nunca lo activa con una autoridad más amplia que la vigente.

Integraciones de pruebas

Una integración de ambiente de pruebas trabaja en su propio espacio, que nunca ven las personas. Solo puede previsualizar contenido, leer lo propio y guardar borradores. Publicar, programar, activar, retirar, resolver, archivar, desarchivar y reactivar responden 403 test_environment antes de tener efecto. El ambiente sale de la credencial: una API key mk_test_… o un cliente de una integración de pruebas trabajan en este espacio.

Límites y cuotas

Límites de Comunicados
Alcance	Límite	Al excederlo
Cuerpo de la solicitud	160 KiB	`413 payload_too_large`
Escrituras por cliente	60 por minuto	`429 rate_limited` con `Retry-After: 60`
Escrituras por empresa, sumadas todas sus integraciones	300 por minuto	`429 rate_limited` con `Retry-After: 60`
Objetos nuevos por integración, borradores incluidos	600 por hora	`429 object_quota_exceeded` con `Retry-After: 600`
Objetos vinculados vivos por integración	20.000	`409 binding_limit_reached`
Publicaciones publicadas, archivadas o programadas por empresa	2.000	`409 tenant_content_limit`
Avisos activos o programados por empresa	100	`409 tenant_content_limit`

Las cuotas por minuto se miden con un contador compartido y no pasan sin medir: si el contador no responde, la solicitud se rechaza con 503 quota_unavailable y Retry-After: 30, no se ejecuta y no tiene efecto. Reintente con la misma Idempotency-Key. Los demás topes se miden en la base de datos. Las lecturas siguen la cuota común de la API de datos.

Si la empresa está en modo de solo lectura por mantenimiento, toda escritura nueva responde 503 communications_read_only con Retry-After: 60, sin efecto. Si el plan de la empresa no incluye Comunicados, la respuesta es 403 module_unavailable.

Errores

Los errores usan application/problem+json (RFC 9457) con type, title, status, detail, code y correlation_id. Algunos añaden un miembro details: fields (hasta cinco campos), field, max, current_source_revision, allowed o required. El detalle nunca repite el contenido enviado ni revela datos de otra empresa.

Códigos de Comunicados
Estado	Códigos
`400`	forbidden_field, invalid_shape, unknown_field, invalid_external_id
`403`	insufficient_scope, module_unavailable, test_environment, channel_not_granted, field_not_granted, publish_not_granted, activate_not_granted, lifecycle_not_granted, standalone_not_granted, severity_not_granted, audience_not_granted, linked_highlight_effect_not_authorized
`404`	unavailable
`409`	version_conflict, source_revision_conflict, stale_source_revision, idempotency_conflict, already_exists, manual_control, terminal_state, invalid_transition, immutable_channel, channel_archived, preview_stale, missing_draft, new_revision_required, lossy_conversion_not_accepted, binding_limit_reached, tenant_content_limit
`413`	payload_too_large, content_too_large
`422`	invalid_source_revision, invalid_field, field_length, invalid_state, invalid_date, invalid_instant, scheduled_requires_published, invalid_content_format, invalid_content, unsafe_html, unsafe_link, too_many_nodes, too_deep, tree_too_large, invalid_unicode, empty_content, invalid_target, target_unavailable, invalid_audience, audience_required, invalid_window, window_elapsed
`428`	idempotency_key_required, precondition_required
`429`	rate_limited, object_quota_exceeded
`503`	quota_unavailable, communications_read_only, temporarily_unavailable

La lista completa, con la causa y la acción de cada código, está en Errores.

Ejemplos

Los identificadores, las fechas y los resúmenes son de ejemplo. Los resúmenes de la publicación se calcularon con el código de la API sobre el contenido que se muestra.

1. Previsualizar el contenido

Solicitud

POST /api/v1/integrations/data/communications/content-preview HTTP/1.1
Host: daas.masnet.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "external_id": "erp-aviso-2026-0142",
  "source_revision": 1,
  "channel_id": "3f2b9a52-6d41-4c63-9a0e-7b1d5c8e2f10",
  "title": "Cierre anticipado de despacho",
  "summary": "El viernes 6 de noviembre el despacho cerrará a las 15:00.",
  "reference_date": "2026-11-06",
  "content": { "format": "markdown", "value": "## Horario\nRecibiremos pedidos hasta las **15:00**." }
}

Respuesta

{
  "data": {
    "external_id": "erp-aviso-2026-0142",
    "source_revision": 1,
    "title": "Cierre anticipado de despacho",
    "summary": "El viernes 6 de noviembre el despacho cerrará a las 15:00.",
    "reference_date": "2026-11-06",
    "body": {
      "format": "communication_nodes",
      "version": 1,
      "nodes": [
        { "type": "heading", "level": 2, "children": [{ "type": "text", "text": "Horario" }] },
        {
          "type": "paragraph",
          "children": [
            { "type": "text", "text": "Recibiremos pedidos hasta las " },
            { "type": "strong", "children": [{ "type": "text", "text": "15:00" }] },
            { "type": "text", "text": "." }
          ]
        }
      ]
    },
    "warnings": [],
    "lossy": false,
    "revision_digest": "c6e43004945b4ba969ada3d4fef798db024dc00d086c9a3b7785f34e4b959208",
    "preview_digest": "cfc609c35176ee914dc1db9f77d35a2a6113f02361f16462974c27f0ab277a8a",
    "linked_highlight_effects": [],
    "affected_count": 0,
    "requires_effect_confirmation": false,
    "affected_campaigns": 0,
    "environment": "production"
  }
}

2. Crear y publicar la publicación

Se crea con If-None-Match: * y se publica en la misma operación. El ETag de la respuesta es el etag que exigirán los cambios siguientes.

Solicitud

PUT /api/v1/integrations/data/communications/publications/erp-aviso-2026-0142 HTTP/1.1
Host: daas.masnet.com
Authorization: Bearer <token>
Idempotency-Key: 6f1d2c9e-4b7a-4c1e-9d55-0a1b2c3d4e5f
If-None-Match: *
Content-Type: application/json

{
  "source_revision": 1,
  "channel_id": "3f2b9a52-6d41-4c63-9a0e-7b1d5c8e2f10",
  "title": "Cierre anticipado de despacho",
  "summary": "El viernes 6 de noviembre el despacho cerrará a las 15:00.",
  "reference_date": "2026-11-06",
  "content": { "format": "markdown", "value": "## Horario\nRecibiremos pedidos hasta las **15:00**." },
  "state": "published"
}

Respuesta

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
ETag: "mK3vQ9xT1uYw7Rz2LpA8cE"
Location: /api/v1/integrations/data/communications/publications/erp-aviso-2026-0142

{
  "data": {
    "external_id": "erp-aviso-2026-0142",
    "kind": "publication",
    "channel_id": "3f2b9a52-6d41-4c63-9a0e-7b1d5c8e2f10",
    "status": "published",
    "blocked_reason": null,
    "control": "integration",
    "environment": "production",
    "source_revision": 1,
    "etag": "\"mK3vQ9xT1uYw7Rz2LpA8cE\"",
    "published": {
      "title": "Cierre anticipado de despacho",
      "summary": "El viernes 6 de noviembre el despacho cerrará a las 15:00.",
      "reference_date": "2026-11-06",
      "revision_digest": "c6e43004945b4ba969ada3d4fef798db024dc00d086c9a3b7785f34e4b959208",
      "origin": "integration",
      "warnings": []
    },
    "draft": null,
    "scheduled": null,
    "first_published_at": "2026-11-04T14:32:08.114Z",
    "published_at": "2026-11-04T14:32:08.114Z",
    "archived_at": null,
    "withdrawn_at": null,
    "updated_at": "2026-11-04T14:32:08.114Z"
  }
}

3. Crear un aviso que apunta a la publicación

Solicitud

PUT /api/v1/integrations/data/communications/highlights/erp-incidencia-2026-0031 HTTP/1.1
Host: daas.masnet.com
Authorization: Bearer <token>
Idempotency-Key: 9a4c7e12-3d58-4b60-8f1a-c2e5d7b09a36
If-None-Match: *
Content-Type: application/json

{
  "source_revision": 1,
  "state": "active",
  "title": "Despacho con retraso en la Región de Valparaíso",
  "message": "Los despachos a la Región de Valparaíso se entregarán con un día de retraso.",
  "severity": "important",
  "priority": 10,
  "target": { "kind": "communication_publication", "external_id": "erp-aviso-2026-0142" },
  "audience": { "mode": "channel" },
  "starts_at": "2026-11-04T15:00:00-03:00",
  "ends_at": "2026-11-06T18:00:00-03:00",
  "requires_ack": false
}

Respuesta

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
ETag: "Qe5nB2sXc8TgV0hJrW1dYa"
Location: /api/v1/integrations/data/communications/highlights/erp-incidencia-2026-0031

{
  "data": {
    "external_id": "erp-incidencia-2026-0031",
    "kind": "highlight",
    "status": "active",
    "blocked_reason": null,
    "control": "integration",
    "environment": "production",
    "source_revision": 1,
    "etag": "\"Qe5nB2sXc8TgV0hJrW1dYa\"",
    "active": {
      "title": "Despacho con retraso en la Región de Valparaíso",
      "message": "Los despachos a la Región de Valparaíso se entregarán con un día de retraso.",
      "severity": "important",
      "priority": 10,
      "target": { "kind": "communication_publication", "channel_id": "3f2b9a52-6d41-4c63-9a0e-7b1d5c8e2f10", "external_id": "erp-aviso-2026-0142" },
      "audience": { "mode": "channel", "group_refs": [], "user_refs": [] },
      "starts_at": "2026-11-04T18:00:00.000Z",
      "ends_at": "2026-11-06T21:00:00.000Z",
      "requires_ack": false,
      "material_digest": "5be21f0c7a94d3860e1c47b2f9a8d6053ce1b7490d2f58a6e3c0b9174d8a2f61",
      "origin": "integration"
    },
    "draft": null,
    "activated_at": "2026-11-04T18:04:51.307Z",
    "withdrawn_at": null,
    "updated_at": "2026-11-04T18:04:51.307Z"
  }
}

4. Retirar la publicación

Un comando lleva If-Match con el etag vigente y el cuerpo {}. Retirar la publicación retira también el aviso que apunta a ella.

Solicitud

POST /api/v1/integrations/data/communications/publications/erp-aviso-2026-0142/withdraw HTTP/1.1
Host: daas.masnet.com
Authorization: Bearer <token>
Idempotency-Key: d3f08a57-61b2-4e94-a7c0-1e9b5f2c8d47
If-Match: "mK3vQ9xT1uYw7Rz2LpA8cE"
Content-Type: application/json

{}

Un cambio con una revisión anterior

Respuesta de error

HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset=utf-8

{
  "details": { "current_source_revision": 3 },
  "type": "https://masnet.com/developers/errors/stale_source_revision",
  "title": "Conflicto",
  "status": 409,
  "detail": "El recurso cambió o la operación no corresponde a su estado.",
  "code": "stale_source_revision",
  "correlation_id": "4c9e1d7a-52b8-4f03-9a6e-d18b0c3f5e72"
}

Cuota no disponible

Respuesta de error

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json; charset=utf-8
Retry-After: 30

{
  "type": "https://masnet.com/developers/errors/quota_unavailable",
  "title": "Cuota no disponible",
  "status": 503,
  "detail": "No se pudo medir la cuota de escritura; la solicitud no se ejecutó.",
  "code": "quota_unavailable",
  "correlation_id": "b27e90c4-1d63-4a58-8f0b-7c5a2e9d1f36"
}