Pleaxy

Emetti ordini d’acquisto, approva e paga le fatture e configura il tuo spazio di lavoro.

Riferimento API

Note di credito

Le note di credito che riducono quanto deve un acquirente, e la loro applicazione alle fatture.

Altro su questa risorsa

Le note di credito sono documenti come le fatture: anche ListInvoices, GetInvoice e CreateInvoice le gestiscono con documentType credit_note, e queste route sono le azioni proprie della nota di credito. Una nota di credito riduce quanto un acquirente deve a un fornitore, con righe e imposte proprie. Un fornitore ne emette una a fronte della fattura che corregge o per l’acquirente in generale (oppure la invia tramite SubmitFeedInvoice); un acquirente può registrarne una ricevuta. Una che indica una fattura e non ne supera il totale viene accettata subito; qualsiasi altra attende che l’acquirente la accetti o la rifiuti. Accettare un credito returned_goods o price_adjustment (o other con correctsBilling) restituisce il suo importo al netto delle imposte alla riga dell’OdA della fattura corretta; i crediti di servizio e i rebate non toccano l’OdA. Chi salda i crediti accettati è un’impostazione dell’acquirente: Pleaxy, dove vengono applicati alle fatture e riducono l’importo dovuto (una fattura approvata coperta interamente dai crediti viene contrassegnata come pagata con method "credit"), oppure il sistema contabile, dove le note di credito accettate escono nella successiva esportazione di pagamenti come righe negative. Rifiutare una fattura restituisce i crediti applicati alle rispettive note di credito. Il totale della fattura e le sue imposte non cambiano mai. Una nota di credito che AWS o Azure emette su una fattura sincronizzata dalla tua connessione cloud viene registrata come nota di credito di quel provider (source "cloud_sync", con cloudProvider), a fronte della fattura che indica quando quella fattura è in Pleaxy, una volta per nota.

Endpoint

Elencare le note di credito

Elenca le note di credito, con il residuo di ciascuna.

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

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Le note di credito ricevute da un acquirente o emesse da un fornitore (verso tutti i suoi acquirenti), dalla meno recente, ciascuna con remaining: quanto resta da applicare, mai memorizzato.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/credit-notes
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
} ]

Recuperare una nota di credito

Recupera una nota di credito.

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

Parametri

  • creditNoteIdstringObbligatorio

    La nota di credito, ad es. "CN-1A2B3C4D".

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Una nota di credito: cosa corregge, l’effetto dell’accettazione sull’OdA (poEffect), le fatture a cui è stata applicata o l’esportazione che l’ha inclusa, e quanto ne resta.

Campi della risposta

  • remainingnumber

    amount − quanto applicato alle fatture − quanto rimborsato. 0 una volta esaurita; una nota di credito esportata viene saldata dal sistema contabile.

  • refundednumber

    Quanto il fornitore dichiara di aver già rimborsato prima di inviare la nota di credito (UBL PrepaidAmount, cXML DepositAmount). Mai disponibile da applicare.

  • poEffectobject

    Impostato all’accettazione: il saldo dell’OdA restituito (kind release, al netto delle imposte, con la quantità per la merce resa), o perché non ne è stato restituito (not_a_correction, no_po, po_closed).

  • hasPdfboolean

    La nota di credito ha un proprio PDF, allegato all’emissione o il documento da cui è stata registrata: GetCreditNotePdf lo restituisce.

  • source, cloudProviderstring, string

    source è "feed" per una nota inviata tramite SubmitFeedInvoice (in submittedFormat) e "cloud_sync" per una nota di credito di un provider (cloudProvider aws o azure); assente quando è inserita in Pleaxy o con CreateCreditNote.

Errori

  • 404 Not Found - Questa nota di credito non esiste in questo workspace ("Credit note <id> not found.").
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/credit-notes/{creditNoteId}
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
}

Recuperare il PDF di una nota di credito

Scarica il PDF di una nota di credito.

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

Parametri

  • creditNoteIdstringObbligatorio

    La nota di credito, ad es. "CN-1A2B3C4D".

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Il PDF della nota di credito: quello allegato all’emissione (pdfBase64), o il documento da cui è stata registrata. Pleaxy non ne genera uno. Invia Accept: application/pdf, altrimenti il corpo viene restituito codificato in base64.

Errori

  • 404 Not Found - Questa nota di credito non esiste in questo workspace, oppure codice CREDIT_NOTE_NO_PDF: non ne ha uno (hasPdf è false).
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
application/pdf

