TABLE OF CONTENTS

• Accredo API: Documentation
• Useful API Endpoints
• Accredo API: General Usage Notes:
  • Creating new Records via API:
  • Updating existing Records via API:
• Accredo API: Examples
  • Authentication Examples:
  • ARCustomer Examples:
  • INInvoice Examples

Accredo API: Documentation

Accredo has published an OpenAPI specification, available here:

https://api.accredo.co.nz/documentation/openapi.json

To view the OpenAPI.Json file in a readable format you, copy-paste the OpenAPI.Json content into: https://editor.swagger.io/

Note that this will take perhaps a minute or so to process, it's a large file.

If processing is successful, you'll see a much more developer-friendly specification of all the Accredo API endpoints & payloads. Example below.

Useful API Endpoints

• Developer Documentation:
  • https://api.your_website.co.nz:6569/{mercury_or_saturn} /odata4/v1/company('COMPANY_CODE')/developerdoc
• Open API Documentation:
  • https://api.your_website.co.nz:6569/{mercury_or_saturn}/odata4/v1/Company('COMPANY_CODE')/openapi.json 
• API Model Documentation:
  • https://api.your_website.co.nz:6569/{mercury_or_saturn}/odata4/v1/company('COMPANY_CODE')/$metadata/Types('INInvoice')$format=json
• Get Period For Date:
  • https://api.your_website.co.nz:6569/{mercury_or_saturn} /odata4/v1/Company('COMPANY_CODE')/PeriodForDate(Date=2021-05-01) 
  • (Some Accredo Models require a PeriodID to be provided, typically when you attempt to create a Document with a back-dated or future-dated Document with a Date outside of the current Period-range)

Accredo API: General Usage Notes:

• Creating new Records via API:

  • Use HTTP POST methods for the appropriate API Endpoint

• Updating existing Records via API:

  • Both PUT & PATCH methods require an additional eTag in the HTTP header payload.
    This eTag is enforced by the Accredo API and forces the API invoker to specify which record-version to update.
  • Use HTTP PATCH methods to update specific fields within an existing Record
  • Use the HTTP PUT method to completely replace an existing Record (this will cause data destruction and should only be used when explicit overwrites are required)
  • If the eTag is not specified, or if the eTag does not match the current API value for the record being updated, the HTTP PUT / HTTP POST API request will be rejected by the Accredo WebServices:
    

Accredo API: Examples

• Authentication Examples:

  • Authentication with Accredo WebServices using OAuth2.0 Password Grant type: 

    • Uses the simplest OAuth2 grant type (Password), and only involves one step: The application presents a traditional Username & Password in a POST to the WebServices API to exchange the password for an Access_Token.
    • Note: Each Access_Token lasts for a server-side configurable time-span (default is 60 minutes), and consumes an Accredo User-License for this duration.
    • Best practice is to DELETE the Access_Token after your API work is completed, this frees up the Accredo User-Licence that's being consumed by the Access_Token, so that the Access_Token is available to be granted to the next Authentication Request.
    • Obtaining an Access_Token:
      • Endpoint: https://api.your_website.com:your_port/accredo_type/oauth2/v1/token(HTTP POST)
        • Accredo Mercury:
          https://api.your_website.com:your_port/mercury/oauth2/v1/token
        • Accredo Saturn:
          https://api.your_website.com:your_port/saturn/oauth2/v1/token 
      • HTTP POST Body: 
        1. {
               "grant_type":"password",
               "client_id":"(PENDING CREATION)",
               "username":"(PENDING CREATION)",
               "password":"(PENDING CREATION)"
           }
        2. 
           
    • Deleting an Access_Token:
      • Endpoint: https://api.your_website.com:your_port/accredo_type/oauth2/v1/accesstokens/your_access_token (HTTP DELETE)
        • Accredo Mercury:
          https://api.your_website.com:your_port/mercury/oauth2/v1/accesstokens/your_access_token 
        • Accredo Saturn:
          https://api.your_website.com:your_port/saturn/oauth2/v1/accesstokens/your_access_token  
    •  Renewing Access_Tokens:
      • You can use the Refresh_Token to request a new Access_Token before the Refresh-Token expires, or you can request a new Access_Token using the same Password Grant steps above.
      • Endpoint: https://api.your_website.com:your_port/accredo_type/oauth2/v1/token(HTTP POST)
      • HTTP POST Body:
        {
            "grant_type":"refresh_token",
            "client_id":"(PENDING CREATION)",
            "refresh_token":"{refresh_token}"
        }

    1. Explore the ODATA and ENDPOINTS that Accredo WebServices provides:
       • https://api.your_website.com:your_port/accredo_type/odata4/v1/company('COMPANY_CODE_HERE')/developerdoc?access_token=_your_access_token_here_
         • Mercury:
           https://api.your_website.com:your_port/saturn/odata4/v1/company('COMPANY_CODE_HERE')/developerdoc?access_token=_your_access_token_here_
         • Saturn:
           https://api.your_website.com:your_port/saturn/odata4/v1/company('COMPANY_CODE_HERE')/developerdoc?access_token=_your_access_token_here_
    2. Querying Data from Accredo WebServices using OData
       • OData queries can be used to filter / navigate the Accredo Data.
       • e.g: This OData Query will export a paged list of Invoices that include all related Lines, with DeliveryDates later than the beginning of 2020:
         https://api.your_website:your_port/saturn/odata4/v1/Company('COMPANY_CODE_HERE')/INInvoice?$filter=DeliveryDate gt '2020-01-01'&$expand=Line
       • Note that TopFlight is available to advise on where to find the appropriate data, and the best methods to extract the data via the Accredo API

