Vertex e-Invoicing Integration Services
master
by sanjeevgiri

Vertex e-Invoicing Integration Services

Documentation
Vertex e-Invoicing Integration Services API Reference

Overview

Vertex e-Invoicing API Integration Services currently provides following functionalities:

  • Allows client applications to register vertex customer einvoicing client credentials
  • Allow client applications to register callback urls and authentication schemes for supported e-invoice events
  • Sends notification to callback URLs with VrBL payloads (including attachements) when relevant e-invoice events are detected

API Access

  • In the near term the API must be accessible to Vertex managed applications (thin connectors) with OAuth2 authorization bearer token with audience verx://integration-platform-services and scope of ips-vertex (Vertex managed thin connectors that leverage ips capabilities).
  • It may be possible to allow customer managed single tenant applications to access these APIs. In that case, we would need to make a call to Vertex IAM /clientprofile endpoint to limit the scope of data to the context tenant.

Client Types (Machine 2 Machine Credential Types)

  • Tenant Specific e-invoicing API Credential: These M2M credentials represent Vertex customer/tenant specific keys with following scopes: vcd-platform-api, einvoicing-customer-api
  • Multitenant Thin Connector Application: These M2M credentials reporesent thin connectors that leverage IPS/CCS capabilities and have following scopes: ips-vertex
  • Singletenant Thin Connector Application: These M2M credentials represent Vertex customer/tenant provisioned keys using the credential managed page in the chrome app. (For initial version of this API, these types of applications are out of scope)

Versioning

  • Current Version: 0.0.1
  • This API will be versioned using semantic versioning and will maintain backward compatibility among patch and minor versions for the given major version.

API Implied Defaults

  • String property size: Any model string property with undefined size will be interpreted as 255 in length
  • Page size: For responses that require pagination, the default page size will be 10
  • Page sort property: For responses that require pagination, the default sort property will be internally managed sort order based on creation date
  • Page sort order: For response that require pagination ,the default sort order will be ascending.

Supported e-invoice event types

Refer to EventTypes for supported event types

Event Types and Callback Payloads

Notes & Questions

References

Models
EventTypeSubscription

Event subscriptions

Object
eventType
EventType required

Subscription event type.

callbackUrl
string uri required

Callback URL for event notification. (The default authorization context will include tenant specific bearer token)

Example:
https://ubleinv-dev.platdev.vtxdev.net/connector-ubleinv/api/v1/tenants/66bac982-b644-4d75-8d62-d5e70dd9b040/buyers/einvoices?env=prod
EventType

E-Invoicing event type

string
Enumeration:
EINVOICE_RECEIVED

Buyer e-invoice received

EINVOICE_DELIVERED

Seller e-invoice delivered. Buyers can deliver invoices for self-billed invoices.

EINVOICE_DELIVERY_FAILED_WITH_PROCESSING_ISSUE

Seller e-invoice delivery failed with processing issue in vertex einvoicing delivery pipeline

EINVOICE_DELIVERY_FAILED_WITH_ERROR

Seller e-invoice delivery failed with error in e-invoice network access point

Example:
EINVOICE_RECEIVED
CallbackAuthScheme

Callback authentication scheme

string
Enumeration:
BASIC_AUTH

Basic Authentiation

OAUTH2

Use client application’s OAuth2 M2M bearer tokens during notifications on callback endpoint

API_KEY

Use client application managed API Key based authentication

NONE

No authentication scheme used

VERTEX_EINV_OAUTH2

Use e-invoicing tenant specific bearer token for notifications to callback endpoints

Default:
API_KEY
Example:
API_KEY
TenantId

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

string
Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497
EinvoiceApiClient

E-Invoice API Client

Object
clientId
string required

Vertex e-invoicing API tenant specific client id

Example:
0oa2hl2inow5Uqc6c357
clientSecret
string required

Vertex e-invoicing API tenant specific client secret

