Was ist die Kigo Cloud API

Die Kigo Cloud API ist eine Programmierschnittstelle (REST, JSON-Format), ueber die sich externe Systeme mit Ihrem Kigo Cloud Konto verbinden. Am haeufigsten nutzen sie Webshops und andere Geschaeftsprogramme fuer den automatischen Datenaustausch: Synchronisierung von Artikeln und Bestaenden, Uebertragung von Kunden sowie Erstellung und Fiskalisierung von Rechnungen direkt aus Bestellungen, ohne manuelles Abtippen.

Basisinformationen

Sie erreichen die interaktive Dokumentation auch aus der Anwendung: Optionen → Integrationen → API-Dokumentation.

Authentifizierung

Jeder Aufruf sendet zwei Header:

• X-USERNAME: der Benutzername, mit dem Sie sich bei Kigo Cloud anmelden.
• X-PASSWORD: das Passwort desselben Benutzers als MD5-Hash (32 Zeichen), nie im Klartext.

Das Benutzerkonto muss aktiv sein. Beispielaufruf, der die Artikelliste abruft:

curl -H "X-USERNAME: ihr-benutzername" -H "X-PASSWORD: md5-hash-des-passworts" https://app.kigo.cloud/en/api/v1/item/list

Alle verfuegbaren Aufrufe

Artikelgruppen

Artikel

Kunden

Rechnungen und Angebote

Zahlungsarten und Zahlungsstatus

Rechnung ueber die API erstellen

Der wichtigste Aufruf fuer Webshops ist POST invoice/create. Die Schluesselfelder:

• pin: PIN eines aktiven Mitarbeiters; das Dokument bekommt diesen Bediener. Pflichtfeld.
• pos_type: 1 Rechnung, 2 Angebot (Standard), 3 Serviceangebot, 4 Einkaufsangebot. Fuer eine echte Rechnung immer 1 senden.
• payment: G Bargeld, T Ueberweisung (Standard), K Karte, O Sonstiges. Fuer Karte senden Sie auch id_payment_card, fuer Sonstiges id_payment_other: die IDs kommen aus paymentCard/list und paymentOther/list, eine unbekannte ID ergibt einen Fehler. Bargeld, Karte und Sonstiges werden sofort als bezahlt markiert; eine Ueberweisungsrechnung bleibt unbezahlt, bis Sie die Zahlung erfassen. Nur Dokumente mit T koennen spaeter als eRechnung gesendet werden.
• items: Rechnungspositionen, hoechstens 200 je Dokument. Der Artikel wird ueber die Referenz gesucht; ohne gesendete Referenz ueber den Namen (item_name). Wird nichts gefunden, wird automatisch ein neuer Artikel in Ihrem Artikelstamm angelegt: mit der gesendeten oder einer zugewiesenen Referenz, der MwSt aus vat_percent oder 25% und der allgemeinen Gruppe. Dieselbe Referenz zweimal gesendet addiert die Mengen auf einer Position. Alle Preise werden inklusive MwSt gesendet; ohne gesendeten Preis gilt der Verkaufspreis des Artikels. item_name bei einem bestehenden Artikel aendert die Bezeichnung nur auf dieser Position, nicht im Artikelstamm.
• Rabatte: senden Sie discount_percent, gilt genau dieser Prozentsatz (0 bedeutet kein Rabatt). Senden Sie keinen Rabatt, aber einen Preis unter dem Verkaufspreis des Artikels, wird die Differenz auf der Rechnung automatisch als Rabatt ausgewiesen. Preis 0 macht die Position gratis (100% Rabatt). Mit apply_client_discounts erhalten Positionen ohne Rabatt den Kundenrabatt, oder den Gruppenrabatt, wenn der Kunde keinen hat.
• client: wird nur verarbeitet, wenn er oib enthaelt; darueber wird der Kaeufer erkannt, und existiert er nicht, wird er automatisch aus den gesendeten Daten angelegt (Name, Adresse, Kontakt, E-Mail). Ohne OIB wird die Rechnung ohne Kaeufer ausgestellt, was fuer eine B2C-Einzelhandelsrechnung in Ordnung ist. Ein neuer Kaeufer ist standardmaessig eine Firma; das Feld client_vat_type aendert das: 0 Firma, 1 Privatperson, 2 oeffentliche Einrichtung, 3 EU-Firma, 4 Firma ausserhalb der EU. Der Kaeufertyp bestimmt die Fiskalisierung von Ueberweisungsrechnungen, siehe f1 und F2 unten.
• internal_number: die Bestellnummer aus Ihrem System. Eindeutig je Dokumenttyp: existiert bereits ein Dokument mit derselben Nummer, gibt die API Fehler 400 zurueck und erstellt kein Duplikat. Wiederholungen nach einem Verbindungsabbruch sind daher sicher.

