Search

Page tree
Skip to end of metadata
Go to start of metadata

This page include references to libraries used by the integration framework and examples 

Libraries


OpenAPI-Specification

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. 

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md

JUST

JUST Stands for JSON Under Simple Transformation

A library in .NET which enables the transformation of JSON documents using very a simple transformation language. 

https://github.com/WorkMaze/JUST.net


Extension of OpenAPI


In order to accomplish system data synchronization from BSS we extend the specification with a new elements

Example of a new element
"Invoice": {
      "description": "Synchronize Invoices with 3rd party system",
      "module": "Invoices",
      "push": {
        "create": "/SalesInvoice/post",
        "update": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/put",
        "preSynchronizationAction": {
          "ETag": {
            "type": "ApiPath",
            "path": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/get",
            "schema": {
              "type": "String",
              "ETag": "ETag"
            },
            "in": "Body"
          },
          "HeaderETag": {
            "type": "ApiPath",
            "path": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/get",
            "schema": {
              "type": "String",
              "header": "If-Match",
              "headerValue": "@odata.etag"
            },
            "in": "Header"
          }
        },
        "postSynchronizationAction": {
          "InvoiceItems": {
            "type": "ApiSynchronization",
            "path": "InvoiceItems",
            "schema": {
              "type": "String",
              "ETag": "ETag"
            },
            "in": "Body"
          }
        },
        "schemasTransformer": {
                  	   "Document_Type": "Invoice",
                       "Sell_to_Customer_Name": "#valueof($.invoice.account.name)",
                       "Sell_to_Address": "#valueof($.invoice.account.addresses[?(@.isBilling==true)].address1)",
                       "Sell_to_Address_2": "#valueof($.invoice.account.addresses[?(@.isBilling==true)].address2)",
                       "Sell_to_Post_Code": "#valueof($.invoice.account.addresses[?(@.isBilling==true)].postCode)",
                       "Sell_to_City": "#valueof($.invoice.account.addresses[?(@.isBilling==true)].city)",
                       "Document_Date": "#valueof($.invoice.createdAt)",
                       "Due_Date": "#valueof($.invoice.dueDate)",
                       "Currency_Code": "#valueof($.invoice.billingAccount.accountCurrency.currency.mnemonic)"
			}
      }
    }


Transformation



Transformation example
{
	"Name": "#valueof($.Name)", 
    "AccountNumber": "#valueof($.Code)"
}

The tranformation is in JSON format & should be set as a JSON string to the schemasTransformer element


A JSON Instance Exmple