Example:
dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw==
BaseObject

Basic properties of a stateful resource

Object
id
string uuid read-only

Internal resource identifier

Example:
acde070d-8c4c-4f0d-9d8a-162843c10333
clientAppId
string

Client applicaton id. This is the M2M client id of the client application.

Example:
ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q
CallbackSecurityScheme

Security scheme used for push notifications on callback endpoints. This follows similar structure defined in Open API 3.1.1 Security Scheme Object, however includes additional attributes for communicating to callback endpoints.

Object
type
CallbackSecuritySchemeType required

Security scheme type. Valid values are http, oauth2, and apiKey

Example:
oauth2
description
string nullable

A description for security scheme. CommonMark syntax MAY be used for rich text representation.

name
string

Conditioinally required for apkKey based security scheme. The name of the header, query or cookie parameter to be used.

Example:
x-api-key
in
CallbackApiKeySecuritySchemeContainer

Conditioinally required for apkKey based security scheme.

Example:
header
key
string

Conditioinally required for apkKey based security scheme. This is the API key value that will be included during callback push notifications.

Example:
key-f2a1ed52710d4533bde25be6da03b6e3
scheme
string

Conditioinally required for http based security scheme. Currently basic auth is supported

Enumeration:
basic

Unlike Open API 3 which supports basic, digest, bearer, we only support basic at this time.

username
string

Conditioinally required for http basic auth security scheme.

Example:
john-doe
pasword
string

Conditioinally required for http basic auth security scheme.

Example:
super-secret-password
flows
CallbackOauth2Flow

Conditioinally required for oauth2 based security scheme. Since the event recipients are application, client credentials flow is the only supported flow within the the context of webhook based notification system.

CallbackSecuritySchemeType

Following is a list of supported security scheme types for callback notifications:

  • Http Basic Authentication
  • API Key
  • OAuth2 M2M Client credentials flow

Differences from Open API Security Scheme Types

  • Mutual TLS is not yet supported
  • OAuth2 implicit, password, and authorization code flows are not supported since callback endpoints are only relevant to machines.
  • OpenId Connect scheme is not yet supported
  • Open ID Connect is not yet supported
  • Ony Basic auth HTTP scheme is supported. Digest and Bearer schemes are not supported.

References:

string
Enumeration:
http

Http basic is the only supported scheme. (Digest and bearer are not yet supported)

apiKey

API Key based security scheme

oauth2

M2M Client credentials flow is the only supported flows since our clients are machine applications.

CallbackApiKeySecuritySchemeContainer
string
Enumeration:
query

API Key lookup in query string

header

API Key lookup in header

cookie

API Key lookup in cookie

CallbackOauth2Flow

The only support flow type is the client credentials flow since the notification targed endpoints are applications and not human users.

Object
clientCredentials
Object

Client credential flow

tokenUrl
string required

Token url

Example:
https://token-guard-caching-dev.platdev.vtxdev.net/cached/oauth/token
scopes
string nullable

The available scopes for the OAuth2 security scheme.

audience
string required

That target endpoint API identifier

Example:
verx://migration-api
clientId
string required

Client id

Example:
6779ef20e75817b79602
clientSecret
string required

Client secret

Example:
0oa2hl2inow5Uqc6c357
Headers
OAuth2
Authorization
string required
Applied to all operations

OAuth2 bearer token (JSON Web Token) obtained by exchanging client application M2M credentials from the predefined Vertex cloud idP.

Example:
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Parameters
Pagination
page
integer optional

Page number (starts from 0)

Default:
0
size
integer optional

Page size that determines the number of elements in a given page

Default:
10
Operations
E-invoice API Clients
Create e-Invoicing Client
POST /tenants/{tenantId}/einvapiclients
Update e-Invoicing Client
PUT /tenants/{tenantId}/einvapiclients/{id}
Delete e-Invoicing Client
DELETE /tenants/{tenantid}/einvapiclients/{id}
List e-Invoicing Client
GET /tenants/{tenantId}/einvapiclients
Create e-Invoicing Client
POST /tenants/{tenantId}/einvapiclients

