Pleaxy

Bestellungen anlegen, Rechnungen freigeben und bezahlen und den Workspace einrichten.

API-Referenz

Gutschriften

Gutschriften, die mindern, was ein Käufer schuldet, und ihre Verrechnung mit Rechnungen.

Mehr zu dieser Ressource

Gutschriften sind Abrechnungsbelege wie Rechnungen: ListInvoices, GetInvoice und CreateInvoice bedienen sie mit documentType credit_note ebenfalls, und diese Routen sind die eigenen Aktionen der Gutschrift. Eine Gutschrift mindert, was ein Käufer einem Lieferanten schuldet, mit eigenen Positionen und eigener Steuer. Ein Lieferant stellt sie zu der Rechnung aus, die sie korrigiert, oder allgemein für den Käufer (oder sendet sie über SubmitFeedInvoice); ein Käufer kann eine empfangene erfassen. Eine Gutschrift, die eine Rechnung nennt und nicht höher ist als deren Summe, wird sofort angenommen; jede andere wartet, bis der Käufer sie annimmt oder ablehnt. Das Annehmen einer Gutschrift returned_goods oder price_adjustment (oder other mit correctsBilling) gibt ihren Nettobetrag an die PO-Position der korrigierten Rechnung zurück; Service-Gutschriften und Rückvergütungen lassen die PO unberührt. Wer angenommene Gutschriften verrechnet, ist eine Käufereinstellung: Pleaxy, wo sie mit Rechnungen verrechnet werden und den Zahlbetrag mindern (eine freigegebene Rechnung, die Gutschriften vollständig decken, wird mit method "credit" als bezahlt markiert), oder das Buchhaltungssystem, wo angenommene Gutschriften im nächsten Zahlungsexport als negative Zeilen ausgegeben werden. Das Ablehnen einer Rechnung gibt die mit ihr verrechneten Beträge an ihre Gutschriften zurück. Die Rechnungssumme und ihre Steuer ändern sich nie. Eine Gutschrift (Credit Memo), die AWS oder Azure zu einer von Ihrer Cloud-Verbindung synchronisierten Rechnung ausstellt, wird als Gutschrift dieses Anbieters erfasst (source "cloud_sync", mit cloudProvider), zu der Rechnung, die sie nennt, wenn diese in Pleaxy vorliegt, einmal pro Memo.

Endpunkte

Gutschriften auflisten

Listet Gutschriften auf, jeweils mit ihrem Restbetrag.

GET/v1/workspaces/{regionId}/credit-notes

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Die Gutschriften, die ein Käufer empfangen oder ein Lieferant ausgestellt hat (über alle seine Käufer), älteste zuerst, jeweils mit remaining: was noch zu verrechnen ist, nie gespeichert.

Fehler

  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/credit-notes
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
[ {
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
} ]

Gutschrift abrufen

Ruft eine einzelne Gutschrift ab.

GET/v1/workspaces/{regionId}/credit-notes/{creditNoteId}

Parameter

  • creditNoteIdstringPflicht

    Die Gutschrift, z. B. "CN-1A2B3C4D".

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Eine Gutschrift: was sie korrigiert, was die Annahme an der PO bewirkt hat (poEffect), die Rechnungen, mit denen sie verrechnet wurde, oder der Export, der sie enthielt, und was davon übrig ist.

Antwortfelder

  • remainingnumber

    amount − mit Rechnungen verrechnet − erstattet. 0, sobald aufgebraucht; eine exportierte Gutschrift wird vom Buchhaltungssystem verrechnet.

  • refundednumber

    Was nach Angabe des Lieferanten bereits erstattet wurde, bevor er die Gutschrift gesendet hat (UBL PrepaidAmount, cXML DepositAmount). Bleibt nie zur Verrechnung übrig.

  • poEffectobject

    Bei Annahme gesetzt: der zurückgegebene PO-Saldo (kind release, vor Steuern, bei zurückgegebener Ware mit der Menge) oder warum keiner zurückgegeben wurde (not_a_correction, no_po, po_closed).

  • hasPdfboolean

    Die Gutschrift hat ein eigenes PDF, das bei ihrer Ausstellung angehängt wurde, oder das Dokument, aus dem sie erfasst wurde: GetCreditNotePdf gibt es zurück.

  • source, cloudProviderstring, string

    source ist "feed" für eine über SubmitFeedInvoice gesendete Gutschrift (in submittedFormat) und "cloud_sync" für das Credit Memo eines Anbieters (cloudProvider aws oder azure); fehlt, wenn sie in Pleaxy oder mit CreateCreditNote erfasst wurde.

