Publish Documents via API

Publish Documents via API#

This guide demonstrates how a third-party client can publish an announcement with associated files to the Tablon using the udala.tablon REST API.

Scenario#

You have an external application that generates public announcements and needs to publish them on your Plone 6 Electronic Notice Board in multiple languages (for example, Basque eu and Spanish es).

1. Preparing the Payload#

The API accepts a dynamic JSON payload. You will need to encode any files in Base64 format.

Create a payload.json file:

{
  "record_number": "2024/001",
  "date_start": "2024-03-01T00:00:00",
  "date_end": "2024-03-31T23:59:59",
  "origin": "external",
  "translations": {
    "eu": {
        "origin_department": "Kultura Saila",
        "origin_details": "Udaletxea",
        "description": "Kultur egitarauaren diru-laguntzak",
        "publication_url": "https://www.donostia.eus"
    },
    "es": {
        "origin_department": "Departamento de Cultura",
        "origin_details": "Ayuntamiento",
        "description": "Subvenciones para programas culturales",
        "publication_url": "https://www.donostia.eus/es"
    }
  },
  "documents": [
    {
      "language": null,
      "filename": "deialdia_convocatoria.pdf",
      "contents": "JVBERi0xLjMKJc...",
      "titles": {
          "eu": "Deialdia",
          "es": "Convocatoria"
      }
    }
  ]
}

2. Sending the Request#

Use a tool like curl to post the payload to the @tablon endpoint. You must provide a valid authentication token (like a JWT or Basic Auth) with permissions to add content to the Tablon container.

curl -X POST "http://localhost:8080/Plone/@tablon" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -d @payload.json

3. Handling the Response#

If successful, the API returns a 201 Created status code and a JSON response containing the generated Shared UUID and the physical URLs of the created Plone items. The returned url_{lang} keys are dynamic and will precisely match the language codes provided in your payload's translations dictionary.

{
    "@id": "http://localhost:8080/Plone/@tablon/b2c3d4e5f6g7h8i9j0k1",
    "uuid": "b2c3d4e5f6g7h8i9j0k1",
    "url_eu": "http://localhost:8080/Plone/tablon_id/documento_tablon",
    "url_es": "http://localhost:8080/Plone/es/tablon_id/documento_tablon"
}

You can now use uuid to fetch, update, or delete the document through the @tablon endpoint, completely independent of its physical URL or language.

Contents