Creare una nota di credito

Emette una nota di credito o ne registra una ricevuta.

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

Corpo

  • invoiceIdstring

    La fattura che corregge. Non una rifiutata. Indica questo campo o connectionId.

  • connectionIdstring

    La controparte, quando non corregge una singola fattura.

  • externalCreditNoteNumberstringObbligatorio

    Il tuo numero per la nota, da 1 a 64 caratteri: lettere, cifre, '.', '_', '/' e '-', a partire da una lettera o una cifra. Univoco per fornitore presso l’acquirente, senza distinzione tra maiuscole e minuscole.

  • issueDatestringObbligatorio

    YYYY-MM-DD, non nel futuro e non più di 365 giorni prima.

  • reasonstringObbligatorio

    returned_goods, price_adjustment, service_credit, rebate o other. I primi due restituiscono saldo all’OdA una volta accettati.

  • correctsBillingboolean

    Solo con reason other: corregge quanto fatturato, quindi restituisce anch’esso saldo all’OdA.

  • notestring

    Da 1 a 1000 caratteri, ad es. il numero RMA del reso.

  • currencystring

    ISO 4217. Obbligatorio con connectionId; con invoiceId deve essere quella della fattura.

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

    Ciò che viene accreditato, al netto delle imposte. Da 1 a 200 righe.

  • taxAmountnumber

    L’imposta accreditata, inclusa nel totale.

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

    Imposte per tipo, la cui somma è pari a taxAmount. Al massimo 20.

  • pdfBase64string

    PDF della nota di credito come emessa, codificato in Base64, fino a 8MB. Conservato con la nota (vedi GetCreditNotePdf).

  • sourceImportIdstring

    Solo per l’acquirente: l’importazione di fattura (ID-…) da cui è stata letta la nota di credito, cioè il documento di nota di credito del fornitore, caricato e letto da Pleaxy. Il suo documento viene conservato con la nota di credito quando è un PDF sotto 8MB, e l’importazione registra la nota di credito. Mai mostrato al fornitore.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Emette una nota di credito (un fornitore) o ne registra una ricevuta (un acquirente). Indica esattamente uno tra invoiceId (la fattura che corregge, di cui prende acquirente, fornitore, valuta, OdA e riga dell’OdA) e connectionId (la controparte, con currency). Il totale viene calcolato dalle righe e dalle imposte come in CreateInvoice. Viene accettata subito quando indica una fattura e non ne supera il totale; viene poi applicata a quella fattura quando i crediti dell’acquirente sono saldati in Pleaxy e la fattura non è esportata o pagata. L’acquirente riceve una notifica.

Errori

  • 400 Bad Request - CREDIT_NOTE_TARGET_REQUIRED (nessuno o entrambi tra invoiceId e connectionId), CREDIT_NOTE_INVALID (correctsBilling con un altro reason, una fattura rifiutata, una valuta diversa da quella della fattura, nessuna valuta senza una fattura), ISSUE_DATE_INVALID, un pdfBase64 che non è base64, è vuoto o supera 8MB, o non è un PDF ("pdfBase64 doesn't decode to a PDF document (missing %PDF- header)"), oppure un corpo che non supera la convalida.
  • 404 Not Found - La fattura o la connessione non è tua.
  • 409 Conflict - CREDIT_NOTE_NUMBER_TAKEN: questo numero è già usato tra te e questo acquirente.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/credit-notes
Richiesta
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"
}
Risposta · 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"
}

Accettare una nota di credito

Accetta una nota di credito.

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

Parametri

  • creditNoteIdstringObbligatorio

    La nota di credito, ad es. "CN-1A2B3C4D".

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Accetta una nota di credito in attesa di accettazione. In un’unica scrittura: il suo stato, il saldo dell’OdA che una correzione restituisce (mai più di quanto la fattura corretta abbia assorbito sulla riga, meno i crediti precedenti) e, quando i crediti sono saldati in Pleaxy e la fattura che corregge può riceverla, la sua applicazione su di essa. Il fornitore riceve una notifica.

Errori

  • 400 Bad Request - CREDIT_OVER_RELEASES_PO: restituirebbe più di quanto la fattura abbia assorbito sulla sua riga dell’OdA.
  • 409 Conflict - CREDIT_NOTE_NOT_PENDING (già accettata, rifiutata o annullata), oppure CREDIT_NOTE_CHANGED (è cambiata durante l’accettazione; ricarica e riprova).
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
}

Rifiutare una nota di credito

Rifiuta una nota di credito, con un motivo.

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