Fehler

  • 404 Not Found - In diesem Workspace gibt es keine solche Gutschrift ("Credit note <id> not found.").
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/credit-notes/{creditNoteId}
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Gutschrift als PDF abrufen

Lädt das PDF einer Gutschrift herunter.

GET/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf

Parameter

  • creditNoteIdstringPflicht

    Die Gutschrift, z. B. "CN-1A2B3C4D".

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Das eigene PDF der Gutschrift: das bei ihrer Ausstellung angehängte (pdfBase64) oder das Dokument, aus dem sie erfasst wurde. Pleaxy erzeugt keines. Senden Sie Accept: application/pdf, sonst kommt der Body base64-kodiert zurück.

Fehler

  • 404 Not Found - In diesem Workspace gibt es keine solche Gutschrift, oder Code CREDIT_NOTE_NO_PDF: Sie hat keins (hasPdf ist false).
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
application/pdf

Gutschrift anlegen

Stellt eine Gutschrift aus oder erfasst eine empfangene.

POST/v1/workspaces/{regionId}/credit-notes

Body

  • invoiceIdstring

    Die Rechnung, die sie korrigiert. Keine abgelehnte. Geben Sie dies oder connectionId an.

  • connectionIdstring

    Die Gegenpartei, wenn sie keine einzelne Rechnung korrigiert.

  • externalCreditNoteNumberstringPflicht

    Ihre Nummer dafür, 1–64 Zeichen: Buchstaben, Ziffern, '.', '_', '/' und '-', beginnend mit einem Buchstaben oder einer Ziffer. Eindeutig pro Lieferant innerhalb des Käufers, ohne Beachtung der Groß-/Kleinschreibung.

  • issueDatestringPflicht

    YYYY-MM-DD, nicht in der Zukunft und nicht mehr als 365 Tage zurück.

  • reasonstringPflicht

    returned_goods, price_adjustment, service_credit, rebate oder other. Die ersten beiden geben nach der Annahme PO-Saldo zurück.

  • correctsBillingboolean

    Nur bei Grund other: Sie korrigiert das Abgerechnete und gibt daher ebenfalls PO-Saldo zurück.

  • notestring

    1–1000 Zeichen, z. B. die RMA-Nummer der Rücksendung.

  • currencystring

    ISO 4217. Erforderlich mit connectionId; mit invoiceId muss es die Währung der Rechnung sein.

  • lineItemsArray<{ description, qty, unitPrice }>Pflicht

    Was gutgeschrieben wird, vor Steuern. 1–200 Positionen.

  • taxAmountnumber

    Die gutgeschriebene Steuer, in der Summe enthalten.

  • taxBreakdownArray<{ description, amount, rate? }>

    Steuern nach Art, deren Summe taxAmount ergibt. Höchstens 20.

  • pdfBase64string

    Base64-kodiertes PDF der Gutschrift wie ausgestellt, bis zu 8MB. Wird mit ihr gespeichert (siehe GetCreditNotePdf).

  • sourceImportIdstring

    Nur für Käufer: der Rechnungsimport (ID-…), aus dem die Gutschrift gelesen wurde - das Gutschriftsdokument des Lieferanten, hochgeladen und von Pleaxy gelesen. Sein Dokument wird mit der Gutschrift gespeichert, wenn es ein PDF unter 8MB ist, und der Import hält die Gutschrift fest. Wird dem Lieferanten nie angezeigt.

Rückgabe

201 Created mit dem in der Antwort gezeigten Objekt.

