|
| 1 | +{ |
| 2 | + "slug": "datev-sandbox", |
| 3 | + "name": "DATEV Online APIs (Sandbox)", |
| 4 | + "description": "Sandbox environment for the DATEV Online APIs — read accounting Mandanten (clients), document types and DUO version metadata against DATEV's test data. Use this while you build and test; every new DATEV app must run in sandbox until DATEV grants production approval. Same OAuth2 Authorization Code + PKCE flow as production, pointed at DATEV's sandbox endpoints.", |
| 5 | + "instructions": "**Use this connector for testing.** Every DATEV app runs in the sandbox until DATEV completes its production-approval review — so this is where you start.\n\n**Setup**:\n1. Create a **Confidential** app on the DATEV-Entwicklerportal (https://developer.datev.de) with **OpenID Connect Authorization Code Flow**. Set the redirect URI to `<your-server>/api/mcp-oauth/callback`.\n2. Subscribe the app to the sandbox API products: **accounting:clients 2.0** and **accounting:documents 2.0**.\n3. Set `DATEV_CLIENT_ID` and `DATEV_CLIENT_SECRET` (from the portal — copy the secret in full, it is shown only once).\n4. Import this adapter — it is pre-configured for the sandbox (authorize `login.datev.de/openidsandbox/authorize`, token `sandbox-api.datev.de/token`, API base `platform-sandbox/v2`) and authenticates at the token endpoint via **HTTP Basic** (`client_secret_basic`), which DATEV requires.\n5. Run the one-time OAuth flow: `POST /api/connectors/{id}/oauth/authorize` -> open the returned URL -> log in with your DATEV-Konto -> the platform stores an encrypted refresh token automatically.\n6. Every call then sends `Authorization: Bearer <token>` AND the mandatory `X-DATEV-Client-Id: <DATEV_CLIENT_ID>` header automatically.\n\n**Going to production**: once DATEV approves your app for production, use the separate **DATEV Online APIs** connector (same credentials, production endpoints).\n\n**Scopes requested**: `datev:accounting:clients accounting:clients:read accounting:documents`. Do NOT add `openid` — it is the issuer name, not a requested scope.\n\n**Mandant scoping**: every per-client tool takes a `clientId` parameter — the **Mandant UUID** (RFC4122), returned by `datev_list_clients`. Distinct from `DATEV_CLIENT_ID` (the OAuth app identifier, sent in the header).", |
| 6 | + "region": "de", |
| 7 | + "category": "accounting", |
| 8 | + "icon": "datev", |
| 9 | + "docsUrl": "https://developer.datev.de/en/products/988700e4-e0c5-40bf-814b-cd7327dad67a", |
| 10 | + "requiredEnvVars": [ |
| 11 | + "DATEV_CLIENT_ID", |
| 12 | + "DATEV_CLIENT_SECRET" |
| 13 | + ], |
| 14 | + "connector": { |
| 15 | + "name": "DATEV Online APIs (Sandbox)", |
| 16 | + "type": "REST", |
| 17 | + "baseUrl": "https://accounting-clients.api.datev.de/platform-sandbox/v2", |
| 18 | + "authType": "OAUTH2", |
| 19 | + "authConfig": { |
| 20 | + "clientId": "{{DATEV_CLIENT_ID}}", |
| 21 | + "clientSecret": "{{DATEV_CLIENT_SECRET}}", |
| 22 | + "authorizationUrl": "https://login.datev.de/openidsandbox/authorize", |
| 23 | + "tokenUrl": "https://sandbox-api.datev.de/token", |
| 24 | + "tokenAuthMethod": "basic", |
| 25 | + "scopes": "datev:accounting:clients accounting:clients:read accounting:documents" |
| 26 | + }, |
| 27 | + "headers": { |
| 28 | + "X-DATEV-Client-Id": "{{DATEV_CLIENT_ID}}" |
| 29 | + } |
| 30 | + }, |
| 31 | + "tools": [ |
| 32 | + { |
| 33 | + "name": "datev_list_clients", |
| 34 | + "description": "List DATEV accounting Mandanten (clients) your DATEV-Konto user is provisioned for, from the accounting-clients v2 master-data product. Returns each client's UUID, consultant number, client number and display name. Use the returned UUID as the `clientId` parameter on all other tools.", |
| 35 | + "parameters": { |
| 36 | + "type": "object", |
| 37 | + "properties": { |
| 38 | + "skip": { |
| 39 | + "type": "integer", |
| 40 | + "description": "Pagination offset (>= 0)." |
| 41 | + }, |
| 42 | + "top": { |
| 43 | + "type": "integer", |
| 44 | + "description": "Max items per page (1-100)." |
| 45 | + } |
| 46 | + } |
| 47 | + }, |
| 48 | + "endpointMapping": { |
| 49 | + "method": "GET", |
| 50 | + "path": "https://accounting-clients.api.datev.de/platform-sandbox/v2/clients", |
| 51 | + "queryParams": { |
| 52 | + "skip": "$skip", |
| 53 | + "top": "$top" |
| 54 | + }, |
| 55 | + "headers": { |
| 56 | + "Accept": "application/json" |
| 57 | + } |
| 58 | + } |
| 59 | + }, |
| 60 | + { |
| 61 | + "name": "datev_get_client", |
| 62 | + "description": "Get one Mandant's master data (consultant/client number, name, address) from accounting-clients v2.", |
| 63 | + "parameters": { |
| 64 | + "type": "object", |
| 65 | + "properties": { |
| 66 | + "clientId": { |
| 67 | + "type": "string", |
| 68 | + "description": "Mandant UUID (RFC4122 8-4-4-4-12). Get this from datev_list_clients." |
| 69 | + } |
| 70 | + }, |
| 71 | + "required": [ |
| 72 | + "clientId" |
| 73 | + ] |
| 74 | + }, |
| 75 | + "endpointMapping": { |
| 76 | + "method": "GET", |
| 77 | + "path": "https://accounting-clients.api.datev.de/platform-sandbox/v2/clients/{clientId}", |
| 78 | + "headers": { |
| 79 | + "Accept": "application/json" |
| 80 | + } |
| 81 | + } |
| 82 | + }, |
| 83 | + { |
| 84 | + "name": "datev_documents_list_clients", |
| 85 | + "description": "List the subset of Mandanten that have DATEV Unternehmen online (DUO) document access via the accounting-documents v2 product. This may be smaller than datev_list_clients — only clients with active DUO subscriptions appear here.", |
| 86 | + "parameters": { |
| 87 | + "type": "object", |
| 88 | + "properties": {} |
| 89 | + }, |
| 90 | + "endpointMapping": { |
| 91 | + "method": "GET", |
| 92 | + "path": "https://accounting-documents.api.datev.de/platform-sandbox/v2/clients", |
| 93 | + "headers": { |
| 94 | + "Accept": "application/json" |
| 95 | + } |
| 96 | + } |
| 97 | + }, |
| 98 | + { |
| 99 | + "name": "datev_get_documents_client", |
| 100 | + "description": "Get one Mandant's basic data as exposed by the accounting-documents v2 product (the DUO view, distinct from the accounting-clients master record).", |
| 101 | + "parameters": { |
| 102 | + "type": "object", |
| 103 | + "properties": { |
| 104 | + "clientId": { |
| 105 | + "type": "string", |
| 106 | + "description": "Mandant UUID (from datev_list_clients or datev_documents_list_clients)." |
| 107 | + } |
| 108 | + }, |
| 109 | + "required": [ |
| 110 | + "clientId" |
| 111 | + ] |
| 112 | + }, |
| 113 | + "endpointMapping": { |
| 114 | + "method": "GET", |
| 115 | + "path": "https://accounting-documents.api.datev.de/platform-sandbox/v2/clients/{clientId}", |
| 116 | + "headers": { |
| 117 | + "Accept": "application/json" |
| 118 | + } |
| 119 | + } |
| 120 | + }, |
| 121 | + { |
| 122 | + "name": "datev_list_document_types", |
| 123 | + "description": "List the document types (Belegtypen) configured for a Mandant on DATEV Unternehmen online — needed before uploading documents so you know which `documentType` values are accepted.", |
| 124 | + "parameters": { |
| 125 | + "type": "object", |
| 126 | + "properties": { |
| 127 | + "clientId": { |
| 128 | + "type": "string", |
| 129 | + "description": "Mandant UUID (from datev_list_clients)." |
| 130 | + } |
| 131 | + }, |
| 132 | + "required": [ |
| 133 | + "clientId" |
| 134 | + ] |
| 135 | + }, |
| 136 | + "endpointMapping": { |
| 137 | + "method": "GET", |
| 138 | + "path": "https://accounting-documents.api.datev.de/platform-sandbox/v2/clients/{clientId}/document-types", |
| 139 | + "headers": { |
| 140 | + "Accept": "application/json" |
| 141 | + } |
| 142 | + } |
| 143 | + }, |
| 144 | + { |
| 145 | + "name": "datev_get_duo_version", |
| 146 | + "description": "Get the DATEV Unternehmen online (DUO) version and the permitted file extensions for document upload on a given Mandant. Useful before generating uploads to know what file formats DUO will accept (PDF, JPG, TIFF, etc.) and any DUO-version-specific limits.", |
| 147 | + "parameters": { |
| 148 | + "type": "object", |
| 149 | + "properties": { |
| 150 | + "clientId": { |
| 151 | + "type": "string", |
| 152 | + "description": "Mandant UUID (from datev_list_clients)." |
| 153 | + } |
| 154 | + }, |
| 155 | + "required": [ |
| 156 | + "clientId" |
| 157 | + ] |
| 158 | + }, |
| 159 | + "endpointMapping": { |
| 160 | + "method": "GET", |
| 161 | + "path": "https://accounting-documents.api.datev.de/platform-sandbox/v2/clients/{clientId}/duo-version", |
| 162 | + "headers": { |
| 163 | + "Accept": "application/json" |
| 164 | + } |
| 165 | + } |
| 166 | + } |
| 167 | + ] |
| 168 | +} |
0 commit comments