Beispiel 1: Bar-Einzelhandelsrechnung (f1), ohne Kaeufer. Wird sofort fiskalisiert (jir und zki in der Antwort), als bezahlt markiert und in die Kasse eingetragen:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "G",
  "items": [ { "reference": "ART-001", "quantity": 2 } ]
}

Beispiel 2: Ueberweisungsrechnung an eine Firma (F2, eRechnung). Kein jir/zki in der Antwort, die Rechnung bleibt unbezahlt bis Sie die Zahlung erfassen, und auf der Rechnungsliste wartet sie auf den Versand als eRechnung. Das Beispiel sendet kein client_vat_type, der neue Kaeufer wird daher als Firma (Standardwert 0) gespeichert, und genau deshalb geht die Rechnung als F2; fuer eine Privatperson wuerden Sie client_vat_type 1 senden und die Rechnung waere f1. Der OIB im Beispiel besteht die Pruefziffer: mit einem ungueltigen OIB wuerde der Kaeufer als Privatperson gespeichert und die Rechnung ginge ebenfalls als f1, mit Fiskalisierung:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "T",
  "internal_number": "WEB-1001",
  "due_date": "2026-09-15",
  "client": { "oib": "12345678903", "company_name": "Firma GmbH", "street": "Ilica", "house_number": "1", "city": "Zagreb", "zip": "10000" },
  "items": [ { "reference": "ART-001", "quantity": 2, "price": 25.00 } ]
}

Beispiel 3: Rabatte je Position. Die erste Position erhaelt genau 10%, bei der zweiten wird der Rabatt aus dem gesenkten Preis gegen den Verkaufspreis berechnet, die dritte ist gratis (100%), und die vierte, ohne Angaben, erhaelt den Gruppenrabatt des Artikels, weil apply_client_discounts aktiv ist; hat die Rechnung auch einen Kaeufer mit Rabatt, hat dessen Rabatt Vorrang vor dem Gruppenrabatt:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "G",
  "apply_client_discounts": true,
  "items": [
    { "reference": "ART-001", "quantity": 1, "discount_percent": 10 },
    { "reference": "ART-002", "quantity": 1, "price": 80.00 },
    { "reference": "ART-003", "quantity": 1, "price": 0 },
    { "reference": "ART-004", "quantity": 1 }
  ]
}

Das Ergebnis dieser Anfrage, unter der Annahme, dass die Artikel einen Verkaufspreis von 100,00 haben (ART-003 50,00) und die Gruppe von ART-004 5% Rabatt:

• ART-001: genau 10% Rabatt, berechnet werden 90,00.
• ART-002: gesendeter Preis 80,00 bei Verkaufspreis 100,00, auf der Position wird daher automatisch 20% Rabatt ausgewiesen und 80,00 berechnet.
• ART-003: Preis 0 macht die Position gratis: 100% Rabatt, berechnet werden 0,00.
• ART-004: nichts gesendet, daher wendet apply_client_discounts den Gruppenrabatt von 5% an und berechnet werden 95,00.