Weitere Details

Stellt eine Gutschrift aus (Lieferant) oder erfasst eine empfangene (Käufer). Geben Sie genau eines von beiden an: invoiceId (die korrigierte Rechnung, deren Käufer, Lieferant, Währung, PO und PO-Position sie übernimmt) oder connectionId (die Gegenpartei, mit currency). Die Summe wird wie bei CreateInvoice aus den Positionen und der Steuer berechnet. Wird sofort angenommen, wenn sie eine Rechnung nennt und nicht höher ist als deren Summe; sie wird dann mit dieser Rechnung verrechnet, wenn die Gutschriften des Käufers in Pleaxy verrechnet werden und die Rechnung nicht exportiert oder bezahlt ist. Der Käufer wird benachrichtigt.

Fehler

  • 400 Bad Request - CREDIT_NOTE_TARGET_REQUIRED (weder oder beide von invoiceId und connectionId), CREDIT_NOTE_INVALID (correctsBilling mit einem anderen Grund, eine abgelehnte Rechnung, eine Währung, die nicht die der Rechnung ist, keine Währung ohne Rechnung), ISSUE_DATE_INVALID, ein pdfBase64, das nicht base64 ist, leer ist oder über 8MB groß ist oder kein PDF ist ("pdfBase64 doesn't decode to a PDF document (missing %PDF- header)"), oder ein Body, der die Validierung nicht besteht.
  • 404 Not Found - Die Rechnung oder die Verbindung gehört nicht Ihnen.
  • 409 Conflict - CREDIT_NOTE_NUMBER_TAKEN: Diese Nummer wird zwischen Ihnen und diesem Käufer bereits verwendet.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/credit-notes
Anfrage
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "invoiceId": "string",
   "connectionId": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": boolean,
   "note": "string",
   "currency": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number } ],
   "taxAmount": number,
   "pdfBase64": "string"
}
Antwort · 201 Created
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Gutschrift annehmen

Nimmt eine Gutschrift an.

POST/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept

Parameter

  • creditNoteIdstringPflicht

    Die Gutschrift, z. B. "CN-1A2B3C4D".

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Nimmt eine Gutschrift an, die auf Annahme wartet. In einem Schreibvorgang: ihr Status, der PO-Saldo, den eine Korrektur zurückgibt (nie mehr, als die korrigierte Rechnung auf der Position verbraucht hat, abzüglich früherer Gutschriften), und - wenn Gutschriften in Pleaxy verrechnet werden und die korrigierte Rechnung sie aufnehmen kann - ihre Verrechnung dort. Der Lieferant wird benachrichtigt.

Fehler

  • 400 Bad Request - CREDIT_OVER_RELEASES_PO: Sie würde mehr zurückgeben, als die Rechnung auf ihrer PO-Position verbraucht hat.
  • 409 Conflict - CREDIT_NOTE_NOT_PENDING (bereits angenommen, abgelehnt oder storniert) oder CREDIT_NOTE_CHANGED (sie hat sich während der Annahme geändert; neu laden und erneut versuchen).
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept
Anfrage
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Gutschrift ablehnen

Lehnt eine Gutschrift mit einer Begründung ab.

POST/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject

Parameter

  • creditNoteIdstringPflicht

    Die Gutschrift, z. B. "CN-1A2B3C4D".

Body

  • reasonstringPflicht

    1–1000 Zeichen.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Lehnt eine Gutschrift, die auf Annahme wartet, mit einer Begründung ab, die der Lieferant liest. Der Lieferant wird benachrichtigt.

Fehler

  • 400 Bad Request - CREDIT_NOTE_INVALID: keine Begründung.
  • 409 Conflict - CREDIT_NOTE_NOT_PENDING oder CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject
Anfrage
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "reason": "string" }
Antwort · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Gutschriftsverrechnung abrufen

Gibt zurück, wo angenommene Gutschriften verrechnet werden.