Authentication

OAuth2

Idempotently stores tenant specific einvoicing API client credentials. (idempotency key - jwt.subject/clientAppId, tenantId)

Following actions are required for this operations:

  • Check if vertex cloud tenant has an entitlement registry for “einv-integration-services”
  • If not, create an entitlement for {tenantId} in IPS for “einv-integration-services”
  • Once the entilement is created, store the tenant client credentials along with requesting application client id as a list item (IPS supports storage of lists, objects, and maps keyed with entitlementId)
  • If an entitlment exists, but the tenant einvoice client id, and requesting API client id is not found, then we add to list and save
  • If an entitlement exists, and tenant einvoice client id, and requesting API client id is found, then we return that value

Path variables

tenantId
TenantId required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497

Request body

EinvoiceApiClient
Examples

Responses

201 Created
Body
All of
EinvoiceApiClient
BaseObject
Example 1
POST https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/einvapiclients HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "clientId": "0oa2hl2inow5Uqc6c357",
    "clientSecret": "dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw=="
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "clientId": "0oa2hl2inow5Uqc6c357",
    "clientSecret": "dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw==",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more
Update e-Invoicing Client
PUT /tenants/{tenantId}/einvapiclients/{id}

Authentication

OAuth2

Update existing e-invoicing client credential

Path variables

tenantId
TenantId required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497
id
string required

Internal resource identifier

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497

Request body

EinvoiceApiClient
Examples

Responses

200 OK
Body
All of
EinvoiceApiClient
BaseObject
Example 1
PUT https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/einvapiclients/a58b4abb-49e2-43c2-bf70-a56f9cddd497 HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "clientId": "0oa2hl2inow5Uqc6c357",
    "clientSecret": "dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw=="
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "clientId": "0oa2hl2inow5Uqc6c357",
    "clientSecret": "dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw==",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more
Delete e-Invoicing Client
DELETE /tenants/{tenantid}/einvapiclients/{id}

Authentication

OAuth2

Path variables

tenantid
TenantId required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497
id
string required

Internal resource identifier

Example:
acde070d-8c4c-4f0d-9d8a-162843c10333

Responses

204 No Content

Client credentials are successfully removed

Example 1
DELETE https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/einvapiclients/acde070d-8c4c-4f0d-9d8a-162843c10333 HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 204 No Content
List e-Invoicing Client
GET /tenants/{tenantId}/einvapiclients

Authentication

OAuth2

List e-invlicing client applications. This will be a either an empty list or a list of one element. This is convinient in that it does not require the client applicaiton to provide the internal resource identifier.

Path variables

tenantId
TenantId required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497

Request body

EinvoiceApiClient
Examples

Responses

200 OK
Body
Array
All of
EinvoiceApiClient
BaseObject
Example 1
POST https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/einvapiclients HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "clientId": "0oa2hl2inow5Uqc6c357",
    "clientSecret": "dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw=="
}

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "clientId": "0oa2hl2inow5Uqc6c357",
        "clientSecret": "dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw==",
        "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
        "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
    }
]
show more
Event Type Webhook Subscriptions
Create Event Type Webhook Subscription
POST /tenants/{tenantId}/webhookeventtypes
Update Event Type Webhook Subscription
PUT /tenants/{tenantId}/webhookeventtypes/{id}
Delete Event Type Webhook Subscription
DELETE /tenants/{tenantId}/webhookeventtypes/{id}
Get Event Type Webhook Subscription
GET /tenants/{tenantId}/webhookeventtypes/{id}
List Event Type Webhook Subscriptions
GET /tenants/{tenantId}/webhookeventtypes
Create Event Type Webhook Subscription
POST /tenants/{tenantId}/webhookeventtypes

Authentication

