# Ropo One™  Embed

#### Embed service’s API calls <a href="#embed-services-api-calls" id="embed-services-api-calls"></a>

To be able to use Ropo’s Embed service through REST, the following API calls are required at minimum:

**Posting embed invoices to Ropo One**

{% content-ref url="/pages/rCNyPTWqcnz2cnjf7lCt" %}
[Invoice](/guides/basics/invoice.md)
{% endcontent-ref %}

#### Other most used REST API calls with Embed service <a href="#other-most-used-rest-api-calls-with-unify-service" id="other-most-used-rest-api-calls-with-unify-service"></a>

* **Posting bypass payments for invoices which are in Ropo One**

{% content-ref url="/pages/wd4TOwK261DeytWm5Qa6" %}
[Payment](/guides/basics/payment.md)
{% endcontent-ref %}

* **Get the invoice image from Ropo One.**\
  REST API call’s response returns the invoice image as PDF.

{% content-ref url="/pages/Nvip8UHIHLHOZDmSNfmU" %}
[Get PDF](/guides/general-add-ons/get-pdf.md)
{% endcontent-ref %}

* **Preview the invoice image before posting the invoice to Ropo One**

{% content-ref url="/pages/8DGD3VOZOjJIJ9k6CxKQ" %}
[Preview of invoice](/guides/general-add-ons/preview-of-invoice.md)
{% endcontent-ref %}

* **Post the invoice as a local print to Ropo One and send the invoice by yourself to the recipient.**\
  REST API call’s response returns the invoice image as PDF.

{% content-ref url="/pages/goQ5kgpXBYegxZA4J0Fq" %}
[Local print of invoice](/guides/general-add-ons/local-print-of-invoice.md)
{% endcontent-ref %}

***

### Embed: Posting Embed invoice with minimum level information to Ropo One <a href="#embed-posting-embed-invoice-with-minimum-level-information-to-ropo-one" id="embed-posting-embed-invoice-with-minimum-level-information-to-ropo-one"></a>

Minimum required level information in dataset JSON of the invoice, for posting it to be unify invoice in Ropo One, are listed below:

#### Invoice <a href="#invoice" id="invoice"></a>

**Invoice Data (`dataset` tag):**

* **jobtype:** Message type (e.g., 0 for invoice)
* **address:** Address of the recipient
* **postcode:** Customer’s postal code
* **company:** B2B end customer’s name (if customer type = 1)
* **person:** B2C end customer’s name (if customer type = 2)
* **city:** Customer’s post office
* **customertype:** Client type (1 = company, 2 = private person)
* **billdate:** Date of invoice in the form of YYYY-MM-DD
* **paydate:** Date of issue in the form of YYYY-MM-DD

**Invoice Rows (`payrow` tag):**

* **desc:** Name of the product
* **count:** Number of items
* **amount:** Unit price (excl. tax)
* **taxpr:** Value Added Tax (0-100)

**Accountrow**

* **accountid:** Specifies the account code for the transaction
* **debit** and **credit:** Indicate the amounts to be debited or credited
* **desc:** Provides a description of the transaction
* **netamount:** The net amount excluding VAT
* **vatamount:** The VAT amount
* **taxpr:** The VAT percentage

**Example JSON**

```json
{
  "datastream": {
    "dataset": [
      {
        "jobtype": "0",
        "company": "Example Company",
        "address": "123 Example Street",
        "postcode": "12345",
        "city": "Example City",
        "customertype": "1",
        "billdate": "2025-05-09",
        "paydate": "2025-06-09",
        "payrow": [
          {
            "desc": "Product Description",
            "count": "1",
            "amount": "100.00",
            "taxpr": "24.00"
          }
        ],
        "accountrow": [
          {
            "accountid": "1701",
            "debit": 124.0,
            "credit": null,
            "desc": "Invoice line",
            "netamount": 100.0,
            "vatamount": 24.0,
            "taxpr": 24
          },
          {
            "accountid": "3000",
            "debit": null,
            "credit": 124.0,
            "desc": "Invoice line",
            "netamount": 100.0,
            "vatamount": 24.0,
            "taxpr": 24
          }
        ]
      }
    ]
  }
}
```