• Basic API Examples:

  • ARCustomer Examples:

    • OpenAPI specification for ARCustomers (See top of this article)
    • 
    • Postman example to create a new ARCustomer:
    • 
    • Postman example to update an existing ARCustomer:
    • 

  • INInvoice Examples

    • OpenAPI specification for ININvoice (see top of this article)
    • 
    • Postman example to create a new Quote
      (Quotes and Invoices share the same Endpoint, they use the 'DocumentClass' field to determine if it's a Quote or Invoice)
    • 

• Advanced API Examples:

  • Invoking a Custom API Script with a custom Payload:
    • https://api.your_website.co.nz:6569/{mercury_or_saturn}/odata4/v1/Company('COMPANY_CODE')/PlayScript
    • The Accredo API can be used to invoke custom Accredo-Scripts with custom Input & Output Payloads
    • This is a very useful when you need to invoke custom behaviour within the Accredo Application
    • TopFlight is available to assist with any Custom-Scripting, or custom-Payload requirements
      
    • Simple Payload example:
      • https://api.your_website.co.nz:6569/{mercury_or_saturn}/odata4/v1/Company('COMPANY_CODE')/PlayScript
      • 3 Script-Args, no complex objects
        {
            "ScriptFileName": "TFCS_Custom_Script.pfs",
            "OutputStyle": "List",
            "ScriptArgsn": 3,
            "ScriptArgs1": "123",
            "ScriptArgs2": "abc",
            "ScriptArgs3": "456"
        }
        
    • Complex Payload Example:
      • https://api.your_website.co.nz:6569/{mercury_or_saturn}/odata4/v1/Company('COMPANY_CODE')/PlayScript
      • 1 Script-Arg, Json Array of objects:
        {
            "ScriptFileName": "TFCS_Custom_Script.pfs",
            "OutputStyle": "List",
            "ScriptArgsn": 1,
            "ScriptArgs1": "[{\u0022DocumentType\u0022:\u0022Invoice\u0022,\u0022DocumentID\u0022:98282,\u0022PrintDocumentType\u0022:\u0022DEBUG_PRINTERLIST\u0022}]",
            "ScriptArgs2": null,
            "ScriptArgs3": null
        }
  • Executing Custom SQL:
    • https://api.your_website.co.nz:6569/{mercury_or_saturn}/odata4/v1/Company('COMPANY_CODE')/ExecuteSQL
    • {    
          "QueryText": "SELECT * FROM SOME_TABLE"
      }