OAuth2

Idempotently store subscription for a predefined event type (Implicit idempotency key - jwt.subject/client app, tenantId, eventType)

Path variables

tenantId
string required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497

Request body

EventTypeSubscription
Examples

Responses

201 Created
Body
All of
EventTypeSubscription
BaseObject
Example 1
POST https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/webhookeventtypes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "eventType": "EINVOICE_RECEIVED",
    "callbackUrl": "https://ubleinv-dev.platdev.vtxdev.net/connector-ubleinv/api/v1/tenants/66bac982-b644-4d75-8d62-d5e70dd9b040/buyers/einvoices"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "eventType": "EINVOICE_RECEIVED",
    "callbackUrl": "https://ubleinv-dev.platdev.vtxdev.net/connector-ubleinv/api/v1/tenants/66bac982-b644-4d75-8d62-d5e70dd9b040/buyers/einvoices",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more
Update Event Type Webhook Subscription
PUT /tenants/{tenantId}/webhookeventtypes/{id}

Authentication

OAuth2

Update subscription for a predefined event type

Path variables

tenantId
string required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497
id
string required

Internal resource identifier

Example:
acde070d-8c4c-4f0d-9d8a-162843c10333

Request body

EventTypeSubscription
Examples

Responses

200 OK
Body
All of
EventTypeSubscription
BaseObject
Example 1
PUT https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/webhookeventtypes/acde070d-8c4c-4f0d-9d8a-162843c10333 HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "eventType": "EINVOICE_RECEIVED",
    "callbackUrl": "https://ubleinv-dev.platdev.vtxdev.net/connector-ubleinv/api/v1/tenants/66bac982-b644-4d75-8d62-d5e70dd9b040/buyers/einvoices?env=prod"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "eventType": "EINVOICE_RECEIVED",
    "callbackUrl": "https://ubleinv-dev.platdev.vtxdev.net/connector-ubleinv/api/v1/tenants/66bac982-b644-4d75-8d62-d5e70dd9b040/buyers/einvoices?env=prod",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more
Delete Event Type Webhook Subscription
DELETE /tenants/{tenantId}/webhookeventtypes/{id}

Authentication

OAuth2

Delete subscription for a predefined event type

Path variables

tenantId
string required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497
id
string required

Internal resource identifier

Example:
acde070d-8c4c-4f0d-9d8a-162843c10333

Responses

204 No Content
Example 1
DELETE https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/webhookeventtypes/acde070d-8c4c-4f0d-9d8a-162843c10333 HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 204 No Content
Get Event Type Webhook Subscription
GET /tenants/{tenantId}/webhookeventtypes/{id}

Authentication

OAuth2

Get subscription for a predefined event type

Path variables

tenantId
string required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497
id
string required

Internal resource identifier

Example:
acde070d-8c4c-4f0d-9d8a-162843c10333

Responses

200 OK
Body
All of
EventTypeSubscription
BaseObject
Example 1
GET https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/webhookeventtypes/acde070d-8c4c-4f0d-9d8a-162843c10333 HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "eventType": "EINVOICE_RECEIVED",
    "callbackUrl": "https://ubleinv-dev.platdev.vtxdev.net/connector-ubleinv/api/v1/tenants/66bac982-b644-4d75-8d62-d5e70dd9b040/buyers/einvoices?env=prod",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more
List Event Type Webhook Subscriptions
GET /tenants/{tenantId}/webhookeventtypes

Authentication

OAuth2

Get subscription for a predefined event type

Path variables

tenantId
string required

Vertex Cloud internal identifier for Vertex Customer. This will be the tenant.id field of the https://devapi.vertexsmb.com/site/platformintegration/clientprofile or https://devapi.vertexsmb.com/site/platformintegration/profile reponses

Example:
a58b4abb-49e2-43c2-bf70-a56f9cddd497

Request parameters

eventType
EventType optional

Event type