Json Instance Example
{
  "openapi": "3.0.0",
  "info": {
    "title": "Quickbooks integration",
    "contact": {
      "name": "Thomas Zisopoulos"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://sandbox-quickbooks.api.intuit.com/v3/company/193514681960574",
      "description": "Sandbox",
      "variables": {
        "Vendor_ID": {
          "default": "196",
          "description": "Vendor account ID on QB"
        },
        "Vendor_Name": {
          "default": "Interworks Cloud",
          "description": "Vendor account name on QB"
        }
      }
    }
  ],
  "paths": {
    "/customer": {
      "post": {
        "description": "Creates a new account in the system.",
        "requestBody": {
          "description": "Account to add to the system",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/account"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/newRecord"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "account": {
        "type": "object",
        "required": [
          "GivenName"
        ],
        "properties": {
          "Id": {
            "type": "string"
          },
          "SyncToken": {
            "type": "string"
          },
          "MetaData": {
            "type": "object"
          },
          "GivenName": {
            "type": "string"
          },
          "DisplayName": {
            "type": "string"
          },
          "PrimaryPhone": {
            "type": "object"
          },
          "Fax": {
            "type": "object"
          },
          "PrimaryEmailAddr": {
            "type": "object"
          },
          "WebAddr": {
            "type": "object"
          },
          "Taxable": {
            "type": "boolean"
          },
          "TaxExemptionReasonId": {
            "type": "string"
          },
          "BillAddr": {
            "type": "object"
          },
          "CurrencyRef": {
            "type": "object"
          },
          "Sparse": {
            "type": "boolean"
          }
        }
      },
      "newRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "success": {
            "type": "boolean"
          }
        }
      }
    },
    "securitySchemes": {
      "oauth2_auth": {
        "type": "oauth2",
        "description": "OAuth2 Authentication",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://appcenter.intuit.com/connect/oauth2",
            "tokenUrl": "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer ",
            "scopes": {
              "com.intuit.quickbooks.accounting": "QuickBooks Online API",
              "com.intuit.quickbooks.payment": "QuickBooks Payments API"
            }
          }
        }
      }
    }
  },
  "synchronization": {
    "Accounts": {
      "description": "Accounts",
      "module": "Accounts",
      "push": {
        "create": "/customer/post",
        "update": "/customer/post",
        "preSynchronizationAction": {
          "SyncToken": {
            "type": "ApiPath",
            "path": "/customer/{Account.IntegrationId}/get",
            "schema": {
              "type": "String",
              "SyncToken": "Customer.SyncToken"
            },
            "in": "Body"
          }
        },
        "schemasTransformer": {
          "accountRequest": "{\"GivenName\":\"#valueof($.account.name)\",\"PrimaryPhone\":{\"FreeFormNumber\":\"#valueof($.account.phone)\"},\"Fax\":{\"FreeFormNumber\":\"#valueof($.account.fax)\"},\"PrimaryEmailAddr\":{\"Address\":\"#valueof($.account.corpEmail)\"},\"WebAddr\":{\"URI\":\"#valueof($.account.webSite)\"},\"BillAddr\":{\"Line1\":\"#valueof($.account.addresses[?(@.isBilling==true)].address1)\",\"Line2\":\"#valueof($.account.addresses[?(@.isBilling==true)].address2)\",\"City\":\"#valueof($.account.addresses[?(@.isBilling==true)].city)\",\"Country\":\"#valueof($.account.addresses[?(@.isBilling==true)].countryName)\",\"PostalCode\":\"#valueof($.account.addresses[?(@.isBilling==true)].postCode)\",\"CountrySubDivisionCode\":\"#valueof($.account.addresses[?(@.isBilling==true)].region)\"},\"Taxable\":\"#valueof($.account.isTaxable)\",\"TaxExemptionReasonId\":\"#valueof($.serverVariables.tax_Exception_Reason)\",\"CurrencyRef\":{\"value\":\"#ifcondition(#valueof($.account.accountCurrency),NULL,,#valueof($.account.accountCurrency.currency.mnemonic))\",\"name\":\"#ifcondition(#valueof($.account.accountCurrency),NULL,,#valueof($.account.accountCurrency.currency.name))\"},\"MetaData\":{\"CreateTime\":\"#valueof($.account.createdAt)\",\"LastUpdatedTime\":\"#valueof($.account.updatedAt)\"}}",
          "accountUpdateRequest": "{\"SyncToken\":\"#valueof($.syncToken)\",\"Id\":\"#valueof($.externalId)\",\"GivenName\":\"#valueof($.account.name)\",\"PrimaryPhone\":{\"FreeFormNumber\":\"#valueof($.account.phone)\"},\"Fax\":{\"FreeFormNumber\":\"#valueof($.account.fax)\"},\"PrimaryEmailAddr\":{\"Address\":\"#valueof($.account.corpEmail)\"},\"WebAddr\":{\"URI\":\"#valueof($.account.webSite)\"},\"BillAddr\":{\"Line1\":\"#valueof($.account.addresses[?(@.isBilling==true)].address1)\",\"Line2\":\"#valueof($.account.addresses[?(@.isBilling==true)].address2)\",\"City\":\"#valueof($.account.addresses[?(@.isBilling==true)].city)\",\"Country\":\"#valueof($.account.addresses[?(@.isBilling==true)].countryName)\",\"PostalCode\":\"#valueof($.account.addresses[?(@.isBilling==true)].postCode)\",\"CountrySubDivisionCode\":\"#valueof($.account.addresses[?(@.isBilling==true)].region)\"},\"Taxable\":\"#valueof($.account.isTaxable)\",\"TaxExemptionReasonId\":\"#valueof($.serverVariables.tax_Exception_Reason)\",\"CurrencyRef\":{\"value\":\"#ifcondition(#valueof($.account.accountCurrency),NULL,,#valueof($.account.accountCurrency.currency.mnemonic))\",\"name\":\"#ifcondition(#valueof($.account.accountCurrency),NULL,,#valueof($.account.accountCurrency.currency.name))\"},\"MetaData\":{\"CreateTime\":\"#valueof($.account.createdAt)\",\"LastUpdatedTime\":\"#valueof($.account.updatedAt)\"},\"sparse\":true}",
          "newRecordResponse": "{\"id\":\"#valueof($.Customer.Id)\"}"
        }
      }
    }
  },
  "security": [
    {
      "oauth2_auth": [
        "com.intuit.quickbooks.accounting",
        "com.intuit.quickbooks.payment"
      ]
    }
  ]
}



  • No labels