--- title: "API integration: discovery, contracts and failure ownership — Orvun Labs" description: "An integration connects two operating systems, not just two endpoints. Before implementation, define the records exchanged, the authority for each field, authentication, expected timing and" canonical: "https://orvunlabs.com/en/journal/api-integration-discovery-contracts" language: "en" last_modified: "2026-09-13" --- # API integration: discovery, contracts and failure ownership An integration connects two operating systems, not just two endpoints. Before implementation, define the records exchanged, the authority for each field, authentication, expected timing and ![API integration: discovery, contracts and failure ownership](https://orvunlabs.com/images/blog/integrations.svg) - Published: 2026-09-13T09:00:00.000Z - [Connected systems](https://orvunlabs.com/en/journal/topic/integrations.md) ## The decision An integration connects two operating systems, not just two endpoints. Before implementation, define the records exchanged, the authority for each field, authentication, expected timing and the person responsible when a transfer stops. A successful test request answers only a small part of that contract. ## A worked example For an illustrative shipping connection, trace order creation, address correction, dispatch and cancellation. Keep the internal order identifier linked to the carrier's identifier. Decide what happens if a label is created but the response is lost; retrying blindly could create another shipment. ## Alternatives worth weighing Direct calls suit interactions needing an immediate answer. A durable queue suits work that may continue after the user leaves. Scheduled reconciliation can detect records missed by either route. These mechanisms can coexist, but each needs a clear status the operations team understands. ## Where the plan breaks Do not bury provider-specific fields throughout the application. Use a mapping boundary and validate incoming data before it becomes a business record. Distinguish transient failure from a permanently invalid address; repeatedly sending the same bad payload is not recovery. ## Write the record contract in business language For the shipping example, describe each state the operator can see: waiting for submission, accepted by the carrier, dispatched, cancelled or needing attention. Document which identifier links the two systems and which events may move a record between states. A transport response may mean only that a request arrived; the business may still need a later confirmation. Keep that distinction visible instead of turning every successful network response into a completed shipment. Write down the meaning of missing fields, time zones, units and optional values. An empty delivery instruction may mean no instruction, while an omitted field in an update may mean leave the current value unchanged. Test those meanings with the actual contract. Ask the API owner about authentication rotation, request limits, supported versions and a representative test environment. Record unverified answers as open dependencies rather than incorporating them into a confident delivery date. ## Give an interrupted transfer a recovery owner Suppose the carrier creates a label but the connection closes before your application receives its identifier. The recovery path depends on the provider’s capabilities: a supported idempotency key or lookup by your reference may resolve it safely. If neither exists, hold the item for investigation instead of blindly creating another shipment. Demonstrate that path with a local fake service or an authorised sandbox, not a real customer order. Provide an operator view or private command that shows one failed reference, its safe error category and the last confirmed business state. Replaying an item should preserve its logical identity and pass the same validation as the first attempt. Assign ownership of credentials, mapping changes and daily exception handling. A versioned sample payload and a small contract test can expose provider changes earlier, but still require someone to decide how a changed business meaning should be handled. ## Before you commission the work Who owns the API account? Is there a representative test environment? Can operators find and safely replay one failed record? Answer these questions with the integration partner and agree acceptance examples for failure as well as success. ## System integration Make your tools work together. - [Discuss this service](https://orvunlabs.com/en/services/system-integration.md) ## Related reading - [Keeping stock, prices and orders consistent between ERP and commerce](https://orvunlabs.com/en/journal/erp-commerce-stock-consistency.md) - [CRM synchronisation needs field ownership and conflict rules](https://orvunlabs.com/en/journal/crm-sync-data-ownership.md) ## Let's make something useful. A first product, a difficult workflow or software that needs a fresh start. Tell us where you are. - [Tell us about your project](https://orvunlabs.com/en/contact) ## Structured data ```json { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://orvunlabs.com/#organization", "name": "Orvun Labs", "url": "https://orvunlabs.com", "logo": "https://orvunlabs.com/orvunlabs-icon-512.png", "description": "Custom software, SaaS products and AI-powered tools — designed around your business.", "knowsAbout": [ "Custom software", "SaaS product development", "AI integration" ] }, { "@type": "WebSite", "@id": "https://orvunlabs.com/#website", "name": "Orvun Labs", "url": "https://orvunlabs.com", "inLanguage": [ "en", "es", "de", "fr", "pt", "ja", "hi", "ar", "id", "tr", "pl" ], "publisher": { "@id": "https://orvunlabs.com/#organization" } }, { "@type": "WebPage", "@id": "https://orvunlabs.com/en/journal/api-integration-discovery-contracts#webpage", "url": "https://orvunlabs.com/en/journal/api-integration-discovery-contracts", "name": "API integration: discovery, contracts and failure ownership", "description": "An integration connects two operating systems, not just two endpoints. Before implementation, define the records exchanged, the authority for each field, authentication, expected timing and ", "inLanguage": "en", "isPartOf": { "@id": "https://orvunlabs.com/#website" }, "about": { "@id": "https://orvunlabs.com/#organization" }, "breadcrumb": { "@id": "https://orvunlabs.com/en/journal/api-integration-discovery-contracts#breadcrumb" } }, { "@type": "BreadcrumbList", "@id": "https://orvunlabs.com/en/journal/api-integration-discovery-contracts#breadcrumb", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Orvun Labs", "item": "https://orvunlabs.com/en" }, { "@type": "ListItem", "position": 2, "name": "API integration: discovery, contracts and failure ownership", "item": "https://orvunlabs.com/en/journal/api-integration-discovery-contracts" } ] }, { "@type": "BlogPosting", "headline": "API integration: discovery, contracts and failure ownership", "description": "An integration connects two operating systems, not just two endpoints. Before implementation, define the records exchanged, the authority for each field, authentication, expected timing and ", "datePublished": "2026-09-13T09:00:00.000Z", "dateModified": "2026-09-13T09:45:03Z", "inLanguage": "en", "author": { "@id": "https://orvunlabs.com/#organization" }, "publisher": { "@id": "https://orvunlabs.com/#organization" }, "image": [ "https://orvunlabs.com/images/blog/integrations.svg" ], "mainEntityOfPage": { "@id": "https://orvunlabs.com/en/journal/api-integration-discovery-contracts#webpage" } } ] } ```