Example:
EINVOICE_RECEIVED

Responses

200 OK
Body
Array
All of
EventTypeSubscription
BaseObject
Example 1
GET https://einv-integration-services/api/v1/tenants/a58b4abb-49e2-43c2-bf70-a56f9cddd497/webhookeventtypes?eventType=BUYER_EINVOICE_RECEIVED HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "eventType": "EINVOICE_RECEIVED",
        "callbackUrl": "https://ubleinv-dev.platdev.vtxdev.net/connector-ubleinv/api/v1/tenants/66bac982-b644-4d75-8d62-d5e70dd9b040/buyers/einvoices?env=prod",
        "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
        "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
    }
]
show more
Callback Security Scheme
Create Callback Security Scheme
POST /callbacks/securityschemes
Update Callback Security Scheme
PUT /callbacks/securityschemes
Delete Callback Security Scheme
DELETE /callbacks/securityschemes/{id}
List Callback Security Schemes
GET /callbacks/securityschemes
Create Callback Security Scheme
POST /callbacks/securityschemes

Authentication

OAuth2

Idempotently create callback security schemes for client application represented in the bearer token’s jwt.subject. Client application id, and is the logical key in this case.

Depending on the type of authentication scheme choosen, the body must include relevant credential information.

Request body

All of
CallbackSecurityScheme
Examples

Responses

201 Created
Body
All of
CallbackSecurityScheme
BaseObject
Example 1
Example 2
Example 3

API Key Security Scheme

POST https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "type": "apiKey",
    "description": "API Key for Oracle e-Invoicing Connector",
    "name": "x-api-key",
    "in": "query",
    "key": "key-f2a1ed52710d4533bde25be6da03b6e3"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "type": "apiKey",
    "description": "API Key for Oracle e-Invoicing Connector",
    "name": "x-api-key",
    "in": "query",
    "key": "key-f2a1ed52710d4533bde25be6da03b6e3",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more

Basic Auth Security Scheme

POST https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "type": "http",
    "description": "Basic Auth Security Scheme for Oracle e-Invoicing Connector",
    "scheme": "basic",
    "username": "john-doe",
    "pasword": "super-secret-password"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "type": "http",
    "description": "Basic Auth Security Scheme for Oracle e-Invoicing Connector",
    "scheme": "basic",
    "username": "john-doe",
    "pasword": "super-secret-password",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more

OAuth2 Security Scheme

POST https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "type": "oauth2",
    "description": "OAuth2 Security Scheme for Oracle ERP e-Invoicing Connector",
    "flows": {
        "clientCredentials": {
            "tokenUrl": "https://token-guard-caching-dev.platdev.vtxdev.net/cached/oauth/token",
            "scopes": "ips-vertex",
            "audience": "verx://migration-api",
            "clientId": "6779ef20e75817b79602",
            "clientSecret": "0oa2hl2inow5Uqc6c357"
        }
    }
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "type": "oauth2",
    "description": "OAuth2 Security Scheme for Oracle ERP e-Invoicing Connector",
    "flows": {
        "clientCredentials": {
            "tokenUrl": "https://token-guard-caching-dev.platdev.vtxdev.net/cached/oauth/token",
            "scopes": {"ips-vertex": "abc"},
            "audience": "verx://migration-api",
            "clientId": "6779ef20e75817b79602",
            "clientSecret": "0oa2hl2inow5Uqc6c357"
        }
    },
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more
Update Callback Security Scheme
PUT /callbacks/securityschemes

Authentication

OAuth2

Idempotently create callback security schemes for client application represented in the bearer token’s jwt.subject. Client application id, and is the logical key in this case.

Depending on the type of authentication scheme choosen, the body must include relevant credential information.

Request body

All of
CallbackSecurityScheme
Examples

Responses

200 OK
Body
All of
CallbackSecurityScheme
BaseObject
Example 1
Example 2
Example 3

API Key Security Scheme

