API incidents - Troubleshooting and reporting

[Magnus Johnsen]

Encountering an Issue 

First troubleshooting steps

When encountering an issue using the API there are steps you’ll want to follow to understand where the issue occurs and what support channels it should be reported via to resolve the issue in a timely manner.

1. Review the error message, look at the returned HTTP status code to understand what the issue is regarding.
2. Perform the same action in the UI to determine if it is API specific or if it is the UI that is affected.
   1. Are you using the correct endpoint for what you want to do?
   2. Can the error message inform you what is going wrong? You might need to review the JSON request body, to see the syntax and required fields for the endpoint, please have a look at Visma.Net API Swagger.
   3. If you have reviewed this, and you are still unable to resolve the issue, head over to the Developer Forum and search for similar issues or get in touch with your market specific support: Visma.net ERP API Support channels 
      
   4. If you are still unable to find a solution, create a forum thread and include all relevant information, further explained later in this document, so that the API support team may investigate your issue.
1. If the issue is reproducible in the UI, review the error message in the UI, this will often point you to where in the ERP you might need to review settings. If this doesn’t help, inform your ERP UI user that they need to open a case through the ERP support channels specific to the market.
2. If the issue is not reproducible in the UI, review the action being performed via the API.

Reporting the issue

The terms for the API support states that to make investigation easier and reduce the time required to find a solution to your problem, you’ll need to include as much relevant information as possible when you are reporting your issue, this is true regardless of what channel your issue should be reported to.

When reporting an issue to the developer forum, the thread should contain the following information and be formatted in a way that makes the post to be easy to follow.

When you're Posting a Support Case on the community, you should share clarified information which belongs to your API Transaction/s 

Such as,

1. Used API Endpoint URL / Method
2. Returned Http Status Code
3. Returned Response Body (Error Message)
4. If this is a POST/PUT request then Used RAW JSON script has to be attached

These pieces of information are crucial for the API Support consultant to be able to help you, diagnose the case. 

What are you trying to do

Explain what you are trying to do, what the expected results are and what results you get.

Provide detailed steps of the work flow you have followed.

Your Request:

1. Method and URL to endpoint where issue occurs
1. e.g. GET https://integration.visma.net/API/controller/api/v1/inventory/
2. JSON request body
1. Post this in code blocks: [CODE] { “My JSON” : { “Value”: “Request” } } [/CODE]

The servers Response:

• HTTP Status Code
• Post this in code blocks: [CODE] 201 Created [/CODE]
• JSON response body
• Post this in code blocks: [CODE] { “Servers JSON” : { “Value”: “Response” } } [/CODE]
  

Case Examples

For further examples of scenarios where troubleshooting is needed and how to report them, please have a look at the PDF attached to this post.