# DATEV: Application Owner Setup

## Prerequisites

DATEV's APIs are not self-service. Sandbox access needs a DATEV Developer Portal account
with an App subscribed to the relevant API products. Production access additionally
requires **Schnittstellenanbieter (interface partner) status** and passing DATEV's
technical review.

## Steps to get credentials

Sandbox first: you do not need DATEV's approval to start building. Apideck also ships its
own temporary shared sandbox credentials for this connector, so you can try it against
sandbox data before registering your own DATEV App.

1. **Register at the DATEV Developer Portal**: https://developer.datev.de/en
2. **Create an Enterprise Organization** in the portal (or join an existing one)
3. **Create an App** in your organization
4. **Subscribe the App to every API product you need**: Clients, Accounting Data Exchange,
   EXTF Files, `accounting:documents`, and `dxso-jobs`. Subscribing grants **sandbox
   access automatically**: DATEV requires no separate approval for sandbox. Subscribe to
   everything you might need now: products cannot be added to an App once production
   approval completes.
5. **Use the App's Client ID and Client Secret** from the portal for sandbox development

Production is a separate DATEV process, run in parallel:

6. **Apply for Schnittstellenanbieter (Interface Partner) status**: contact your DATEV
   partner manager, who will guide you through the application
7. **Implement and self-test** against the sandbox, following DATEV's "General" and
   product-specific interface requirements
8. **Book and pass the technical review** with a DATEV consultant, after which DATEV
   issues production credentials

Ask your DATEV partner manager for an expected timeline for your application and review
appointment: the queue is DATEV's to schedule.

## Where to enter your credentials

Paste the Client ID and Client Secret into the
[Apideck DATEV connector settings](https://platform.apideck.com/configuration/accounting/datev-unternehmen-online)
under **Use your own client credentials** in the Apideck Dashboard.

Register this redirect URL on your DATEV OAuth application:

```
https://unify.apideck.com/vault/callback
```

## OAuth Configuration

| Setting | Value |
|---------|-------|
| Authorization URL (Sandbox) | `https://login.datev.de/openidsandbox/authorize` |
| Token URL (Sandbox) | `https://sandbox-api.datev.de/token` |
| Token Lifetime | 15 minutes (900 seconds) |
| Refresh Token Lifetime | 11 hours (standard) or 2 years (with `offline_access` scope) |
| Token Request Content-Type | `application/x-www-form-urlencoded` |
| PKCE | Required (`S256` code challenge) |

## Environment scope

This connector currently functions against DATEV's **sandbox**. Its OAuth
authorize/token endpoints and all of its API base URLs address DATEV's sandbox hosts, so
authorizations and API calls made through it reach sandbox data. Configure the connector
with the sandbox Client ID and Secret of your DATEV App, and plan your build and
verification against sandbox Mandanten.

Obtaining production credentials from DATEV is a real, separate process: the steps above
are worth starting in parallel, since DATEV's review is the long pole. Routing Apideck API
calls to DATEV's production environment is not part of this connector's current scope.
Let [Apideck Support](https://help.apideck.com/en/articles/7774658) know if production
routing is a requirement for your integration.

## Required Scopes

| Scope | Purpose |
|-------|---------|
| `openid` | OpenID Connect (required) |
| `offline_access` | Long-lived refresh tokens (strongly recommended) |
| `datev:accounting:clients` | Clients API: lists Mandanten (companies, company info) |
| `datev:accounting:exchange` | Accounting Data Exchange API: ledger accounts, journal entries, balance sheet, tax rates, customers, suppliers |
| `datev:accounting:extf-files-import` | Upload EXTF CSV files |
| `datev:accounting:documents` | Upload documents to Belege Online |
| `datev:accounting:dxso-jobs` | Upload XML invoice data |

Request all seven when you subscribe: DATEV grants scopes per API product, and the two
read scopes gate different resource groups. Without `datev:accounting:clients`, the
companies and company-info reads fail. Without `datev:accounting:exchange`, the
ledger-accounts, journal-entries, balance-sheet, tax-rates, customers and suppliers reads
fail.

## Headers Apideck sends automatically

Every API request Apideck makes on your App's behalf includes an `Authorization: Bearer`
header carrying the access token, and an `X-DATEV-Client-Id` header carrying your App's
OAuth Client ID. Neither is something you configure yourself: they're listed here so you
recognize them if you inspect traffic or read a DATEV error response.

## Notes and troubleshooting

- **Read operations** (Mandanten, ledger accounts, accounting sequences, sums and
  balances, tax rates) are the mature path and are what to certify against first.
- **Write operations** that go through DATEV's EXTF CSV import (journal entries,
  customers, suppliers) are still being hardened on the Apideck side and are not yet
  verified working end-to-end in the sandbox. Contact
  [Apideck Support](https://help.apideck.com/en/articles/7774658) if an import is
  rejected.
- **Document size**: documents sent through the `accounting:documents` API are capped at
  20 MB each. Larger files must be split and logically linked via DATEV's `stapled`
  endpoint rather than submitted as a single file.
- **Authorization succeeds but reads return errors**: check the granted scope list first
  (see above), then confirm the configured credentials are the sandbox credentials of an
  App whose API-product subscriptions are active.

## References

- [DATEV Developer Portal](https://developer.datev.de/en)
- [DATEV Developer Help](https://developer.datev.de/en/help)
- [Interface requirements guide](https://developer.datev.de/en/guides/interface-requirements)
- [accounting:documents interface requirements](https://developer.datev.de/en/product-detail/accounting-documents/2.0/documentation/interface-requirements)