Auf der nuqo-API aufbauen

1Was die API kann

Mit der API lesen Ihre eigenen Systeme — ein ERP, die Middleware davor, eine Fertigungsplanung oder ein Skript — was Ihr Betrieb in nuqo entschieden hat, ohne dass jemand es vom Bildschirm abschreibt. Sie dient vor allem dem Lesen: Ihr System fragt, nuqo antwortet. Annehmen kann sie nur eines: Ihre Teile, aus Ihrem ERP.

2Anmelden

1. Schlüssel anlegen. In nuqo öffnet ein Inhaber oder Admin Ihres Betriebs Einstellungen → API-Schlüssel, gibt dem Schlüssel einen Namen (etwa „ERP-Middleware“) und legt ihn an. Der Schlüssel wird einmal angezeigt: nq_live_ und 43 Zeichen. Legen Sie ihn in Ihrem Geheimnisspeicher ab.
2. Mit jeder Anfrage senden, als Authorization: Bearer nq_live_…. Kein Cookie, kein CSRF-Token. Jede Adresse beginnt mit https://backend.nuqo.io/api/v1.
3. Prüfen. GET /organization antwortet den Betrieb, dem der Schlüssel gehört.

curl https://backend.nuqo.io/api/v1/organization \
  -H "Authorization: Bearer $NUQO_KEY"

{ "id": 318, "name": "Example Assemblies Inc" }

Widerrufen Sie ihn unter Einstellungen → API-Schlüssel; er gilt sofort nicht mehr. Ein verlorener Schlüssel lässt sich nicht noch einmal anzeigen: legen Sie einen neuen an, stellen Sie Ihr System um und widerrufen Sie dann den alten.

Ein Schlüssel handelt als Ihr Betrieb, nie als eine Person, und sieht nur die Daten Ihres Betriebs. Jeder Schlüssel kann lesen. Ein Schlüssel, bei dem Ihr Admin „Darf auch Teile senden“ angekreuzt hat, kann Ihre Teile auch an nuqo senden: siehe Ihre Teile an nuqo senden.

3Finalisierte Angebote lesen

Die Liste

GET /quotes antwortet Ihre finalisierten Angebote, die älteste Finalisierung zuerst, 50 je Seite (limit bis 100). Blättern Sie mit next_cursor, solange has_more true ist. Dann behalten Sie den letzten next_cursor und fragen damit später wieder: er setzt nach dem letzten gesehenen Angebot fort, Sie bekommen also nur, was seither finalisiert wurde. Ein Cursor ist undurchsichtig — geben Sie ihn unverändert zurück, bauen Sie nie selbst einen. Um ab einem Datum zu beginnen, senden Sie stattdessen finalized_since; zusammen mit einem Cursor gesendet, gilt beides.

curl "https://backend.nuqo.io/api/v1/quotes?finalized_since=2026-10-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $NUQO_KEY"

{
  "quotes": [
    {
      "id": 5087,
      "number": "139-1",
      "revision": 1,
      "finalized_at": "2026-10-14T08:52:40.611093Z",
      "valid_until": null,
      "customer": null,
      "total": { "amount": 3920.5, "currency": "EUR" }
    },
    {
      "id": 5120,
      "number": "147-2",
      "revision": 2,
      "finalized_at": "2026-10-20T14:03:11.204518Z",
      "valid_until": "2026-11-19T22:59:59Z",
      "customer": { "id": 903, "name": "Sample Machines Ltd" },
      "total": { "amount": 21480, "currency": "EUR" }
    }
  ],
  "next_cursor": "MjAyNi0xMC0yMFQxNDowMzoxMS4yMDQ1MTgrMDA6MDB8NTEyMA",
  "has_more": false
}

Ein Angebot, das wieder geöffnet, überarbeitet und erneut finalisiert wurde, kommt später noch einmal, mit höherer revision und neuer number (147-2 nach 147-1): ersetzen Sie Ihre Kopie. Während es überarbeitet wird, steht es nicht in der Liste, und es zu lesen antwortet 409.

Ein Angebot und sein Arbeitsplan

GET /quotes/{quote_id} antwortet den Kopf, jede Baugruppe mit ihrem Arbeitsplan und die Stückliste. Die Namen, die nuqo vergibt (Baugruppen, Arbeitsplätze), kommen auf Englisch; mit ?lang=de auf Deutsch. Text aus den Unterlagen Ihres Kunden, etwa die Beschreibung einer Zeile, bleibt, wie er dort steht. Ein Entwurf, oder ein für eine Revision wieder geöffnetes Angebot, antwortet 409 quote_not_finalized. Ein finalisiertes Angebot ohne Arbeitsplan antwortet work_plan_available: false und keine Baugruppen. Jedes Feld steht in der Referenz; der Arbeitsplan ist der Teil, den die meisten Systeme zuerst abbilden:

Eine Auftragsposition je Baugruppe

Jede Baugruppe nennt ihren Preis wie ihre Zeile im Angebots-PDF: unit_price für ein Stück (per: "pcs") und amount für die bestellte quantity, netto, in der Währung von total. amount ist quantity × unit_price, so stimmt eine Auftragsposition aus den dreien mit dem PDF überein. Der Rest des Angebots steht nur in total: Rüstkosten, die die Zeilen nicht tragen, Versand, Zuschläge, der Rabatt und bei einem älteren Angebot sein Gesamtaufschlag. Eine Baugruppe, von der keine Stückzahl bestellt ist, hat unit_price: null und amount: null.

Die Stückliste

parts nennt jede Zeile der Stückliste des Angebots, in ihrer Reihenfolge — auch eine Zeile, für die nichts gefunden wurde (part: null). quantity ist, was der ganze Auftrag von dem Teil braucht; ordered ist, was gekauft wird, in derselben Einheit: der Bedarf, aufgerundet auf die Packung, die Mindestbestellmenge und das Bestellintervall des Lieferanten. Bestellen Sie ordered. unit_price ist der Listenpreis des Lieferanten je Einheit, in der Währung, in der das Teil gekauft wird; line_total ist, was der Kauf von ordered kostet, in der Währung des Angebots.

Seit dem 29. Oktober 2026 nennt eine Zeile, die in Fuß oder Zoll gezählt wird, ihren unit_price je Fuß oder je Zoll; per sagt, welches von beiden ("ft" oder "in"). Vorher stand er je Meter. Das ist eine einmalige Ausnahme von der Regel, dass sich unter /v1/ keine Bedeutung ändert — wir haben sie gemacht, solange noch kein Integrator die API nutzt.

4Ereignisse

Ereignisse sagen Ihrem System, welches Angebot es holen und welchen Auftrag es anhalten soll. Fragen Sie GET /events etwa jede Minute ab und senden Sie dabei die ID des zuletzt verarbeiteten Ereignisses als after (beim ersten Mal 0).

curl "https://backend.nuqo.io/api/v1/events?after=20870" \
  -H "Authorization: Bearer $NUQO_KEY"

{
  "data": [
    {
      "id": 20871,
      "type": "quote.reopened",
      "created_at": "2026-10-19T08:41:55.120334Z",
      "quote": { "id": 5120, "revision": 2 }
    },
    {
      "id": 20872,
      "type": "quote.finalized",
      "created_at": "2026-10-20T14:03:11.394120Z",
      "quote": { "id": 5120, "revision": 2 }
    }
  ],
  "next_after": 20872
}

• Speichern Sie next_after und senden Sie es beim nächsten Mal als after. Eine volle Seite (limit, standardmäßig 100) heißt, dass weitere warten: fragen Sie sofort noch einmal. Eine kürzere Seite ist vorerst das Ende.
• Erkennen Sie Doppelte an der id. Zugestellt wird mindestens einmal: scheitert Ihr System zwischen dem Verarbeiten eines Ereignisses und dem Speichern seiner ID, bekommt es das Ereignis noch einmal.
• Ignorieren Sie Typen, die Sie nicht kennen. Neue können hinzukommen.
• Ereignisse werden 30 Tage aufbewahrt. Ein älteres after antwortet die ältesten noch vorhandenen Ereignisse; holen Sie über die Angebotsliste auf.

5Teile abgleichen

Ihre Teile an nuqo senden

Ihr ERP sendet nuqo seine Teile — Preise, Bestand, Artikeldaten —, statt dass jemand eine Datei exportiert und hochlädt. Sie landen auf Ihrer Preisliste ERP-Sync, die nuqo wie jede andere Ihrer Preislisten gegen die übrigen abwägt. Sie brauchen einen Schlüssel, den ein Inhaber oder Admin unter Einstellungen → API-Schlüssel mit angekreuztem „Darf auch Teile senden“ angelegt hat; nachträglich lässt sich das nicht ankreuzen, und ein Schlüssel ohne es antwortet 403.