POST https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "type": "apiKey",
    "description": "API Key for Oracle e-Invoicing Connector",
    "name": "x-api-key",
    "in": "query",
    "key": "key-f2a1ed52710d4533bde25be6da03b6e3"
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "type": "apiKey",
    "description": "API Key for Oracle e-Invoicing Connector",
    "name": "x-api-key",
    "in": "query",
    "key": "key-f2a1ed52710d4533bde25be6da03b6e3",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more

Basic Auth Security Scheme

POST https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "type": "http",
    "description": "Basic Auth Security Scheme for Oracle e-Invoicing Connector",
    "scheme": "basic",
    "username": "john-doe",
    "pasword": "super-secret-password"
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "type": "http",
    "description": "Basic Auth Security Scheme for Oracle e-Invoicing Connector",
    "scheme": "basic",
    "username": "john-doe",
    "pasword": "super-secret-password",
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more

OAuth2 Security Scheme

POST https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "type": "oauth2",
    "description": "OAuth2 Security Scheme for Oracle ERP e-Invoicing Connector",
    "flows": {
        "clientCredentials": {
            "tokenUrl": "https://token-guard-caching-dev.platdev.vtxdev.net/cached/oauth/token",
            "scopes": "profile email",
            "audience": "verx://migration-api",
            "clientId": "6779ef20e75817b79602",
            "clientSecret": "0oa2hl2inow5Uqc6c357"
        }
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "type": "oauth2",
    "description": "OAuth2 Security Scheme for Oracle ERP e-Invoicing Connector",
    "flows": {
        "clientCredentials": {
            "tokenUrl": "https://token-guard-caching-dev.platdev.vtxdev.net/cached/oauth/token",
            "scopes": "ips-vertex",
            "audience": "verx://migration-api",
            "clientId": "6779ef20e75817b79602",
            "clientSecret": "0oa2hl2inow5Uqc6c357"
        }
    },
    "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
    "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
}
show more
Delete Callback Security Scheme
DELETE /callbacks/securityschemes/{id}

Authentication

OAuth2

Delete client application callback auth.

Path variables

id
string required

Resource identifier

Example:
acde070d-8c4c-4f0d-9d8a-162843c10333

Responses

204 No Content
Example 1
DELETE https://einv-integration-services/api/v1/callbacks/securityschemes/acde070d-8c4c-4f0d-9d8a-162843c10333 HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 204 No Content
List Callback Security Schemes
GET /callbacks/securityschemes

Authentication

OAuth2

List of 0 or 1 element that represents the callback authentication information.

Responses

200 OK
Body
Array
All of
CallbackSecurityScheme
BaseObject
Example 1
Example 2
Example 3

API Key Security Scheme

GET https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "type": "apiKey",
        "description": "API Key Security Scheme",
        "name": "x-api-key",
        "in": "header",
        "key": "key-f2a1ed52710d4533bde25be6da03b6e3",
        "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
        "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
    }
]
show more

Basic Auth Security Scheme

GET https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "type": "http",
        "description": "Http Basic Auth Security Scheme",
        "scheme": "basic",
        "username": "john-doe",
        "pasword": "super-secret-password",
        "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
        "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
    }
]
show more

OAuth2 Security Scheme

GET https://einv-integration-services/api/v1/callbacks/securityschemes HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "type": "http",
        "description": "OAuth2 Security Scheme",
        "flows": {
            "clientCredentials": {
                "tokenUrl": "https://token-guard-caching-dev.platdev.vtxdev.net/cached/oauth/token",
                "scopes": "tenants::*::resources::einvoice::actions::read",
                "audience": "verx://migration-api",
                "clientId": "6779ef20e75817b79602",
                "clientSecret": "0oa2hl2inow5Uqc6c357"
            }
        },
        "id": "acde070d-8c4c-4f0d-9d8a-162843c10333",
        "clientAppId": "ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q"
    }
]
show more