GET/v1/workspaces/{regionId}/credit-notes/settings

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Wer angenommene Gutschriften verrechnet: pleaxy (hier mit Rechnungen verrechnet) oder accounting_system (für Ihr ERP exportiert). Solange nichts gewählt ist (chosen: false), gilt accounting_system für einen Workspace, der Rechnungen für die Zahlung exportiert hat, sonst pleaxy.

Fehler

  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/credit-notes/settings
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/settings" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "chosen": boolean
}

Gutschriftsverrechnung festlegen

Legt fest, wo angenommene Gutschriften verrechnet werden.

PUT/v1/workspaces/{regionId}/credit-notes/settings

Body

  • creditSettlementstringPflicht

    "pleaxy" oder "accounting_system".

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Legt fest, wer angenommene Gutschriften verrechnet. Der Wechsel zu accounting_system wird abgelehnt, solange Gutschriften auf unbezahlten Rechnungen verrechnet sind; nehmen Sie sie zuerst herunter.

Fehler

  • 400 Bad Request - CREDIT_SETTLEMENT_INVALID.
  • 409 Conflict - CREDITS_APPLIED_TO_UNPAID: Gutschriften sind mit unbezahlten Rechnungen verrechnet.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
PUT /v1/workspaces/{regionId}/credit-notes/settings
Anfrage
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/settings" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "creditSettlement": "pleaxy" | "accounting_system" }
Antwort · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "chosen": boolean
}

Verfügbare Gutschriften auflisten

Listet die Gutschriften auf, die mit einer Rechnung verrechnet werden können.

GET/v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits

Parameter

  • invoiceIdstringPflicht

    Die Rechnung, z. B. "INV-1A2B3C4D".

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Die angenommenen Gutschriften des Lieferanten der Rechnung in ihrer Währung, älteste zuerst, jeweils mit dem Restbetrag und einem Vorschlag (bis zu dem, was die Rechnung schuldet), sowie die Gutschriften des Lieferanten, die noch auf Annahme warten. locked gibt an, warum die Rechnung derzeit keine Gutschriften aufnehmen kann.

Fehler

  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "locked": "exported" | "paid" | "rejected" | "otherCurrency",
   "amountDue": number,
   "currency": "string",
   "credits": [ { "creditNoteId": "string", "externalCreditNoteNumber": "string", "reason": "string", "issueDate": "string", "amount": number, "remaining": number, "suggested": number } ],
   "pending": [ { "creditNoteId": "string", "externalCreditNoteNumber": "string", "reason": "string", "amount": number } ],
   "suggestedTotal": number
}

Gutschriften verrechnen

Verrechnet Gutschriften mit einer Rechnung.

POST/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications

Parameter

  • invoiceIdstringPflicht

    Die Rechnung, z. B. "INV-1A2B3C4D".

Body

  • applicationsArray<{ creditNoteId, amount }>Pflicht

    1–20, jede Gutschrift einmal, jeder Betrag höchstens ihr Restbetrag.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Verrechnet angenommene Gutschriften mit einer Rechnung, die nicht exportiert, bezahlt, abgelehnt oder in einer anderen Währung geschuldet ist - alle oder keine, in einem Schreibvorgang mit jeder Gutschrift. Der Zahlbetrag sinkt, die Summe und ihre Steuer nicht. Gutschriften dürfen höchstens decken, was die Rechnung schuldet; eine freigegebene Rechnung, die sie vollständig decken, wird mit method "credit" als bezahlt markiert (eine nicht freigegebene, sobald sie freigegeben ist). Der Lieferant wird benachrichtigt. Gibt die Rechnung zurück.

Fehler

  • 400 Bad Request - CREDIT_APPLICATIONS_REQUIRED, CREDIT_APPLICATIONS_INVALID (eine Gutschrift doppelt aufgeführt, in einer anderen Währung oder von einem anderen Lieferanten) oder CREDIT_OVER_APPLIED (mehr als der Restbetrag einer Gutschrift oder mehr, als die Rechnung schuldet).
  • 409 Conflict - INVOICE_LOCKED (exportiert, bezahlt, abgelehnt oder in einer anderen Währung geschuldet), CREDIT_NOTE_NOT_ACCEPTED, CREDITS_SETTLED_IN_ACCOUNTING (Ihr Buchhaltungssystem verrechnet Gutschriften) oder CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications
