API docs by Redocly

Urban Sharing - SAP BUBI API (7.2.0)

Download OpenAPI specification:

Urban Sharing Support: info@urbansharing.com URL: https://www.urbansharing.com

REST-to-SOAP proxy that integrates the BUBI bike-sharing system with BKK's SAP R/3 ECC 6.0 ERP. Exposes a JSON REST API and translates requests to WSDL-based SOAP web service calls.

SD interface — Submits billing line items to SAP Sales and Distribution. SAP creates an SD Order, generates an Invoice, reports to the NAV online invoice data service, and books the invoice to the customer account. Hungarian law requires an invoice at the time of BUBI service usage, regardless of payment success.

NAV interface — Validates Hungarian tax numbers against the National Tax and Customs Administration (NTCA) database and returns the legal entity's official registered name and address. Pre-validation is mandatory; NAV rejects invalid data during online invoice reporting.

Release History
DateVersionNotes
Fri Apr 10 20267.2.0SD: optional overrides.authId restored; SAP AuthId is overrides.authId when set, otherwise paymentTransaction.externalId (TransId remains externalId)
Fri Apr 10 20267.1.0SD: optional paymentTransaction.isFullyRefunded (boolean): with originalInvoiceId, false maps to INVOICETYPE "2" (partial refund), true or omitted maps to "3" (full refund)
Fri Apr 10 20267.0.0Breaking: overrides.authId removed; SAP AuthId is always paymentTransaction.externalId (same as TransId; no appended "1")
SD: idempotency cache keys for SD change for the same payload vs releases before this until TTL expires
Thu Apr 09 20266.0.0Breaking: paymentTransaction.refundedTransactionId removed; use originalInvoiceId (string, optional, max 10) — the SAP invoiceId from the original POST /invoice response
SD: Originalinvoicenumber now carries that SAP invoice number; INVOICETYPE remains "1" invoice / "2" corrective / "3" cancellation (char1), with "3" inferred when originalInvoiceId is set unless overrides.invoiceType is provided
Fri Mar 27 20265.0.2SD: POST /invoice now applies idempotency on selected SAP business fields (Id, AuthId, TransId, Invoicetype), reusing the same successful SAP response for duplicates
Thu Mar 26 20265.0.1SD: SAP ZbubiIf BankCard now receives `paymentTransaction.last4` as four characters (no asterisk padding)
Thu Mar 26 20265.0.0Breaking: POST /invoice removed top-level authIdOverride; use overrides.authId instead
SD: optional overrides object on POST /invoice with authId and invoiceType for SAP ZbubiIf (integration / negative testing)
Mon Mar 23 20264.0.0Breaking: NAV lookup endpoint moved from GET /company/info to GET /legal-entity/info
Breaking: NAV DTO/schema names renamed from NavGetCompanyInfo* to NavGetLegalEntityInfo*
Mon Mar 23 20263.0.0Breaking: POST /invoice now requires `user` in the request body
Breaking: POST /invoice request field `company` renamed to `legalEntity`
Sat Mar 21 20262.1.0SD: optional authIdOverride on POST /invoice body to override SAP AuthId
SD: salesOrderId in POST /invoice response extracts the numeric id when SAP EReturn is like "Sales order:0015537378"
Fri Mar 20 20262.0.0Breaking: paymentTransaction.id is number (1–9999999999), not string
Breaking: refundedTransactionExternalId removed; use refundedTransactionId (number, optional) for storno
Breaking: documentId and documentType removed (SAP Dummy1/Dummy2 no longer populated)
SD: Itemprice and Itemamount sent as whole-forint strings (minor HUF units ÷ 100, no .00 fraction)
Validation: last4 must be exactly 4 characters
SD: SAP Invoicetype uses numeric codes ("1" invoice, "2" corrective, "3" cancellation/storno)
Thu Mar 19 20261.2.0NAV taxpayer validation interface (GET /company/info)
Health check integration: SAP SOAP client readiness on /healthz
Version indicator: running commit SHA on /healthz
Wed Mar 18 20261.1.0Structured SD request DTOs with validation
SOAP connectivity: local WSDL files, TLS certificate handling
Internal auth guard
Fri Mar 13 20261.0.0SD invoicing interface (POST /invoice)
Basic SOAP-to-REST proxy for ZbubiWs
Prometheus metrics for SD requests

audience

sap-bubi-api

Sync Log

Query SAP BUBI outgoing request log (JSON, paginated)

Returns a paginated list of outgoing SOAP request rows ordered by dispatched_at DESC. Use filters to narrow by status, date range, invoice ID, document, or SAP field values.

query Parameters
dispatchedAtFrom
string