Parametri

  • creditNoteIdstringObbligatorio

    La nota di credito, ad es. "CN-1A2B3C4D".

Corpo

  • reasonstringObbligatorio

    Da 1 a 1000 caratteri.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Rifiuta una nota di credito in attesa di accettazione, con un motivo che il fornitore legge. Il fornitore riceve una notifica.

Errori

  • 400 Bad Request - CREDIT_NOTE_INVALID: nessun motivo.
  • 409 Conflict - CREDIT_NOTE_NOT_PENDING o CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject
Richiesta
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" }
Risposta · 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"
}

Recuperare il saldo dei crediti

Restituisce dove vengono saldati i crediti accettati.

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

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Chi salda i crediti accettati: pleaxy (applicati alle fatture qui) o accounting_system (esportati per il tuo ERP). Finché non viene scelto (chosen: false), è accounting_system per un workspace che ha esportato fatture per il pagamento, e pleaxy altrimenti.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/credit-notes/settings
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/settings" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "chosen": boolean
}

Impostare il saldo dei crediti

Sceglie dove vengono saldati i crediti accettati.

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

Corpo

  • creditSettlementstringObbligatorio

    "pleaxy" o "accounting_system".

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Sceglie chi salda i crediti accettati. Il passaggio ad accounting_system viene rifiutato finché ci sono crediti applicati a fatture non pagate; rimuovili prima.

Errori

  • 400 Bad Request - CREDIT_SETTLEMENT_INVALID.
  • 409 Conflict - CREDITS_APPLIED_TO_UNPAID: ci sono crediti applicati a fatture non pagate.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
PUT /v1/workspaces/{regionId}/credit-notes/settings
Richiesta
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" }
Risposta · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "chosen": boolean
}

Elencare i crediti disponibili

Elenca i crediti che possono essere applicati a una fattura.

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

Parametri

  • invoiceIdstringObbligatorio

    La fattura, ad es. "INV-1A2B3C4D".

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

I crediti accettati del fornitore della fattura nella sua valuta, dal meno recente, ciascuno con il residuo e un suggerimento (fino a quanto la fattura deve), e le note di credito del fornitore ancora in attesa di accettazione. locked indica perché la fattura al momento non può ricevere crediti.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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
}

Applicare crediti

Applica crediti a una fattura.

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

Parametri

  • invoiceIdstringObbligatorio

    La fattura, ad es. "INV-1A2B3C4D".

Corpo

  • applicationsArray<{ creditNoteId, amount }>Obbligatorio

    Da 1 a 20, ogni nota di credito una sola volta, ogni amount al massimo pari al suo residuo.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Applica crediti accettati a una fattura che non sia esportata, pagata, rifiutata né dovuta in un’altra valuta: tutti o nessuno, in un’unica scrittura con ciascuna nota di credito. L’importo dovuto diminuisce; il totale e le sue imposte no. I crediti possono coprire al massimo quanto la fattura deve; una fattura approvata che coprono interamente viene contrassegnata come pagata con method "credit" (una non approvata, una volta approvata). Il fornitore riceve una notifica. Restituisce la fattura.

Errori

  • 400 Bad Request - CREDIT_APPLICATIONS_REQUIRED, CREDIT_APPLICATIONS_INVALID (una nota di credito indicata due volte, in un’altra valuta o di un altro fornitore), oppure CREDIT_OVER_APPLIED (più del residuo di una nota di credito, o più di quanto la fattura deve).
  • 409 Conflict - INVOICE_LOCKED (esportata, pagata, rifiutata o dovuta in un’altra valuta), CREDIT_NOTE_NOT_ACCEPTED, CREDITS_SETTLED_IN_ACCOUNTING (i crediti li salda il tuo sistema contabile), oppure CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications
Richiesta
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 } ] }
Risposta · 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 } } ]
}

Rimuovere l’applicazione di un credito

Rimuove un credito da una fattura.

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

Parametri

  • invoiceIdstringObbligatorio

    La fattura, ad es. "INV-1A2B3C4D".

  • applicationIdstringObbligatorio

    L’applicazione, presa da creditApplications della fattura.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Toglie un credito da una fattura non esportata né pagata; il credito torna alla sua nota di credito. Restituisce la fattura.

Errori

  • 404 Not Found - La fattura non ha questa applicazione.
  • 409 Conflict - INVOICE_LOCKED (esportata o pagata), oppure CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
DELETE /v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}
Richiesta
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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 } } ]
}
Contattaci