--- title: "Migreren naar asynchrone API-referentie import en hersynchronisatie" slug: "migrate-to-async-api-reference-import-resync" updated: 2026-11-03T09:00:13Z published: 2026-11-03T09:00:13Z canonical: "docs.document360.com/migrate-to-async-api-reference-import-resync" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.document360.com/llms.txt > Use this file to discover all available pages before exploring further. # Migreren naar asynchrone API-referentie import en hersynchronisatie Als je API importeert of opnieuw synchroniseert via de Customer API of de `d360` CLI, moet je je integratie verplaatsen naar de nieuwe asynchrone endpoints en commando's voordat de oude worden verwijderd. Na de migratie importeren grote specificatiebestanden zonder time-outs of geheugenfouten, en je pipeline krijgt een clear pass or fail resultaat voor elke import. Deze gids leidt je door de migratie voor Customer API V3, Customer API v2 en de `d360` CLI. BELANGRIJK! Op Customer API V3 `force_import` staat nu standaard op `false` elke import- en resyncroute, inclusief de verouderde synchrone routes. Als je V3-aanroepen weglaten `force_import`, wordt een specificatie die vroeger ondanks fouten of waarschuwingen importeerde, nu geweigerd, zelfs voordat je migreert. [Zie Bepaal hoe je met bevindingen omgaat](/docs/nl/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). --- ## Ontdek wat je nodig hebt om te migreren Begin met de integratie die je vandaag gebruikt. Elke rij linkt naar de sectie die je nodig hebt. | Als je gebruikt | Wat te doen | Ga naar | | --- | --- | --- | | Klant-API V3 (`/v3/projects/{projectId}/api-references`) | Vervang de import- en resync-aanroepen, en voeg polling toe | [Migrate a Customer API V3 integratie](/docs/nl/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v3-integration) | | Customer API v2 (`/v2/APIReferences`) | Vervang de import- en resync-aanroepen, en voeg polling toe | [Migrate a Customer API v2 integratie](/docs/nl/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | CI/CD-routes (`/v2/apidocs/…`) direct aangesproken | Vervang de routes en voeg polling toe | [Migrate a Customer API v2 integratie](/docs/nl/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | `d360 apiref import` of `d360 apiref resync` | Upgrade de CLI en schakel over naar `d360 apiref submit` | [Migreer de d360 CLI en CI/CD-pijplijnen](/docs/nl/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | `d360 apidocs` of `d360 apidocs:resync` | Upgrade de CLI en schakel over naar `d360 apidocs:submit` | [Migreer de d360 CLI en CI/CD-pijplijnen](/docs/nl/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | Alleen het kennisbankportaal | Niets. Portalimport en hersynchronisatie blijven onaangetast. | | Je huidige endpoints en commando's werken nog steeds, maar ze zijn verouderd. OPMERKING De oude synchrone eindpunten en CLI-commando's worden tegen het einde van maart 2027 verwijderd. Plan je migratie van tevoren vóór dat venster. --- ## Voordat je begint Bevestig het volgende zodat je eerste asynchrone oproep werkt: 1. **Je V3 API-sleutel of rol heeft beide rechten.** Indienen vereist **Bijwerken artikelen**. Het lezen van het resultaat vereist **projectinstellingen**. Met slechts één daarvan kun je het resultaat indienen maar niet lezen, of omgekeerd. Op v2 wordt dezelfde CI/CD API-sleutel of API-token gebruikt om het resultaat in te dienen en te lezen. 2. **Je kent je regionale basis-URL.** | Regio | Basis-URL | | --- | --- | | EU | `https://apihub.document360.io` | | VS | `https://apihub.us.document360.io` | | Canada | `https://apihub.ca.document360.io` | | Privéhosting | `https://apihub.<your-hosting-name>.document360.io` | 3. **Je specificatie valt binnen de groottelimieten.** Een specificatie kan tot 25 MB zijn, geüpload of opgehaald van een URL. Het uploadverzoek kan tot 26 MB zijn. Een URL-ophalen die niet binnen 100 seconden voltooid is, faalt. 4. **Je hebt besloten hoe je met de bevindingen omgaat.** Zie de volgende sectie. ### Bepaal hoe je met bevindingen omgaat Wanneer geforceerde import uit staat, wordt je import of resync geweigerd als de specificatie: - Er is een fout of waarschuwing. - Heeft geen `servers` ingang. Force import staat standaard uit in alle drie de integraties: | Integratie | Standaard | Wat is er veranderd | | --- | --- | --- | | Klant-API V3 | `force_import: false` | De standaard was `true`vroeger . Dit geldt voor de nieuwe en de verouderde V3-routes. | | Klant-API v2 | `forceImport=false` | Niets. De standaard was al `false`. | | `d360` CLI | `--force-import` en `--force` zijn er niet mee als je ze niet voorbij gaat | Niets. | Wanneer een specificatie wordt geweigerd, heb je twee opties: - **Herstel de specificatie.** Dit is de aanbevolen optie. Bevindingen kunnen de gegenereerde documentatie beïnvloeden. Bijvoorbeeld, een eigenschap die in plaats van `boolean` is getypeerd`bool`, wordt geïmporteerd zonder een type. - **Forceer de import.** Stuur `"force_import": true` (V3), `forceImport=true` (v2), `--force-import` (`apiref submit`), of `--force` (`apidocs:submit`). Behandel dit als een bewuste override, niet als een standaard. Als je V3-scripts op de oude standaard vertrouwden, worden ze nu geweigerd, ongeacht of je bent gemigreerd of niet. Herstel de specificatie of voeg `force_import: true`. Dezelfde bevestiging geldt voor een hersynchronisatie die eindpunten verwijdert. Zonder deze bevestiging mislukt de operatie met een waarschuwing zoals *"Deze update verwijdert permanent 19 eindpunten. Geef force_import=waar om te bevestigen"* en vermeldt de eindpunten in `result.deleted_endpoints`. Niets wordt verwijderd totdat je bevestigt. --- ## Hoe je integratie verandert Vandaag wacht je oproep tot de volledige specificatie is verwerkt en geeft het resultaat terug. Nadat je hebt gemigreerd, werkt je integratie in drie stappen: 1. **Dien** de import in of resync. Je krijgt `202 Accepted` direct een operatie-ID. 2. **Poll** het status-eindpunt met die ID totdat de bewerking een definitieve status bereikt. 3. **Lees** het resultaat, fouten, waarschuwingen en de nieuwe API-referentie-ID uit de uiteindelijke reactie. Wat geïmporteerd wordt, verandert niet. Dezelfde specificatie produceert dezelfde API-referentie. Alleen *wanneer* je het resultaat krijgt en waar je leest *,* veranderen fouten en waarschuwingen. Een typische import is binnen enkele seconden tot minder dan een minuut klaar. Beschouw de `202` reactie nooit als succes. De JSON-voorbeelden in deze gids zijn ingekort tot de velden die ertoe doen. --- ## Migrate a Customer API V3 integratie Authenticeer met de `X-API-Key: d360_sk_…` header, of een bearer-token met de `customerApi` scope. ### Stap 1: Vervang de eindpunten | Werking | Oud (verouderd) | Nieuw | | --- | --- | --- | | Import | `POST /v3/projects/{projectId}/api-references` | `POST /v3/projects/{projectId}/api-references/imports` | | Resync | `PUT /v3/projects/{projectId}/api-references/{apiReferenceId}` | `POST /v3/projects/{projectId}/api-references/{apiReferenceId}/resyncs` | | Lees de uitkomst | In de reactie | `GET /v3/projects/{projectId}/operations/{operationId}` | ### Stap 2: Dien de import in of synchroniseer opnieuw Om te importeren vanaf een URL: ``` curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/imports" \ -H "X-API-Key: $D360_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/openapi.json", "workspace_id": "" }' ``` Om uit een bestand te importeren, stuur `multipart/form-data`: ``` curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/imports" \ -H "X-API-Key: $D360_API_KEY" \ -F "file=@openapi.json;type=application/json" \ -F "workspace_id=" ``` Om een bestaande API-referentie opnieuw te synchroniseren: ``` curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/$API_REFERENCE_ID/resyncs" \ -H "X-API-Key: $D360_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/openapi.json" }' ``` Een hersynchronisatie neemt `workspace_id`geen . Het gebruikt de werkruimte van de bestaande API-referentie. Gebruik deze verzoekvelden: | Veld | Import | Resync | Noten | | --- | --- | --- | --- | | `url` | Optioneel | Optioneel | Een publiek bereikbare specificatie-URL | | `file` | Optioneel (meerdelig) | Optioneel (meerdelig) | Het specificatiebestand, JSON of YAML | | `content` | Verouderd | Verouderd | Gebruik `file` in plaats daarvan | | `workspace_id` | Verplicht | Niet gebruikt | Doelwerkruimte | | `publish_articles` | Optioneel | Optioneel | Publiceert de gegenereerde artikelen | | `user_id` | Vereist met `publish_articles` | Vereist met `publish_articles` | Het teamlid dat publiceert | | `force_import` | Optioneel, standaard `false` | Optioneel, standaard `false` | Zie [Bepaal hoe bevindingen om te gaan](/docs/nl/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings) | Geef precies één van `url`, `file`, of `content`. Het antwoord is `202 Accepted`. Sla het `operation_id` veld of de `Operation-Location` header op. Beide identificeren de operatie die je als volgende pollt. ``` Operation-Location: https://apihub.document360.io/v3/projects/{projectId}/operations/{operationId} ``` ``` { "data": { "id": null, "status": null, "operation_id": "4da2313e-b2da-440f-b4be-a1632901f2eb", "operation_status": "queued" }, "success": true } ``` OPMERKING Als je integratie leest `data.id` of `data.status` van het verzendantwoord komt, update het dan bij. Beide staan `null` op een `202` antwoord omdat er nog niets is geïmporteerd. Je krijgt de API-referentie-ID uit het operatieresultaat in Stap 4. ### Stap 3: Peil tot de operatie is afgerond ``` curl -sS "https://apihub.document360.io/v3/projects/$PROJECT_ID/operations/$OPERATION_ID" \ -H "X-API-Key: $D360_API_KEY" ``` Terwijl de bewerking `queued` of `running`is, bevat de respons een `Retry-After: 5` header. Wacht dat aantal seconden tussen polls. Stop pollen wanneer de status definitief is: | Status | Finale | Betekenis | | --- | --- | --- | | `queued` | Nee | Geaccepteerd en wachtend op een werknemer | | `running` | Nee | Wordt verwerkt | | `succeeded` | Ja | Succesvol geïmporteerd of opnieuw gesynchroniseerd | | `failed` | Ja | Niet toegepast. Controleer `message`, `errors`, en `result` | Beperk je polling met een timeout. Twintig minuten is gul voor de meeste specificaties. Als een operatie stopt met voortgang, markeert een achtergrondwatchdog het `failed`, zodat je poll altijd een definitieve status bereikt. ### Stap 4: Lees het resultaat Wanneer de operatie slaagt, sla `result.api_definition_id`dan op. Dit is de API-referentie-ID die je gebruikt bij latere hersynchronisatie-, publiceer- en verwijderingsaanroepen. ``` { "data": { "id": "4da2313e-b2da-440f-b4be-a1632901f2eb", "operation_type": "import-api-reference", "status": "succeeded", "message": null, "result": { "api_definition_id": "f9af5181-ee76-489d-b6c9-306e9eb6d60a", "is_success": true, "articles_created": 19, "categories_created": 3, "errors": null, "warnings": null, "is_server_available": true, "show_spec_file_warning": false, "deleted_endpoints": null }, "errors": null, "created_at": "2026-10-05T10:02:25.33Z", "updated_at": "2026-10-05T10:02:30.866Z", "completed_at": "2026-10-05T10:02:30.866Z" }, "success": true } ``` **Als je specificatie bevindingen heeft** en `force_import` is `false`, eindigt de bewerking als `failed` en vermeldt de bevindingen in `result.errors` en `result.warnings`. Elke `pointer` is een JSON-pointer in je specificatie, zodat je direct naar de lijn kunt gaan om te fixen. Het pad in dit voorbeeld is illustratief. ``` { "data": { "status": "failed", "message": "The operation failed.", "result": { "is_success": false, "errors": [ { "message": "Invalid schema type identifier: bool", "pointer": "#/paths/~1orders/get/responses/200/content/application~1json/schema/properties/active/type" } ], "warnings": [] } } } ``` **Als de taak niet kon draaien**, bijvoorbeeld omdat de URL niet kon worden opgehaald, `message` en `errors[0].message` geef de reden: ``` { "data": { "status": "failed", "message": "This operation can't be completed. Please ensure that you have given a valid specification URL.", "result": null, "errors": [ { "code": "OPERATION_FAILED", "message": "This operation can't be completed. Please ensure that you have given a valid specification URL." } ] } } ``` ### Voorbeeld: Gate een pipelinestap op het importresultaat Dit script voert een import in, wacht op een eindstatus en sluit bij falen af met een niet-nul code: ``` #!/usr/bin/env bash set -euo pipefail BASE="https://apihub.document360.io" H=(-H "X-API-Key: $D360_API_KEY") # 1. Submit and capture the status URL from the Operation-Location header OP_URL=$(curl -sS -D - -o /dev/null -X POST \ "$BASE/v3/projects/$PROJECT_ID/api-references/imports" "${H[@]}" \ -H "Content-Type: application/json" \ -d "{\"url\":\"$SPEC_URL\",\"workspace_id\":\"$WORKSPACE_ID\"}" \ | awk 'tolower($1)=="operation-location:" {print $2}' | tr -d '\r') [ -n "$OP_URL" ] || { echo "Submission was not accepted" >&2; exit 1; } # 2. Poll until a final status (capped at 20 minutes) for _ in $(seq 1 240); do BODY=$(curl -sS "$OP_URL" "${H[@]}") STATUS=$(echo "$BODY" | jq -r '.data.status') case "$STATUS" in queued|running) sleep 5 ;; succeeded) echo "$BODY" | jq '.data.result'; exit 0 ;; *) echo "$BODY" | jq '.data.message, .data.result.errors, .data.result.warnings' >&2; exit 1 ;; esac done echo "Timed out waiting for the operation" >&2 exit 1 ``` --- ## Migrate a Customer API v2 integratie Authenticeer met de `api_token` header. De v2 asynchrone eindpunten nemen dezelfde `multipart/form-data` velden als de synchrone, inclusief de vereiste `forceImport`. ### Stap 1: Vervang de eindpunten | Werking | Oud (verouderd) | Nieuw | | --- | --- | --- | | Import | `POST /v2/APIReferences` | `POST /v2/APIReferences/jobs` | | Resync | `PUT /v2/APIReferences` | `PUT /v2/APIReferences/jobs` | | Lees de uitkomst | In de reactie | `GET /v2/APIReferences/jobs/{backgroundTaskId}` | Als je de CI/CD-routes direct aanroept met een CI/CD API-sleutel, vervang deze dan in plaats daarvan. De `d360 apidocs` commando's gebruiken dezelfde routes. | Werking | Oud (verouderd) | Nieuw | | --- | --- | --- | | Import | `POST /v2/apidocs/import/{userId}` | `POST /v2/apidocs/jobs/import/{userId}` | | Resync | `POST /v2/apidocs/{apiDefinitionId}/resync/{userId}` | `POST /v2/apidocs/jobs/{apiDefinitionId}/resync/{userId}` | | Lees de uitkomst | In de reactie | `GET /v2/apidocs/jobs/{backgroundTaskId}` | ### Stap 2: Dien de import in of synchroniseer opnieuw Importeren: ``` curl -i -X POST "https://apihub.document360.io/v2/APIReferences/jobs" \ -H "api_token: $D360_API_TOKEN" \ -F "url=https://api.example.com/openapi.json" \ -F "projectVersionId=" \ -F "userId=" \ -F "forceImport=false" ``` Om opnieuw te synchroniseren: ``` curl -i -X PUT "https://apihub.document360.io/v2/APIReferences/jobs" \ -H "api_token: $D360_API_TOKEN" \ -F "url=https://api.example.com/openapi.json" \ -F "apiReferenceId=" \ -F "projectVersionId=" \ -F "userId=" \ -F "forceImport=false" ``` Het antwoord is `202 Accepted`. Behalve `background_task_id` voor peilingen. ``` { "data": { "background_task_id": "c02535d8-f051-41d3-92a9-57a224022f7d", "is_processing": true, "alerts": [{ "message": "Accepted for processing. Poll /v2/apireferences/jobs/c02535d8-… for the result." }] }, "success": true } ``` ### Stap 3: Peil tot de klus klaar is ``` curl -sS "https://apihub.document360.io/v2/APIReferences/jobs/$BACKGROUND_TASK_ID" \ -H "api_token: $D360_API_TOKEN" ``` Blijf pollen tot `data.is_processing` is `false`. ### Stap 4: Lees het resultaat De uiteindelijke reactie draagt het resultaat. Bewaar `api_reference_id` voor latere oproepen. ``` { "data": { "api_reference_id": "b8e74ec5-7de3-4d4b-8cbc-b2945f7aeb56", "articles_created": 19, "categories_created": 3, "errors": [], "alerts": [], "background_task_id": "c02535d8-f051-41d3-92a9-57a224022f7d", "is_processing": false }, "success": true } ``` Lees bevindingen uit `data.errors`, en waarschuwingen van `data.alerts`. Voor een hersynchronisatie worden `data.deleted_endpoints` de verwijderde eindpunten vermeld, met de `method`, `path`, `article_id`, en `title` van elk. --- ## Migreer de d360 CLI en CI/CD-pijplijnen De CLI heeft twee commandofamilies: V3 (`apiref`) en v2 (`apidocs`). Blijf binnen je huidige familie wanneer je migreert. Vervang V3-commando's door V3-commando's en v2-commando's door v2-commando's. ### Stap 1: Upgrade de CLI De nieuwe commando's vereisen versie **3.0.7** of later. ``` npm install -g d360@latest d360 --version ``` De oude commando's (, , , ) `apidocs:resync`zijn gemarkeerd `[DEPRECATED]` in `--help`. Ze stoppen met werken wanneer de eindpunten die ze aanroepen worden verwijderd.`d360 apidocs:validate` is niet verouderd. `apidocs``apiref resync``apiref import` ### Stap 2: Controleer of je het juiste certificaat gebruikt Beide families lezen dezelfde `D360_API_KEY` variabelenaam, maar verwachten elk een ander inlog. Het gebruik van de verkeerde is de meest voorkomende installatiefout. De CLI geeft je aan wanneer het het verkeerde inloggegevens detecteert. | | V3-commando's (`apiref`, `operations`) | v2-commando's (`apidocs`, `apidocs:submit`, ) `apidocs:status` | | --- | --- | --- | | Geloofsbrieven | Een V3 API-sleutel beginnend met `d360_sk_`, gemaakt onder **Settings** > **Knowledge Base-portaal** > **API-sleutels** | De CI/CD API-sleutel van het project (een GUID) | | Verzonden als | `X-API-Key` Header | `api_token` | | Ook nodig | Project-ID (`--project-id` of `d360 config set-project-id`), plus de workspace-ID (import) of API-referentie-ID (resync) | Gebruikers-ID (`--userId`), plus de workspace-ID (`--versionId`, import) of API-referentie-ID (`--apiReferenceId`, resync). Geen project-ID. | | Toestemmingen | **Werk artikelen bij** om in te sturen, **bekijk de projectinstellingen** om te pollen. Een ontbrekende sleutel kan het resultaat indienen maar niet lezen, of andersom. | Dezelfde sleutel wordt gebruikt voor verzenden en status | De CLI heeft geen interactieve login. Het neemt de API-sleutel van de eerste bron die wordt ingesteld: een commando-vlag, een omgevingsvariabele (`D360_API_KEY`, , ), `D360_BASE_URL`dan de opgeslagen configuratie (`d360 init`, of `d360 config set-key` en `d360 config set-project-id`). In een pipeline sla je de sleutel op in je CI-geheime opslag en geef je deze door als een omgevingsvariabele. Gebruik de basis-URL `D360_PROJECT_ID`voor je regio. ### Stap 3: Vervang je commando's #### Als je V3-commando's gebruikt Vervang beide `apiref import` en `apiref resync` met `apiref submit`. De ID die je doorgeeft bepaalt de operatie: `--workspace-id` importeert, `--api-reference-id` resynct. Voor: ``` d360 apiref import --workspace-id --url https://api.example.com/openapi.json d360 apiref resync --api-reference-id --url https://api.example.com/openapi.json ``` Na: ``` # Import a new API reference and wait for the result d360 apiref submit --workspace-id --url https://api.example.com/openapi.json --wait # Resync an existing API reference from a local file and wait d360 apiref submit --api-reference-id --file ./openapi.json --wait # Submit now and poll separately, for example from another pipeline stage id=$(d360 apiref submit --workspace-id --file ./openapi.json \ --filter operation_id -o tsv) d360 operations wait "$id" ``` Werk je vlaggen bij: | | Oud | Nieuw | | --- | --- | --- | | Importeren of opnieuw synchroniseren | Twee commando's | Eén commando: `--workspace-id` importeert, `--api-reference-id` resynct | | Specificatiebron | Import: `--url` of `--content`. Resync: `--url` | `--url` of `--file` voor beide | | Publiceren na import | `--publish-articles` | `--publish-articles` met `--user-id` (vereist) | | Waarschuwingen | | `--force-import` Om door te gaan met voorbij waarschuwingen (standaard uitgeschakeld) | | Resultaat | In de reactie | `--wait`, of `d360 operations wait <operation-id>` | De `--filter` vlag volgt een pad naar de responsgegevens. Gebruik `operation_id`, niet `data.operation_id`. De `-o tsv` optie print de kale ID af. `--wait` en `d360 operations wait` vertrekken `0` wanneer de operatie slaagt. Ze vertrekken `1` als deze mislukt of het wachtbudget van 20 minuten is af. Een budgettimeout stopt het wachten, maar annuleert de operatie niet. #### Als je v2 (apidocs) commando's gebruikt, Dit zijn de commando's die worden weergegeven voor CI/CD in de **referentiepanelen Add API** en **Edit API** van het portaal. Vervang beide `apidocs` en `apidocs:resync` door `apidocs:submit`, lees het resultaat vervolgens met `apidocs:status`. De vlagnamen blijven hetzelfde (camelCase), en je behoudt de CI/CD-sleutel. Voor: ``` d360 apidocs --apiKey "$D360_CICD_KEY" --userId --versionId \ --path ./openapi.json d360 apidocs:resync --apiKey "$D360_CICD_KEY" --userId \ --apiReferenceId --path ./openapi.json ``` Na: ``` # Import (prints the task ID on its own line) d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId --versionId \ --path ./openapi.json # Resync (passing --apiReferenceId makes it a resync) d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId \ --apiReferenceId --path ./openapi.json # Wait for the job to finish d360 apidocs:status --apiKey "$D360_CICD_KEY" --wait ``` `apidocs:submit`accepteert dezelfde vlaggen als het oude `apidocs` commando: `--apiKey`, `--userId`, , `--versionId`, `--apiReferenceId`, `--path``--force`, `--publish`, , en `--apihubUrl`. Het print een taak-ID en sluit af. `apidocs:status` neemt alleen `--apiKey`, plus `--apihubUrl` voor niet-EU-regio's. Gate je pipeline altijd op `--wait`. Zonder deze commando rapporteert het commando één keer en sluit `0` het af, zelfs als de taak nog draait. Met `--wait`, pollt het totdat de taak klaar is, print de bevindingen (fouten, meldingen en eventuele eindpunten die door een hersynchronisatie zijn verwijderd), en sluit `1` af als de taak niet succesvol is. Als een hersynchronisatie eindpunten zou verwijderen, stopt het en vermeldt het ze. Voer opnieuw uit met `--force` om het te bevestigen. ### Stap 4: Update je pijplijn Gebruik een van deze GitHub Actions-stappen als uitgangspunt. In beide faalt de stap wanneer de taak faalt, en worden de bevindingen in het logboek afgedrukt. V3: ``` - name: Publish API reference (V3) env: D360_API_KEY: ${{ secrets.D360_API_KEY }} # a d360_sk_ key D360_PROJECT_ID: ${{ vars.D360_PROJECT_ID }} run: | npm install -g d360@latest d360 apiref submit --api-reference-id "${{ vars.D360_API_REFERENCE_ID }}" \ --file ./openapi.json --wait ``` v2 (`apidocs`): ``` - name: Publish API reference (v2) env: D360_CICD_KEY: ${{ secrets.D360_CICD_KEY }} # the project's CI/CD key run: | npm install -g d360@latest task=$(d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId "${{ vars.D360_USER_ID }}" \ --apiReferenceId "${{ vars.D360_API_REFERENCE_ID }}" --path ./openapi.json) d360 apidocs:status "$task" --apiKey "$D360_CICD_KEY" --wait ``` --- ## Los veelvoorkomende problemen op nadat je bent gemigrerd | Wat je ziet | Waarom het gebeurt | Wat te doen | | --- | --- | --- | | Peilingen komen terug `403` na een succesvolle inzending | Je key of rol kan artikelen bijwerken, maar kan de projectinstellingen niet bekijken | Geef de integratie beide rechten | | Dien aangiften in `409 Conflict` | Er draait al een andere import of resync in het project. Er kan er maar één tegelijk draaien. | Poll de lopende taak die in het antwoord is genoemd en probeer het dan opnieuw | | Het opnieuw indienen geeft dezelfde bewerkings-ID terug | Je stuurde een identiek verzoek terwijl de eerste nog draaide | Poll de teruggegeven operatie. Er wordt geen tweede import gestart. | | Een V3-import of resync die vroeger werkte, wordt nu geweigerd | `force_import` nu standaard op `false` alle V3-routes, inclusief de verouderde | Fix de bevindingen, of stel het bewust in. `force_import: true` [Zie Bepaal hoe je met bevindingen omgaat](/docs/nl/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). | | Een hersynchronisatie mislukt met *"Deze update zal permanent verwijderen..."* | De resync verwijderde eindpunten | Bekijk de vermelde eindpunten en dien vervolgens opnieuw in met `force_import: true` (V3), `forceImport=true` (v2), `--force-import` (), (`apiref submit`), of `--force` (`apidocs:submit`) om te bevestigen | | A indienen time-out of retourneerend `5xx` | Het verzoek kan wel of niet zijn geaccepteerd | Probeer het niet meteen opnieuw. Een herpoging kan een tweede import starten. Controleer of er een lopende bewerking is met `GET /v3/projects/{projectId}/operations?status=running`, of poll de operatie-ID als je die hebt. | De CLI volgt dezelfde retry-regel. Het probeert geen verzending opnieuw na een `5xx` of een verbroken verbinding. Het probeert alleen een `429`, die wordt afgewezen voordat er werk begint. --- ## Controleer je migratie Uw migratie is voltooid wanneer: - Elke import- en resync-aanroep gebruikt een asynchroon eindpunt of commando. - Je integratie leest de uitkomst uit het status-eindpunt, niet uit de `202` respons. - Op V3 gebruikt `operation_id` je integratie in plaats van `data.id` en `data.status` uit het submit response. - Je integratie regelt `409 Conflict` het door te wachten tot de taak draait en het opnieuw te proberen. - Je hebt gekozen hoe je met bevindingen omgaat: de specificatie corrigeren, of bewust instellen `force_import: true` . - Je API-sleutel of rol kan zowel operaties verzenden als lezen. - Je CLI staat op versie 3.0.7 of later, en elke familie gebruikt zijn eigen credential: een `d360_sk_` sleutel voor `apiref`, en de CI/CD-sleutel voor `apidocs`. - Je pijplijn faalt in de stap wanneer een import of hersynchronisatie mislukt. - Je hebt de migratie voltooid voordat de oude eindpunten en commando's eind maart 2027 worden verwijderd. Application Programming Interface - A set of defined rules and protocols that allows one software application to communicate with and request functionality from another. APIs are the backbone of modern integrations. When Document360 connects to Slack, Intercom, or Google Analytics, it does so through their APIs. Document360 also provides its own REST API, enabling teams to programmatically manage articles, categories, and reader accounts from external systems.