# External Business DB Write API Integration Guide This document is the handoff guide for internal teams and third-party integrators who need to write data into a preconfigured business MongoDB connection through Drobodata. ## 1. Integration Target - Base URL: `` - Auth header: `X-API-Key` - Allowed connectionId: `` - Allowed collection whitelist: - `businessWriteValidation` Current API key: ```text dbw_ ``` Do not keep the live plaintext key in git, wiki pages, or chat history. Distribute it out of band to the third party. The platform stores only a hash and preview; the full key is shown only in the create or rotate response. If this key is rotated later, the old key immediately becomes invalid. ## 2. Supported Operations Third parties can call these routes: - `POST /api/external/business-db/documents` - `PATCH /api/external/business-db/documents/:documentId` - `POST /api/external/business-db/upserts` All requests must include: ```http Content-Type: application/json X-API-Key: dbw_... ``` ## 3. Request Rules - `connectionId` must be the authorized one - `collection` must be in the token whitelist - `document`, `patch`, `match`, and `setOnInsert` must be plain JSON objects - Mongo update operators such as `$set`, `$inc`, `$push` are not accepted ## 4. Create Document Request: ```bash curl -X POST '/api/external/business-db/documents' \ -H 'Content-Type: application/json' \ -H 'X-API-Key: dbw_' \ --data '{ "connectionId": "", "collection": "businessWriteValidation", "document": { "runLabel": "partner-demo-001", "source": "partner-a", "value": 123, "createdAt": "2026-04-14T17:20:00+08:00" } }' ``` Typical success response: ```json { "connectionId": "", "collection": "businessWriteValidation", "operation": "created", "document": { "_id": { "$oid": "69de3ab85edc4783ca5ce18b" }, "runLabel": "partner-demo-001", "source": "partner-a", "value": 123, "createdAt": "2026-04-14T17:20:00+08:00" } } ``` ## 5. Patch Existing Document By _id Request: ```bash curl -X PATCH '/api/external/business-db/documents/' \ -H 'Content-Type: application/json' \ -H 'X-API-Key: dbw_' \ --data '{ "connectionId": "", "collection": "businessWriteValidation", "patch": { "value": 789, "status": "done" } }' ``` Typical success response: ```json { "connectionId": "", "collection": "businessWriteValidation", "operation": "updated", "document": { "_id": { "$oid": "69de3ab85edc4783ca5ce18b" }, "runLabel": "partner-demo-001", "source": "partner-a", "value": 789, "status": "done" } } ``` ## 6. Upsert By Business Key Use this when the third party wants "insert if not exists, otherwise update". Request: ```bash curl -X POST '/api/external/business-db/upserts' \ -H 'Content-Type: application/json' \ -H 'X-API-Key: dbw_' \ --data '{ "connectionId": "", "collection": "businessWriteValidation", "match": { "runLabel": "partner-demo-001" }, "patch": { "source": "partner-a", "value": 456, "updatedAt": "2026-04-14T17:21:00+08:00" }, "setOnInsert": { "createdBy": "partner-a" } }' ``` Typical success response: - Insert path: `operation` is `created` - Update path: `operation` is `updated` ## 7. Error Cases Common failures: - `401 Unauthorized` - Missing `X-API-Key` - Invalid API key - Rotated or disabled API key - `403 Forbidden` - `connectionId` not allowed for this token - `collection` not allowed for this token - `400 Bad Request` - Invalid JSON - Missing required fields - `document` / `patch` / `match` not plain JSON objects ## 8. Verified Live Test On April 14, 2026 This configuration was tested against the live remote Kubernetes deployment on April 14, 2026. Verified successfully: - create document - upsert document - patch document by `_id` Test collection: - `businessWriteValidation` Sample live test markers: - `external-api-test-202604141712` - `external-api-upsert-202604141712` ## 9. Operational Notes - This API does not expose raw MongoDB credentials to third parties - A token should be scoped to the smallest possible set of collections - If a third party no longer needs access, disable or delete the token - If a key is leaked, rotate it immediately