***

### How to post the Embed invoice job to Ropo One <a href="#how-to-post-the-embed-invoice-job-to-ropo-one" id="how-to-post-the-embed-invoice-job-to-ropo-one"></a>

You need to know to which country and to which environment you are posting the reminder job. Ropo has country-specific environments for testing and production purposes.

#### Test environments <a href="#test-environments" id="test-environments"></a>

* **FIN:** [https://rc.ropo24.fi](https://rc.ropo24.fi/)
* **SWE:** [https://rc.ropo24.se](https://rc.ropo24.se/)
* **NOR:** [https://rc.ropo24.no](https://rc.ropo24.no/)

#### Prod environments <a href="#prod-environments" id="prod-environments"></a>

* **FIN:** [https://ropo24.fi](https://ropo24.fi/)
* **SWE:** [https://ropo24.se](https://ropo24.se/)
* **NOR:** [https://ropo24.no](https://ropo24.no/)

For each environment, your company’s Ropo One profile has its own `cid`and `apicode`.

When posting jobs to Ropo One, you should be using jobs API-call:\
Example Swagger link to Finnish environment: <https://rc.ropo24.fi/swagger/#/jobs/JobAddJobAction>

***

#### Authorization <a href="#authorization" id="authorization"></a>

First, you need to do the authorization with `cid` and `apicode` which Ropo has given to your knowledge:

**Fetch the token from the desired environment with your cid and apicode:**

```bash
curl -X POST "https://rc.ropo24.fi/rest/token" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{\"cid\":\"CIDCODE\",\"apicode\":\"APICODE\"}"
```

As a response, you will get the token:

```json
{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI3MDAwMDczIiwic2NvcGUiOltdLCJyb2xlcyI6WyJhcGljb2RlIl0sImlhdCI6MTc0Njc3NDQ0NywiZXhwIjoxNzQ2NzgxNjQ3fQ.OJGk9_760dldmaLIkqis2zv8hay5m6VsTDmiTfFuJUo_rTlrEgZXSyrnxhK50Xmfds9z-G-PXPfaJnQX_NnmKw"}
```

***

#### Posting the job <a href="#posting-the-job" id="posting-the-job"></a>

Then use the token as authorization header when posting job to Ropo One:

```bash
curl -X POST "https://rc.ropo24.fi/rest/jobs" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "datastream": {
      "dataset": [
        {
          "jobtype": "0",
          "company": "Example Company",
          "address": "123 Example Street",
          "postcode": "12345",
          "city": "Example City",
          "customertype": "1",
          "billdate": "2025-05-09",
          "paydate": "2025-06-09",
          "payrow": [
            {
              "desc": "Product Description",
              "count": "1",
              "amount": "100.00",
              "taxpr": "24.00"
            }
          ],
          "accountrow": [
            {
              "accountid": "1701",
              "debit": 124,
              "credit": null,
              "desc": "Sales Account",
              "netamount": 100,
              "vatamount": 24,
              "taxpr": 24
            },
            {
              "accountid": "3000",
              "debit": null,
              "credit": 124,
              "desc": "Receivable Account",
              "netamount": 100,
              "vatamount": 24,
              "taxpr": 24
            }
          ]
        }
      ]
    }
  }'
```

***

#### Response <a href="#response" id="response"></a>

As a response to posting the job to Ropo One, Ropo One gives the information whether the job was accepted or rejected.

```json
{
  "result": [
    {
      "accepted": 1,
      "amount": 124,
      "billnum": "3224",
      "billcode": "",
      "error": null,
      "evoicetype": "",
      "jobid": 28118113,
      "jobstatus": "0",
      "jobtype": "0",
      "notice": null,
      "origbillnum": null,
      "ownref": "",
      "print": null,
      "receiver": "Example Company",
      "reference": "157000073281181136",
      "sendtype": "post"
    }
  ],
  "errors": [],
  "accepted": 1
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ropo.com/guides/service-models/ropo-one-tm-embed.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.