Building integrations

This guide covers how we recommend building integrations to our network, and where to find API information.

Convictional is a platform for enabling B2B trade. We do this various ways. Sometimes our customers have the tech skills in house to build their own integrations. We enable this through our API.

API Documentation

We offer API documentation that covers all the public endpoints for our various services. You can find the V1 API documentation here. In the near future, we'll start releasing V2 endpoints that build on our prior work, and we'll release documentation alongside them when they are ready to go into production.

Support

Please contact support@convictional.com if you have questions about how to approach building integrations. We support our API, and are able to pull logs, review your requests and attempt to reproduce any issues you have consuming our services through the API. 

Best practices

By building an integrated trade platform, we have learned some best practices when it comes to writing integrations. That applies to integrations our customers write to our services as much as it does to us. Here are some of the things we have found result in a better experience, with less unexpected behavior:

  1. Use a queue to keep track of your work while it's in motion to avoid data loss
  2. Log every attempted request to our API and the response that you get for troubleshooting
  3. Use our NPM client library for more comprehensive error reporting and documentation
  4. Use the more reliable language that you can, ideally static typed for validation
  5. Limit use of custom meta data to the minimum necessary to accomplish your goals
  6. Write test coverage that includes mock requests and health checks against the endpoint
  7. Consider authentication and rate limiting requirements during the design phase