Die Antwort: das Feld data enthaelt id_pos, pos_number, die Betraege (price, tax_pdv), Zahlungsart und Zahlungsstatus sowie die Fiskaldaten jir und zki mit QR-Code-Link (qrcode_link). Ein gefuelltes jir Feld bedeutet, dass die Rechnung erfolgreich fiskalisiert wurde.

PDF und Versand an den Kaeufer: die Antwort enthaelt keine fertige PDF-URL. Das PDF holen Sie mit einem separaten Aufruf GET invoice/getAsPdf/{id}, wobei {id} der Wert id_pos aus der Antwort ist (nicht pos_number); die Antwort dieses Aufrufs ist die PDF-Datei selbst. Die API sendet die Rechnung nicht per E-Mail an den Kaeufer (die email aus dem client Block wird nur beim Kunden gespeichert), der Versand an den Kaeufer erfolgt also aus Ihrem System mit dem geholten PDF.

Fiskalisierung: welche Rechnung ist f1, welche F2 und welche NF

Jede Rechnung (pos_type 1) erhaelt beim Abschluss automatisch eine Fiskalisierungskennzeichnung nach Zahlungsart und Kaeufertyp; Angebote werden nie fiskalisiert. Dieselben Kennzeichen sehen Sie auch auf der Liste der ausgestellten Rechnungen.

• f1 (klassische Fiskalisierung): Rechnungen mit Bargeld, Karte oder sonstiger Zahlung, unabhaengig vom Kaeufer, sowie Ueberweisungsrechnungen an eine Privatperson oder ohne Kaeufer. Die Rechnung wird sofort fiskalisiert und erhaelt ZKI und JIR: die Felder zki und jir in der Antwort sind gefuellt. Dafuer muss in der Anwendung ein Fiskalzertifikat geladen sein.
• F2 (Fiskalisierung 2.0, eRechnungspflicht): eine Ueberweisungsrechnung (payment T) an eine inlaendische Firma oder oeffentliche Einrichtung mit gueltigem OIB. Sie erhaelt bei Ausstellung keinen JIR (jir und zki bleiben in der Antwort leer), sondern wird als eRechnung gesendet: auf der Rechnungsliste traegt sie die F2-Kennzeichnung, rot bis die eRechnung gesendet ist, gruen danach.
• NF (nicht fiskalisiert): eine Rechnung, die keinem von beiden unterliegt, zum Beispiel eine Ueberweisungsrechnung an eine auslaendische Firma oder eine Barrechnung, deren Positionen alle unter Reverse Charge fallen.

Rechnung stornieren

Der Aufruf POST invoice/cancel mit Mitarbeiter-pin und id_pos (Dokument-ID) erstellt ein Stornodokument, genau wie das Stornieren in der Anwendung, und gibt es in der Antwort zurueck. Die Originalrechnung wechselt dabei in Status 3 (storniert), das neue Stornodokument traegt Status 2, und der von der Originalrechnung abgebuchte Bestand wird zurueckgegeben.

Limits und Fehler

Listen sind seitenweise aufgeteilt, standardmaessig 200 Datensaetze pro Seite; Seite und Groesse waehlen Sie mit page und pageSize. Die Zahl der Aufrufe pro Minute je Benutzer ist durch den Tarif begrenzt: Starter 5, Standard 15, Business 30, Premium 60. Darueber liefern Listenaufrufe Fehler 429; warten Sie eine Minute und fahren Sie fort.

Aufrufe ausprobieren

In der interaktiven Dokumentation kann jeder Aufruf mit dem Button Try it out getestet werden: waehlen Sie Ihre Adresse aus der Server-Auswahl, geben Sie Header und Parameter ein und sehen Sie sofort die echte Antwort.

Brauchen Sie Hilfe?

Bei Fragen zur Anbindung, oder wenn ein benoetigter Aufruf fehlt, schreiben Sie an [email protected].