1. Einen Stapel senden, bis zu 1.000 Zeilen. Eine Zeile hat die Felder einer Zeile von GET /materials, unter denselben Namen; eine aus nuqo gelesene Zeile können Sie also unverändert zurücksenden. Pflicht sind mpn und manufacturer. Hersteller, mpn und supplier sagen, welches Teil eine Zeile ist; senden Sie also jedes Mal dieselben: eine Zeile ohne ihren Lieferanten ist ein anderes Teil. Jedes andere Feld, das eine Zeile weglässt oder als null sendet, behält den Wert, den nuqo hat, und ein Teil, das der Stapel weglässt, bleibt, wie es ist. valid_from und valid_to sind die Tage, für die die tiers der Zeile gelten; senden Sie sie also mit diesen Staffeln: Staffeln ohne sie gelten ab jetzt ohne Ende, Gültigkeitsdaten ohne Staffeln werden abgelehnt.

   Ein Teil, das Sie nicht mehr führen: senden Sie seine Zeile mit "removed": true, z. B. {"mpn": "1-968849-1", "manufacturer": "TE Connectivity", "supplier": {"name": "Example Supply", "sku": "ES-968849"}, "removed": true}. Es wird nicht mehr aus Ihrer Preisliste ERP-Sync kalkuliert; Ihre anderen Preislisten behalten ihren Eintrag. Hersteller, mpn und supplier sagen, welches Teil, wie bei jeder Zeile; die übrigen Felder der Zeile werden ignoriert. GET /materials liefert es weiter, mit prices_quotes false (nicht als obsolete: das ist ein Teil, das ein Nutzer gelöscht hat), und senden Sie seine Zeile wieder ohne removed, wird es wieder geführt. Entfernungen gelten nach den übrigen Zeilen des Stapels: ein Stapel, der dasselbe Teil sendet und entfernt, endet mit dem Teil entfernt.

   curl https://backend.nuqo.io/api/v1/materials/batches \
     -H "Authorization: Bearer $NUQO_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "rows": [
       {
         "org_sku": "A-10442",
         "mpn": "1-968849-1",
         "manufacturer": "TE Connectivity",
         "description": "Receptacle 2.8 mm, tin",
         "supplier": { "name": "Example Supply", "sku": "ES-968849" },
         "tiers": [{"min_qty": 1, "max_qty": null, "price": {"amount": 0.42, "currency": "EUR"}}],
         "valid_from": "2026-11-01",
         "valid_to": "2027-03-31",
         "quantity_in_stock": 4200
       }
     ]
   }'

   { "batch_id": 88214 }

   Der ganze Stapel wird geprüft, bevor etwas davon übernommen wird. Eine abgelehnte Zeile antwortet 422, und nichts wird eingereiht; die Meldung nennt die erste fehlerhafte Zeile, z. B. rows[3]: tiers.0.price.amount: Input should be a valid number …. Korrigieren Sie sie und senden Sie den Stapel erneut.

2. Den Stapel abfragen, alle paar Sekunden, solange sein status pending oder running ist.

   curl https://backend.nuqo.io/api/v1/materials/batches/88214 \
     -H "Authorization: Bearer $NUQO_KEY"

   { "id": 88214, "status": "done", "summary": {"rows": 1, "imported": 1, "removed": 0, "not_imported": []} }

   done trägt die summary: die gesendeten rows, wie viele imported und removed wurden, und in not_imported jede Zeile, die nuqo nicht geschrieben hat, mit ihrer Stelle (index) in Ihrem Stapel und dem Grund: auch eine Entfernung eines Teils, das Ihre Liste nicht führt („nothing to remove“). failed heißt, die Übernahme ist abgebrochen: senden Sie den Stapel erneut. Das ist gefahrlos: eine zweimal gesendete Zeile schreibt dasselbe Teil, und eine zweimal gesendete Entfernung findet nichts mehr zu entfernen. Solange ein Stapel aussteht oder läuft, antwortet ein weiterer 409 batch_in_progress: senden Sie ihn, sobald die Abfrage done sagt.