Filter dispatched_at >= this ISO timestamp

dispatchedAtTo
string

Filter dispatched_at <= this ISO timestamp

status
string
Enum: "TRANSMITTED" "SAP_REJECTED" "TRANSPORT_ERROR" "IDEMPOTENCY_REPLAY"

Filter by outcome status

invoiceId
string

Filter by SAP invoice ID

transId
string

Filter by SAP TRANS_ID

authId
string

Filter by SAP AUTH_ID

posCode
string

Filter by SAP POS_CODE

documentType
string (DocumentType)
Enum: "ORDER" "INVOICE"

Filter by document type

documentId
string

Filter by document ID

page
number
Default: 1

Page number (1-based)

limit
number
Default: 100

Page size

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 1042
}

Export SAP BUBI outgoing request log as BKK 3.0 CSV (streamed)

Streams all matching rows as a UTF-8 CSV in the BKK 3.0 column layout (39 columns, A–AM). Filter by status != TRANSMITTED to get the unsynchronised data view. Rows are ordered by dispatched_at ASC. Large result sets are batched internally.

query Parameters
dispatchedAtFrom
string

Filter dispatched_at >= this ISO timestamp

dispatchedAtTo
string

Filter dispatched_at <= this ISO timestamp

status
string
Enum: "TRANSMITTED" "SAP_REJECTED" "TRANSPORT_ERROR" "IDEMPOTENCY_REPLAY"

Filter by outcome status

invoiceId
string

Filter by SAP invoice ID

transId
string

Filter by SAP TRANS_ID

authId
string

Filter by SAP AUTH_ID

posCode
string

Filter by SAP POS_CODE

documentType
string (DocumentType)
Enum: "ORDER" "INVOICE"

Filter by document type

documentId
string

Filter by document ID

page
number
Default: 1

Page number (1-based)

limit
number
Default: 100

Page size

Responses

SAP

Create SAP SD invoice

Submits billing line items to the SAP SD SOAP endpoint. SAP creates an SD Order, generates an Invoice, reports to NAV, and books the invoice to the customer account.

Request Body schema: application/json
required
required
object

Common payment transaction data.

id
required
number

Internal Urbansharing ID of the payment transaction or refund (PaymentTransaction.id or PaymentRefund.id). Maps to SAP SOAP field: Id (ZbubiIf).

externalId
required
string <= 7 characters

External ID from the Urbansharing payment system. Corresponds to either PaymentTransaction.externalId or PaymentRefund.externalId. Maps to SAP SOAP field: TransId (ZbubiIf). AuthId uses the same value unless overrides.authId is set on the invoice request.

posCode
required
string <= 8 characters

POS terminal ID number in the BUBI system. Maps to SAP SOAP field: PosCode (ZbubiIf).

processedAt
required
string <date-time>

Timestamp when the transaction was processed in the Urbansharing system. Maps to SAP SOAP fields: ServDat (date part, YYYY-MM-DD) and Time (time part, HH:mm:ss) (ZbubiIf).

customerRef
required
string <= 16 characters

Customer reference in the Urbansharing payment system (corresponds to Customer entity). Maps to SAP SOAP field: UserId (ZbubiIf).

emailAddress
required
string <= 70 characters

Customer email address for e-invoice delivery. Maps to SAP SOAP field: EmailAddress (ZbubiIf).

last4
required
string = 4 characters

Last 4 digits of the payment card used in the Urbansharing transaction. Maps to SAP SOAP field: BankCard (ZbubiIf), sent as-is (four characters).

originalInvoiceId
string <= 10 characters

SAP invoice number of the document being reversed, exactly as returned in invoiceId from the successful POST /invoice response for the original posting (SAP INVOICETYPE "1" standard invoice). When set, the mapper sends this value in Originalinvoicenumber and derives INVOICETYPE from isFullyRefunded (see below) unless overrides.invoiceType is set. Maps to SAP SOAP field: Originalinvoicenumber (ZbubiIf), max 10 characters.

isFullyRefunded
boolean

Only when originalInvoiceId is set: false = partial refund (SAP INVOICETYPE "2"), true or omitted = full refund ("3"). If originalInvoiceId is omitted, this field is ignored.

documentType
string
Enum: "ORDER" "INVOICE"

Document type. Used for audit log only — not sent to SAP.

documentId
string

Document ID (e.g. order id). Used for audit log only — not sent to SAP.

required
Array of objects (SdItem)

Array of billing line items.

Array
productExternalSKU
required
string <= 4 characters

Product external SKU from the Urbansharing core database (corresponds to Product.externalSKU). Maps to SAP SOAP field: Matnr (ZbubiIf).

