Other documents

Send PDF letters to Ropo using a JSON index file.

Send letters to Ropo as PDF + index JSON.

Use this for customer letters, contracts, reports, and similar documents.

Prerequisites

You need:

• cid + apicode

• a JWT token in Authorization: Bearer <token>

Authentication

Delivery options

You have two common ways to deliver the PDF.

Option A: HTTPS with embedded PDF (base64)

Put the base64-encoded PDF content in:

• image.file

Use this when your payload format supports embedded files.

Option B: Deliver the PDF as a separate file (ZIP)

Deliver the PDF file(s) and the index file in the same ZIP package.

Use this when:

• you cannot embed base64 in JSON

• the PDFs are large

• you want to upload file + data together

Data transfer limits and ZIP uploads

If you use SFTP delivery, the PDF and index must still be in the same ZIP package.

Minimum letter payload

Send one item in datastream.dataset[].

{
  "datastream": {
    "dataset": [
      {
        "jobtype": "301",
        "sendtype": "post",
        "customertype": "2",
        "person": "Nelli Niirulainen",
        "address": "Kellokoskenkatu 15 A 3",
        "postcode": "70100",
        "city": "KUOPIO",
        "addresscountry": "FIN",
        "countryname": "Finland",
        "propertyrow": [
          {
            "propname": "documenttype",
            "propvalue": "customerletter"
          }
        ],
        "image": {
          "filename": "letter.pdf",
          "file": "<base64-pdf>"
        }
      }
    ]
  }
}

Field reference

Fields live inside each datastream.dataset[] item.

Core fields

• jobtype (string, required)

  • Letter type in Ropo production.

  • For “other letter”, use "301".

• language (string, optional)

  • Example: "fin".

• sendtype (string, required)

  • Delivery channel.

  • Supported values:

    • post (printed and mailed)

    • email

• customertype (string, required)

  • "1" = company

  • "2" = consumer

• person (string, required if customertype is "2")

  • Consumer recipient name.

• company (string, required if customertype is "1")

  • Company recipient name.

Address fields

• address (string, required)

• postcode (string, required)

• city (string, required)

• addresscountry (string, required)

  • 3-letter country code (ISO 3166-1 alpha-3).

  • Example: "FIN".

• countryname (string, required)

  • Long country name.

  • Example: "Finland".

Email and phone

• email (string, required if sendtype is "email")

• phone (string, optional)

  • Example: "[phone]".

Identifiers and dates

• custnum (string, optional)

  • Your customer number.

• deliverydate (string, optional)

  • Format: YYYY-MM-DD.

Contracts

• contract[] (array, optional)

  • Items contain:

    • contract_no (string)

PDF attachment (image)

• image.filename (string)

  • PDF filename.

  • Required when the PDF is delivered as a separate file with the index.

• image.file (string)

  • Base64-encoded PDF.

  • Optional.

  • Use this for HTTPS embedded file delivery.

Usage place (optional)

• usageplaces[] (array, optional)

  • Items can contain:

    • address (object)

      • address (string)

      • city (string)

      • addresscountry (string)

      • postcode (string)

      • sitecode (string)

    • energycontract[] (array)

      • contract_no (string)

Properties (propertyrow)

• propertyrow[] (array, required)

  • Use this to send the document type.

  • Each item contains:

    • propname (string, required)

    • propvalue (string, required)

Supported documenttype values

Add one propertyrow item:

{
  "propname": "documenttype",
  "propvalue": "contract"
}

Supported propvalue values:

• invoice (Lasku)

• payslip (Palkka)

• customerletter (Asiakaskirje)

• questionnaire (Kysely)

• report (Raportti)

• contract (Sopimus)

• test (Testi)

• electricityinvoice (Sähkölasku)

• reminder (Maksukehotus)

• districtheatinginvoice (Lämpölasku)

• readingcard (Lukemakortti)

• adInvoice (Ilmoituslasku)

• interestinvoice (Korkolasku)

• rentinvoice (Vuokralasku)

• waterinvoice (Vesilasku)

• subscriptioninvoice (Tilauslasku)

• order (Tilaus)

• circulationinvoice (Levikkilasku)

Full JSON example

{
  "datastream": {
    "dataset": [
      {
        "jobtype": "301",
        "language": "fin",
        "person": "Nelli Niirulainen",
        "sendtype": "email",
        "company": "Yritys Oy",
        "address": "Kellokoskenkatu 15 A 3",
        "postcode": "70100",
        "city": "KUOPIO",
        "addresscountry": "FIN",
        "countryname": "Finland",
        "email": "[email protected]",
        "phone": "[phone]",
        "customertype": "2",
        "contract": [
          {
            "contract_no": "EN12345678"
          }
        ],
        "image": {
          "filename": "filename.pdf",
          "file": "AFSAFAFSAF"
        },
        "usageplaces": [
          {
            "address": {
              "address": "Kuninkaankatu 15",
              "city": "KUOPIO",
              "addresscountry": "FIN",
              "postcode": "70100",
              "sitecode": "123456"
            },
            "energycontract": [
              {
                "contract_no": "123456"
              }
            ]
          }
        ],
        "deliverydate": "2017-03-03",
        "custnum": "1234RR5",
        "propertyrow": [
          {
            "propname": "documenttype",
            "propvalue": "contract"
          }
        ]
      }
    ]
  }
}

Migration notes (V1 → V2)

If you still have a V1 payload, these fields were renamed in V2:

• deliverymethod → sendtype

• countrycode → addresscountry

• country → countryname

• emailaddress → email

• phonenumber → phone

• filename → image.filename

• contractnumber → usageplaces.energycontract.contract_no

• customernumber → custnum

• deliverysite.id → usageplaces.address.sitecode

• deliverysite.address → usageplaces.address.address