Anfrage
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "applications": [ { "creditNoteId": "string", "amount": number } ] }
Antwort · 200 OK
{
   "documentType": "invoice" | "debit_note",
   "amendsInvoiceId": "string",
   "amendsExternalInvoiceNumber": "string",
   "debitNoteIds": [ "string" ],
   "replacesInvoiceIds": [ "string" ],
   "replacedByInvoiceIds": [ "string" ],
   "replacement": { "creditedInFull": boolean, "uncredited": number },
   "uncreditedOriginals": [ { "invoiceId": "string", "externalInvoiceNumber": "string", "uncredited": number, "currency": "string" } ],
   "id": "string",
   "po": "string",
   "poLineNo": number,
   "billsNoPoLine": true,
   "buyerOrgId": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "amount": number,
   "currency": "string",
   "usageAmount": number,
   "usageCurrency": "string",
   "tolerancePct": number,
   "matchStatus": "pending" | "matched" | "discrepancy" | "unverified",
   "unverifiedReason": "no_purchase_order" | "no_billing_connection" | "debit_note",
   "discrepancyReason": "amount" | "currency",
   "paid": boolean,
   "dueInDays": number,
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "createdAt": "string",
   "lastRemindedAt": "string",
   "rejection": { "reasonCode": "amount_incorrect" | "not_ordered_or_not_received" | "duplicate" | "missing_or_wrong_po" | "wrong_billing_entity" | "other", "reason": "string", "at": "string" },
   "replacesInvoiceId": "string",
   "source": "po-flip" | "direct" | "manual" | "feed",
   "submittedFormat": "json" | "cxml" | "ubl",
   "submittedBy": "string",
   "externalInvoiceNumber": "string",
   "lineItems": [
      { "description": "string", "qty": number, "unitPrice": number, "discount": number, "charge": number, "amount": number }
   ],
   "adjustments": [
      { "type": "discount" | "charge", "description": "string", "amount": number }
   ],
   "taxAmount": number,
   "taxBreakdown": [ { "description": "string", "rate": number, "amount": number } ],
   "paymentCurrencyAmount": { "currencyCode": "string", "totalAmount": number, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "taxCurrencyAmount": { "currencyCode": "string", "amountBreakdown": { "taxes": { "totalAmount": number } }, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "baseCurrencyAmount": { "currencyCode": "string", "totalAmount": number },
   "rateWarnings": [
      { "object": "payment" | "tax", "currency": "string", "statedRate": number, "referenceRate": number, "source": "provider" | "override", "asOf": "string", "deviationPct": number }
   ],
   "withholdings": [ { "description": "string", "rate": number, "amount": number } ],
   "deductions": [ { "kind": "prepayment" | "credit", "description": "string", "amount": number, "reference": "string", "paidOn": "string", "sourceInvoiceId": "string", "stated": true } ],
   "invoiceKind": "prepayment",
   "creditNoteIds": [ "string" ],
   "creditApplications": [ { "id": "string", "creditNoteId": "string", "externalCreditNoteNumber": "string", "amount": number, "appliedAt": "string", "appliedByName": "string", "auto": true } ],
   "payment": { "status": "recorded", "method": "ach" | "wire" | "check" | "card" | "other" | "credit", "paymentDate": "string", "reference": "string", "paidAmount": { "amount": number, "currency": "string", "rate": number, "rateDate": "string" } },
   "remittances": [ { "id": "string", "sentAt": "string", "sentByName": "string", "note": "string", "file": { "fileName": "string", "contentType": "application/pdf" | "image/png" | "image/jpeg", "sizeBytes": number } } ]
}

Gutschriftsverrechnung entfernen

Entfernt eine Gutschrift von einer Rechnung.

DELETE/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}

Parameter

  • invoiceIdstringPflicht

    Die Rechnung, z. B. "INV-1A2B3C4D".

  • applicationIdstringPflicht

    Die Verrechnung, aus den creditApplications der Rechnung.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Nimmt eine Gutschrift wieder von einer Rechnung, die nicht exportiert oder bezahlt ist; der Betrag geht an ihre Gutschrift zurück. Gibt die Rechnung zurück.

Fehler

  • 404 Not Found - Die Rechnung hat keine solche Verrechnung.
  • 409 Conflict - INVOICE_LOCKED (exportiert oder bezahlt) oder CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
DELETE /v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}
Anfrage
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "documentType": "invoice" | "debit_note",
   "amendsInvoiceId": "string",
   "amendsExternalInvoiceNumber": "string",
   "debitNoteIds": [ "string" ],
   "replacesInvoiceIds": [ "string" ],
   "replacedByInvoiceIds": [ "string" ],
   "replacement": { "creditedInFull": boolean, "uncredited": number },
   "uncreditedOriginals": [ { "invoiceId": "string", "externalInvoiceNumber": "string", "uncredited": number, "currency": "string" } ],
   "id": "string",
   "po": "string",
   "poLineNo": number,
   "billsNoPoLine": true,
   "buyerOrgId": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "amount": number,
   "currency": "string",
   "usageAmount": number,
   "usageCurrency": "string",
   "tolerancePct": number,
   "matchStatus": "pending" | "matched" | "discrepancy" | "unverified",
   "unverifiedReason": "no_purchase_order" | "no_billing_connection" | "debit_note",
   "discrepancyReason": "amount" | "currency",
   "paid": boolean,
   "dueInDays": number,
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "createdAt": "string",
   "lastRemindedAt": "string",
   "rejection": { "reasonCode": "amount_incorrect" | "not_ordered_or_not_received" | "duplicate" | "missing_or_wrong_po" | "wrong_billing_entity" | "other", "reason": "string", "at": "string" },
   "replacesInvoiceId": "string",
   "source": "po-flip" | "direct" | "manual" | "feed",
   "submittedFormat": "json" | "cxml" | "ubl",
   "submittedBy": "string",
   "externalInvoiceNumber": "string",
   "lineItems": [
      { "description": "string", "qty": number, "unitPrice": number, "discount": number, "charge": number, "amount": number }
   ],
   "adjustments": [
      { "type": "discount" | "charge", "description": "string", "amount": number }
   ],
   "taxAmount": number,
   "taxBreakdown": [ { "description": "string", "rate": number, "amount": number } ],
   "paymentCurrencyAmount": { "currencyCode": "string", "totalAmount": number, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "taxCurrencyAmount": { "currencyCode": "string", "amountBreakdown": { "taxes": { "totalAmount": number } }, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "baseCurrencyAmount": { "currencyCode": "string", "totalAmount": number },
   "rateWarnings": [
      { "object": "payment" | "tax", "currency": "string", "statedRate": number, "referenceRate": number, "source": "provider" | "override", "asOf": "string", "deviationPct": number }
   ],
   "withholdings": [ { "description": "string", "rate": number, "amount": number } ],
   "deductions": [ { "kind": "prepayment" | "credit", "description": "string", "amount": number, "reference": "string", "paidOn": "string", "sourceInvoiceId": "string", "stated": true } ],
   "invoiceKind": "prepayment",
   "creditNoteIds": [ "string" ],
   "creditApplications": [ { "id": "string", "creditNoteId": "string", "externalCreditNoteNumber": "string", "amount": number, "appliedAt": "string", "appliedByName": "string", "auto": true } ],
   "payment": { "status": "recorded", "method": "ach" | "wire" | "check" | "card" | "other" | "credit", "paymentDate": "string", "reference": "string", "paidAmount": { "amount": number, "currency": "string", "rate": number, "rateDate": "string" } },
   "remittances": [ { "id": "string", "sentAt": "string", "sentByName": "string", "note": "string", "file": { "fileName": "string", "contentType": "application/pdf" | "image/png" | "image/jpeg", "sizeBytes": number } } ]
}
Kontakt aufnehmen