quantity
required
number

Quantity of purchased items. Maps to SAP SOAP field: Quant (ZbubiIf), converted to string.

itemPrice
required
number

Gross unit price in 1/100 of a Hungarian forint (Urbansharing minor HUF units). Maps to SAP SOAP field: Itemprice (ZbubiIf) as whole forints, e.g. 100000 -> "1000".

validFrom
string <date-time>

Beginning of validity period (date and time). Maps to SAP SOAP field: ValFrom (ZbubiIf), formatted as yyyyMMddHHmmss.

validTo
string <date-time>

End of validity period (date and time). Maps to SAP SOAP field: ValTo (ZbubiIf), formatted as yyyyMMddHHmmss.

object

Optional overrides for SAP ZbubiIf fields (e.g. Invoicetype). Intended for advanced scenarios and integration / negative testing.

authId
string <= 32 characters

Override for the SAP authorization / idempotency code. When omitted, AuthId is derived as paymentTransaction.externalId. Maps to SAP SOAP field: AuthId (ZbubiIf).

invoiceType
string <= 1 characters

Override for SAP Invoicetype (char1). Allowed production values are typically "1" (invoice), "2" (corrective / partial refund), "3" (full refund). Other values may be used to exercise SAP validation (e.g. negative tests). When omitted, type is derived from paymentTransaction (originalInvoiceId + isFullyRefunded when reversing). Maps to SAP SOAP field: Invoicetype (ZbubiIf).

required
object

Private individual customer data.

name
required
string <= 70 characters

Private individual's full name. Maps to SAP SOAP field: Name1 (ZbubiIf).

country
required
string <= 3 characters

Country code from SAP country master data. Maps to SAP SOAP field: Country (ZbubiIf).

postCode
required
string <= 10 characters

ZIP/postal code of the customer. Maps to SAP SOAP field: PostCode1 (ZbubiIf).

city
required
string <= 40 characters

City/place of the customer. Maps to SAP SOAP field: City1 (ZbubiIf).

street
required
string <= 60 characters

Street and house number of the customer. Maps to SAP SOAP field: Street (ZbubiIf).

object

Legal entity customer data.

taxNumber
required
string <= 13 characters

Legal entity tax number (format: XXXXXXXX-X-XX; corresponds to LegalEntity.taxNumber in the B2B module). Validated against the NAV database. Maps to SAP SOAP field: TaxNumber (ZbubiIf).

groupTaxNumber
string <= 13 characters

Legal entity group tax number (format: XXXXXXXX-X-XX; corresponds to LegalEntity.groupTaxNumber in the B2B module). Maps to SAP SOAP field: GroupTaxNumber (ZbubiIf).

name
required
string <= 70 characters

Legal entity name in the Urbansharing system (corresponds to LegalEntity.name in the B2B module). Maps to SAP SOAP field: LegalEntityBillingName (ZbubiIf).

country
required
string <= 3 characters

Legal entity country code (corresponds to LegalEntity.country in the B2B module). Maps to SAP SOAP field: LegalEntityBillingCountry (ZbubiIf).

zipCode
required
string <= 10 characters

Legal entity ZIP/postal code (corresponds to LegalEntity.zipCode in the B2B module). Maps to SAP SOAP field: LegalEntityBillingZip (ZbubiIf).

city
required
string <= 40 characters

Legal entity city (corresponds to LegalEntity.city in the B2B module). Maps to SAP SOAP field: LegalEntityBillingCity (ZbubiIf).

address
required
string <= 60 characters

Legal entity address (corresponds to LegalEntity.address in the B2B module). Maps to SAP SOAP field: LegalEntityBillingAddress (ZbubiIf).

Responses

Request samples

Content type
application/json
{
  • "paymentTransaction": {
    },
  • "items": [
    ],
  • "overrides": {
    },
  • "user": {
    },
  • "legalEntity": {
    }
}

Response samples

Content type
application/json
{
  • "salesOrderId": "0015537378",
  • "invoiceId": "9215538727",
  • "errorType": "SAP_REJECTED",
  • "errorMessage": "Duplicate invoice number"
}

Get legal entity info from NAV

Validates a Hungarian tax number against the NAV database and returns the official registered legal entity name, address, and group tax number.

query Parameters
taxNumber
required
string = 8 characters
Example: taxNumber=11961552

8-digit Hungarian taxpayer ID to validate against the NAV database.

Responses

Response samples

Content type
application/json
{
  • "valid": true,
  • "taxpayerName": "Peek & Cloppenburg Kft",
  • "taxNumber": "11961552-2-42",
  • "groupTaxNumber": "17782672-5-44",
  • "addresses": [
    ]
}