{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Building a Custom Integration","description":"The operational transportation management API. Full access to planning, tracking, invoicing, and integrations — built on the OTM5 open data standard.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"building-a-custom-integration","__idx":0},"children":["Building a Custom Integration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"objective","__idx":1},"children":["Objective"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set up a custom integration that automatically syncs new transport orders to an external system (e.g., your ERP, a webhook endpoint, or a data warehouse)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-the-integration","__idx":2},"children":["Step 1: Create the Integration"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/integration \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"name\": \"ERP Sync - New Orders\",\n    \"type\": \"configured\",\n    \"description\": \"Push new transport orders to our ERP system when they are created\",\n    \"enabled\": true\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"message\": \"OK\",\n  \"integration\": {\n    \"id\": \"integration-uuid\",\n    \"name\": \"ERP Sync - New Orders\",\n    \"type\": \"configured\",\n    \"enabled\": true,\n    \"createdAt\": \"2026-03-22T10:00:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-generate-credentials","__idx":3},"children":["Step 2: Generate Credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create authentication credentials for the integration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.otms.transportial.com/api/integration/generate/credentials\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"integrationId\": \"integration-uuid\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the returned credentials securely — they grant access to the integration's scoped data."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-test-your-data-mapping","__idx":4},"children":["Step 3: Test Your Data Mapping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before going live, validate that your data transformation works:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.otms.transportial.com/api/integration/dataSource/mapping:test\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"mapping\": {\n      \"erp_order_id\": \"$.transportOrder.id\",\n      \"customer_name\": \"$.transportOrder.customer.name\",\n      \"status\": \"$.transportOrder.status\",\n      \"created\": \"$.transportOrder.createdAt\"\n    },\n    \"testData\": {\n      \"transportOrder\": {\n        \"id\": \"test-uuid\",\n        \"customer\": { \"name\": \"Acme Corp\" },\n        \"status\": \"requested\",\n        \"createdAt\": \"2026-03-22T10:00:00Z\"\n      }\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-import-data-inbound","__idx":5},"children":["Step 4: Import Data (Inbound)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your integration needs to push data into Transportial:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.otms.transportial.com/api/integration/import/data\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"integrationId\": \"integration-uuid\",\n    \"data\": [\n      {\n        \"name\": \"Order from ERP #12345\",\n        \"status\": \"requested\",\n        \"customer\": { \"name\": \"External Customer\" }\n      }\n    ]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-monitor-processing","__idx":6},"children":["Step 5: Monitor Processing"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"check-the-processing-queue","__idx":7},"children":["Check the Processing Queue"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/integration/{integration-uuid}/objects/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"view-logs","__idx":8},"children":["View Logs"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/integration/{integration-uuid}/logs/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"check-request-logs","__idx":9},"children":["Check Request Logs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the actual HTTP requests the integration has made:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/integration/{integration-uuid}/requestLogs/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"view-integration-tasks","__idx":10},"children":["View Integration Tasks"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/integration/{integration-uuid}/tasks/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-handle-errors","__idx":11},"children":["Step 6: Handle Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If an integration object fails, it will be marked with status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETRY"]},". Check the logs to diagnose:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Get recent logs\ncurl -X GET \"https://api.otms.transportial.com/api/integration/{integration-uuid}/logs/0/10\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common issues:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication failure"]}," — regenerate credentials"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mapping error"]}," — test your mapping with the test endpoint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Target system down"]}," — objects will be retried automatically"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"email-based-integration","__idx":12},"children":["Email-Based Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For email-triggered workflows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.otms.transportial.com/api/integration/email\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"from\": \"orders@customer.com\",\n    \"subject\": \"New transport request\",\n    \"body\": \"Please arrange pickup of 20 pallets...\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"file-based-integration","__idx":13},"children":["File-Based Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upload template files for EDI, CSV, or XML exchange:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.otms.transportial.com/api/integration/file/upload\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -F \"file=@/path/to/template.csv\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Test file template mappings:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.otms.transportial.com/api/integration/fileTemplate/mapping:test\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"mapping\": { ... },\n    \"testData\": { ... }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-processing-flow","__idx":14},"children":["Integration Processing Flow"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Entity Change (e.g., new transport order)\n    ↓\nIntegrationObject created (status: QUEUE)\n    ↓\nScheduler picks up (~every 10 seconds)\n    ↓\nFilters checked (does this event match?)\n    ↓\nData sources transform the data\n    ↓\nExternal system called\n    ↓\nResult: SUCCESS / ERROR / RETRY\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-takeaways","__idx":15},"children":["Key Takeaways"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Integrations are event-driven — they react to entity changes automatically"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always test your mappings before enabling"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Monitor logs and request logs to diagnose issues"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Failed objects are retried automatically"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the App Store for pre-built integrations with common platforms"]}]}]},"headings":[{"value":"Building a Custom Integration","id":"building-a-custom-integration","depth":1},{"value":"Objective","id":"objective","depth":2},{"value":"Step 1: Create the Integration","id":"step-1-create-the-integration","depth":2},{"value":"Step 2: Generate Credentials","id":"step-2-generate-credentials","depth":2},{"value":"Step 3: Test Your Data Mapping","id":"step-3-test-your-data-mapping","depth":2},{"value":"Step 4: Import Data (Inbound)","id":"step-4-import-data-inbound","depth":2},{"value":"Step 5: Monitor Processing","id":"step-5-monitor-processing","depth":2},{"value":"Check the Processing Queue","id":"check-the-processing-queue","depth":3},{"value":"View Logs","id":"view-logs","depth":3},{"value":"Check Request Logs","id":"check-request-logs","depth":3},{"value":"View Integration Tasks","id":"view-integration-tasks","depth":3},{"value":"Step 6: Handle Errors","id":"step-6-handle-errors","depth":2},{"value":"Email-Based Integration","id":"email-based-integration","depth":2},{"value":"File-Based Integration","id":"file-based-integration","depth":2},{"value":"Integration Processing Flow","id":"integration-processing-flow","depth":2},{"value":"Key Takeaways","id":"key-takeaways","depth":2}],"frontmatter":{"seo":{"title":"Building a Custom Integration"}},"lastModified":"2026-03-22T21:04:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/examples/building-an-integration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}