API
Die Nori-API ist eine GraphQL-API – ein einziger Endpunkt, über den du genau die Daten abfragst und Aktionen auslöst, die du brauchst.
Unsere API basiert auf GraphQL. Der zentrale Endpunkt ist https://api.noridocs.com/graphql. Unter api.noridocs.com stellen wir zusätzlich einen interaktiven Playground bereit. Dort testest du Queries und Mutations direkt im Browser – mit Schema-Autovervollständigung und Dokumentation, ohne eine Zeile Code zu schreiben.
Authentifizierung
Die meisten Felder erfordern ein Bearer-Token im Authorization-Header. Den Connectivity-Check noriPing erreichst du ohne Token – ideal, um die Verbindung zu prüfen:
query {
noriPing
}Beispiel: Query
Eine Query fragt genau die Felder ab, die du brauchst. Hier die offenen Rechnungen mit Kunde:
query {
noriInvoices(status: "open", first: 10) {
data {
id
number
title
status
customer { name }
}
paginatorInfo { total }
}
}{
"data": {
"noriInvoices": {
"data": [
{
"id": "1024",
"number": "2025-0007",
"title": "Website Relaunch",
"status": "open",
"customer": { "name": "Acme Studio" }
}
],
"paginatorInfo": { "total": 1 }
}
}
}Beispiel: Mutation
Mit einer Mutation legst du Daten an oder veränderst sie – zum Beispiel eine neue Rechnung im Entwurf:
mutation {
noriCreateInvoice(input: {
customer_id: "42"
title: "Website Relaunch"
currency: "EUR"
lines: [
{ title: "Design", quantity: 1, unit_price_cents: 250000 }
{ title: "Entwicklung", quantity: 1, unit_price_cents: 800000 }
]
}) {
id
number
status
}
}{
"data": {
"noriCreateInvoice": {
"id": "1025",
"number": null,
"status": "draft"
}
}
}Requests senden
GraphQL läuft über einen einzigen POST-Request. Du schickst ein JSON mit den Feldern query und optional variables. So sieht das mit cURL aus – einmal als Query, einmal als Mutation:
# Query: aktueller Nutzer
curl https://api.noridocs.com/graphql \
-H "Authorization: Bearer DEIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"query { me { id name email } }"}'
# Mutation: Rechnung anlegen (mit Variablen)
curl https://api.noridocs.com/graphql \
-H "Authorization: Bearer DEIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "mutation ($input: NoriCreateInvoiceInput!) { noriCreateInvoice(input: $input) { id number status } }",
"variables": { "input": { "customer_id": "42", "lines": [{ "title": "Design", "quantity": 1, "unit_price_cents": 250000 }] } }
}'In JavaScript definierst du dir am besten einen kleinen Helper – einmal geschrieben, überall genutzt:
// Einmal definieren – für Query und Mutation gleichermaßen.
async function nori(query, variables = {}) {
const res = await fetch('https://api.noridocs.com/graphql', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.NORI_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ query, variables }),
});
const { data, errors } = await res.json();
if (errors) throw new Error(errors[0].message);
return data;
}
// Query
const { me } = await nori(`query { me { id name email } }`);
// Mutation
const { noriCreateInvoice } = await nori(
`mutation ($input: NoriCreateInvoiceInput!) {
noriCreateInvoice(input: $input) { id number status }
}`,
{ input: { customer_id: '42', lines: [{ title: 'Design', quantity: 1, unit_price_cents: 250000 }] } },
);Schnell loslegen mit einem Client
Für den produktiven Einsatz nimmst du am besten einen schlanken GraphQL-Client. graphql-request ist winzig, kennt Variablen und macht Queries wie Mutations zum Einzeiler:
import { GraphQLClient, gql } from 'graphql-request';
const client = new GraphQLClient('https://api.noridocs.com/graphql', {
headers: { Authorization: `Bearer ${process.env.NORI_TOKEN}` },
});
// Query
const { me } = await client.request(gql`
query { me { id name email } }
`);
// Mutation
const { noriCreateInvoice } = await client.request(
gql`
mutation ($input: NoriCreateInvoiceInput!) {
noriCreateInvoice(input: $input) { id number status }
}
`,
{ input: { customer_id: '42', lines: [{ title: 'Design', quantity: 1, unit_price_cents: 250000 }] } },
);