Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Status Notifications (events)

Receive real-time status events from Ropo One into your system.

Use this when you need push-based updates. Use Status Updates when you prefer polling.

  • note that polling service doesn't include as wide variety of different actions as status notification service does

Please note:

  • Ropo may add new fields to the messages described in this document without separately announcing them.

  • Changes which affects to current field content or naming or any other thing that breaks backward compatibility are announced as an own change process and are not implemented in production until users have had enough time to react.

What you receive

Ropo One sends HTTP POST requests to your endpoint. Each request contains one event batch.

One batch can include multiple message types. One batch contains max 500 messages.

Setup checklist

1

Expose a webhook endpoint

Accept POST requests over HTTPS. Parse JSON.

Make the handler idempotent. Use id to dedupe.

2

Choose authentication

Pick either OAuth2 client credentials or Basic Auth. Share the needed details with Ropo.

3

Return the right HTTP status codes

Return 2xx when you have stored the events. Return 4xx for permanent validation errors. Return 5xx for transient errors.

Authentication

Ropo fetches an access token from your token endpoint. Ropo then uses it as a Bearer token for webhook delivery.

Share these values with Ropo:

  • Token URL

  • Client ID

  • Client secret

  • Webhook service endpoint (your receiver URL)

  • Scope (if your token endpoint requires it)

Token request (from Ropo to you):

POST <token-url>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=<scope>&client_id=<client-id>&client_secret=<client-secret>

Expected token response (from you to Ropo):

{
  "token_type": "Bearer",
  "access_token": "<token>",
  "expires_in": 3600
}

Ropo uses HTTP Basic Auth for webhook delivery.

Share these values with Ropo:

  • User ID

  • Password

  • Webhook service endpoint (your receiver URL)

Envelope format

Every webhook payload uses the same envelope:

  • created_at (string): message creation time in ISO-8601 format.

  • id (string): unique message/batch id.

  • data (object): one or more arrays by message type.

data can contain any combination of these arrays:

  • delivery

  • lcstatus

  • payment

  • contract

  • creditnote

  • creditloss

  • duedateupdate

  • disconnect

  • reconnect

  • telecomdisconnect

  • telecomreconnect

Ropo may add new fields without separate notice. Ignore unknown fields to stay forward-compatible.

Common identification rules

Most message types identify the case using either:

  • invoicenumber

  • documentid (your additional identifier for the document in addition to invoice number)

  • jobid (Ropo One internal identifier)

Some messages all three. Don’t assume documentid is always present.

cid is the Ropo One profile id. It is mandatory in all message types.

Message types

Sample payloads

Examples are trimmed for readability. Expect more fields in production.

Single message type (delivery):

Batch with multiple message types:

Delivery status (data.delivery[])

Tells you how document delivery progressed.

Fields you’ll use most:

  • status: received | rejected | delivered | error

  • statustime: when the status changed

  • distributionchannel:

    • Finland post | b2b | peppol | email | b2c | kivra | omaposti

    • Sweden post | b2b | peppol | email | b2c | kivra

    • Norway post | b2b | peppol | email | b2c | digipost

  • description: extra details

  • notes[]: optional notes (received use case)

  • errors[]: optional errors (rejected/error use cases)

Delivery status values

  • received: document received by Ropo One

  • rejected: rejected on import. Check description and errors[]

  • delivered: delivered to recipient / next party

  • error: delivery failed. Check description and errors[]

Lifecycle status (data.lcstatus[])

Tells you when a case moved to a new lifecycle phase.

Fields you’ll use most:

  • code: lifecycle code

  • status: lifecycle text (often English)

  • time: when the status change happened

  • paydate: original due date

  • currentpaydate: current due date

  • opencapital, interest, expenses: open amounts by type (optional)

Lifecycle status codes

Most commonly used status codes:

Full list of possible status codes

  • This list can grow. Store the numeric code and treat status as informational.

Payment (data.payment[])

Tells you about payments received and booked in Ropo One.

Key points:

  • paydate is deprecated.

  • Use paymentdate, accountdate, and settlementdate for booking clarity.

    • paymentdate = Day when payment was made.

    • accountdate = Day when payment was booked to account

    • settlementdate = Day when payment was paid out from Ropo

  • openamount includes capital + client expenses + interest.

  • amountbreakdown and openamountbreakdown includes detailed view what receivable types were paid and are still open.

Contract (data.contract[])

Tells you about contract data changes, when contract updates are part of the agreed lifecycle.

Key fields:

  • contract_no (mandatory)

  • contractstatus (mandatory, example: active)

  • termination_date and terminationterm may be present if termination is calculated

Credit note (data.creditnote[])

Tells you when a credit note is:

  • allocated to a debit invoice

  • unallocated (allocation removed)

  • refunded to the end customer

Notes:

  • Allocation/unallocation may reference invoices via bill numbers and/or job IDs.

  • Credit notes allocated based on allocation info received from the client are not reported.

Credit loss (data.creditloss[])

Tells you about credit loss related actions.

Key fields:

  • type

    • suspected: suspected bad receivable before actual credit loss. Used only in Sweden.

    • creditloss: receivable has become bad debt.

    • change: bad debt receivable changed, for example after a payment.

  • amountbreakdown: amounts related to the credit loss action

  • reason: reason for the credit loss

    • OTHER

    • DECEASED

    • INDIGENT

    • UNKNOWN

    • RESTRUCTURING

    • DEBT_RESCHEDULING

    • BANKRUPTCY

    • SMALL_RECEIVABLE

    • NOCHANGE

    • DISPUTING

    • DISPUTED

Due date update (data.duedateupdate[])

Sent when due date changes in Ropo One.

Important fields:

  • currentpaydate: the new due date

  • source: why/how the update happened

  • contract[]: optional list of contract numbers (can be 1..n)

Due date update source values

  • restapi: updated from an external source via Ropo REST API

  • online: updated by end customer in Ropo online service

  • aspa_end_customer_request: updated by Ropo customer service on end customer request

  • aspa_other_reason: updated by Ropo customer service for other reasons

  • einvoice_error: updated after e-invoice negative ack, then fixed and resent

Disconnect / reconnect (data.disconnect[], data.reconnect[])

Sent when a process recognizes a disconnect/reconnect action is needed.

Both contain:

  • usageplacecode (mandatory)

  • contract_no (mandatory)

  • invoices[] with invoice identifiers (jobid, invoicenumber, optional documentid)

Disconnect may include disconnectiondate.

Telecom disconnect / reconnect (data.telecomdisconnect[], data.telecomreconnect[])

Sent when a process recognizes a Telecom disconnect/reconnect action is needed.

Relevant fields:

  • customernumber: points to the end customer whose telecom subscriptions should be disconnected or reconnected

  • time: timestamp when it was recognized that the subscription should be disconnected or reconnected

Error response body (optional)

You can return a problem details body with non-2xx responses. RFC 7807 is recommended.

Webhook definition (OpenAPI)

Status notification service

Status notification service

Payload

Status information provided from Ropo One.

created_atstring · dateOptional

Event creation timestamp in ISO8601 format

Example: 2019-08-12T14:36:00+00:00
idstringOptional

Event identification

Example: e69f55fe-46c4-45cf-ab16-85da60b63884
Responses
200

OK

No content

Payload

PreviousOther documentsNextStatus Updates (polling)

Last updated

Was this helpful?