3. Zurücklesen mit GET /materials, changed_since auf eine Minute vor dem Senden des Stapels gesetzt, damit nichts fehlt, wenn Ihre Uhr vorgeht: jedes seither geänderte Teil, die des Stapels darunter, wie nuqo sie führt, mit nuqos listing_id und part_id. Eine Zeile, die nichts geändert hat, kommt nicht zurück. Eine Änderung wird geliefert, sobald sie 3 Minuten alt ist.

   curl "https://backend.nuqo.io/api/v1/materials?changed_since=2026-10-30T08:00:00Z" \
     -H "Authorization: Bearer $NUQO_KEY"

   {
     "materials": [
       {
         "listing_id": 918377,
         "part_id": 4410951,
         "catalogue": { "id": 131, "name": "ERP-Sync" },
         "org_sku": "A-10442",
         "mpn": "1-968849-1",
         "manufacturer": "TE Connectivity",
         "description": "Receptacle 2.8 mm, tin",
         "category_leaf": null,
         "supplier": { "name": "Example Supply", "sku": "ES-968849" },
         "tiers": [{"min_qty": 1, "max_qty": null, "price": {"amount": 0.42, "currency": "EUR"}}],
         "unit_price": { "amount": 0.42, "currency": "EUR", "per": "pcs" },
         "valid_from": "2026-11-01",
         "valid_to": "2027-03-31",
         "order_unit": null,
         "content_unit": "pcs",
         "no_cu_per_ou": 1,
         "price_quantity": 1,
         "minimum_order_quantity": null,
         "order_multiple": null,
         "lead_time_days": null,
         "quantity_in_stock": 4200,
         "notes": null,
         "prices_quotes": true,
         "status": "active",
         "changed_at": "2026-10-30T08:00:41.208113Z"
       }
     ],
     "next_cursor": "MjAyNi0xMC0zMFQwODowMDo0MS4yMDgxMTMrMDA6MDB8NDQxMDk1MXw5MTgzNzc",
     "has_more": false
   }

Die erste vollständige Übernahme ist dasselbe, viele Male: senden Sie Stapel von bis zu 1.000 Zeilen nacheinander, jeden bis done abgefragt, bevor der nächste kommt.

Ihre Teile aus nuqo lesen

GET /materials antwortet die Zeilen Ihres Reiters Materialien in nuqo, mit denselben Werten, die am längsten unveränderte zuerst.

1. Zuerst ein vollständiger Abruf: ohne changed_since, mit include_removed=true, blätternd mit next_cursor, solange has_more true ist. Ein Teil, das sich während des Abrufs ändert, kommt weiter hinten noch einmal, mit den neuen Werten: ersetzen Sie Ihre Kopie.
2. Dann die Änderungen: behalten Sie den letzten next_cursor und fragen damit wieder (mit include_removed=true). Sie bekommen die seither angelegten, bearbeiteten, neu bepreisten oder gelöschten Teile. Eine Änderung wird geliefert, sobald sie 3 Minuten alt ist.
3. Nachts ein vollständiger Abruf mit Abgleich. Er findet die wenigen Änderungen, die keine Abfrage der Änderungen zeigen kann: ein Teil aus nuqos globalem Katalog, das Sie aus Ihren Teilen entfernt haben, ist weg statt markiert, und nuqos eigene Pflege (ein zusammengeführter Herstellername, eine neu zugeordnete Kategorie) ändert den Änderungszeitpunkt eines Teils nicht.

curl "https://backend.nuqo.io/api/v1/materials?include_removed=true&limit=100" \
  -H "Authorization: Bearer $NUQO_KEY"

{
  "materials": [
    {
      "listing_id": 918204,
      "part_id": 4410273,
      "catalogue": { "id": 112, "name": "Example Supply 2026" },
      "org_sku": "300-118",
      "mpn": "EX-H4",
      "manufacturer": "Example Housings",
      "description": "Housing, 4 pole, black",
      "category_leaf": "Connectors > Housings",
      "supplier": { "name": "Example Supply", "sku": "ES-H4-01" },
      "tiers": [
        { "min_qty": 1, "max_qty": 499, "price": {"amount": 1.58, "currency": "EUR"} },
        { "min_qty": 500, "max_qty": null, "price": {"amount": 1.42, "currency": "EUR"} }
      ],
      "unit_price": { "amount": 1.58, "currency": "EUR", "per": "pcs" },
      "valid_from": "2026-01-01",
      "valid_to": "2026-12-31",
      "order_unit": null,
      "content_unit": "pcs",
      "no_cu_per_ou": 1,
      "price_quantity": 1,
      "minimum_order_quantity": 100,
      "order_multiple": 50,
      "lead_time_days": 14,
      "quantity_in_stock": 2400,
      "notes": null,
      "prices_quotes": true,
      "status": "active",
      "changed_at": "2026-10-21T16:20:05.774812Z"
    }
  ],
  "next_cursor": "MjAyNi0xMC0yMVQxNjoyMDowNS43NzQ4MTIrMDA6MDB8NDQxMDI3Mw",
  "has_more": false
}

Die Identität eines Teils ist part_id. org_sku ist Ihre Artikelnummer, wo Sie eine gesetzt haben, aber zwei Teile können sie teilen, sie ist also kein Schlüssel. Ein vollständiger Abruf ist eine Anfrage je 100 Teile: 24.000 Teile sind 240 Anfragen, etwa zwei Minuten innerhalb des Limits.

6Fehler, Limits und Änderungen

Ein Fehler antwortet einen festen code für Ihr Programm und eine message für Menschen, deren Wortlaut sich ändern kann.

{
  "error": { "code": "quote_not_finalized", "message": "The quote is a draft or a revision in progress." }
}

Außer der Antwort 1010 oben trägt nur ein Serverfehler, 500, diesen Inhalt nicht. Behandeln Sie jede Antwort ohne code nach ihrem Status. Wiederholen Sie einen 500, einen 502–504 oder einen Netzwerkfehler mit wachsender Wartezeit (etwa 2, 4, 8 … Sekunden, fünfmal), dann geben Sie bis zum nächsten Lauf auf.

Limit

120 Anfragen pro Minute je Schlüssel, über alle Adressen. Darüber antwortet die API 429 rate_limited mit einem Header Retry-After, der die ganzen Sekunden bis zum nächsten Versuch nennt.

Wie sich die API ändert

• Ergänzungen kommen ohne Ankündigung. Ein neues Feld, eine neue Adresse, ein neuer Parameter oder Ereignistyp kann jederzeit erscheinen. Ihr System ignoriert, was es nicht liest.
• Ein Feld geht langsam. Es wird hier und in einem Header der Antwort als veraltet markiert, in den Neuigkeiten angekündigt und frühestens 6 Monate später entfernt.
• Ein echter Bruch kommt als /v2/ neben /v1/, das weiterläuft, während Sie umstellen. Eine Prüfung bei jeder unserer Änderungen weist alles andere zurück.

7Was wir über Ihr System annehmen

Wir haben v1 auf diesen Annahmen gebaut. Sagen Sie uns, welche für Ihr System zutreffen, und korrigieren Sie die anderen — die Nummern genügen.

1. A1
   Ereignisse

   Ihr System fragt GET /events regelmäßig ab, oder es kann HTTPS-Aufrufe aus dem Internet annehmen.

   Wenn nicht: Sagen Sie uns, was zutrifft. Nimmt es eingehende HTTPS-Aufrufe an, rücken Webhooks auf unserer Liste nach oben.

2. A2
   Anmeldung

   Ein fester Schlüssel im Authorization-Header ist für Ihr System in Ordnung.

   Wenn nicht: Sagen Sie uns, was es braucht (z. B. OAuth2 Client Credentials).

3. A3
   Angebote

   Ihr ERP führt eine Baugruppe unter Ihrer eigenen Nummer dafür, shop_part_number, und sie ist auf jedem Angebot gesetzt, das Sie finalisieren.

   Wenn nicht: Sagen Sie uns, unter welcher Nummer Ihr ERP einen Arbeitsplan ablegt.

4. A4
   Arbeitsplan

   Eine Zeile des Arbeitsplans ohne Arbeitsplatz (work_center_id: null, mit Name und Zeit) ist annehmbar.

   Wenn nicht: Jede Zeile muss einen Arbeitsplatz nennen, und wir brauchen von Ihnen einen Standard-Arbeitsplatz.

5. A5
   Revisionen

   Eine höhere Revision eines Angebots ersetzt den Plan, den Sie dafür haben.

   Wenn nicht: Sagen Sie uns, wie Ihr ERP Revisionen nebeneinander führt.

6. A6
   Teile abgleichen

   Ihr ERP führt bei Preisen, Bestand, Lieferzeit und Artikeldaten.

   Wenn nicht: Nennen Sie die Gruppen, bei denen nuqo führen soll.

7. A7
   Teile abgleichen

   Ihre Artikelnummer (org_sku) ist Ihr Schlüssel für ein Teil.

   Wenn nicht: Sagen Sie uns, welches Feld es ist.

8. A8
   Teile abgleichen

   Einige tausend Teile, einmal am Tag abgeglichen, und in nuqo angelegte Teile müssen in Ihrem ERP keine neuen Artikel werden.

   Wenn nicht: Nennen Sie uns die Zahl der Teile, wie oft, und ob neue Teile zurückfließen sollen.