POST/v1/finance/report

Ανάκτηση συνοπτικής οικονομικής αναφοράς

finance_report

Επιστρέφει τα σύνολα των τιμολογίων ή των πληρωμών του οργανισμού, ομαδοποιημένα έως και κατά τρεις διαστάσεις (κατηγορία, ομάδα, κλάδος δραστηριότητας του προμηθευτή, προμηθευτής, αγοραστής, αντισυμβαλλόμενος, κατεύθυνση, νόμισμα, μήνας, τρίμηνο, έτος), με τα μέτρα invoiced, paid, unpaid και tax. Τα σύνολα περιλαμβάνουν μόνο έγγραφα ορατά στον χρήστη (τις συλλογές και τις κατηγορίες του προφίλ δεδομένων του και τη ρύθμιση «απάντηση μόνο από επαληθευμένες κάρτες»)· τα φίλτρα του αιτήματος περιορίζουν αυτό το εύρος, αλλά δεν το διευρύνουν ποτέ.

Στον τρόπο reporting (η προεπιλογή) τα ποσά μετατρέπονται στο νόμισμα αναφοράς του οργανισμού με την ισοτιμία της ημερομηνίας του εγγράφου, και τα ποσά χωρίς ισοτιμία παρατίθενται στο conversion.unconverted. Στον τρόπο original τα ποσά σε διαφορετικά νομίσματα δεν αθροίζονται, και το νόμισμα γίνεται διάσταση της γραμμής. Αν υπάρχουν περισσότερες γραμμές από το limit, το truncated είναι true, και τα totals εξακολουθούν να καλύπτουν όλες τις γραμμές. Απαιτεί προφίλ δεδομένων με πρόσβαση σε οικονομικά δεδομένα (finance.forbidden).

Η αναφορά, οι λίστες τιμολογίων και πληρωμών και οι εξαγωγές τους είναι λειτουργίες ανάγνωσης, παρόλο που χρησιμοποιούν POST: είναι διαθέσιμες στη λειτουργία «View as» και σε κλειδιά API με την εμβέλεια read (και, όπως πριν, σε κλειδιά με την εμβέλεια write).

Έλεγχος ταυτότητας

Στείλτε ένα κλειδί API στην κεφαλίδα Authorization: Authorization: Bearer <κλειδί>.

Παράμετροι κεφαλίδας

X-View-Asstring
Μόνο για κλειδιά API με τον ρόλο admin. Εκτελεί το αίτημα ως το προφίλ δεδομένων <profile>[:viewer|verifier|editor], για παράδειγμα employee:viewer. Το κλειδί εγκατάστασης δεν μπορεί να χρησιμοποιήσει αυτή την κεφαλίδα (403).

Παράμετροι cookie

kb_view_asstring
Cookie της λειτουργίας «View as» για μια συνεδρία. Το POST /auth/view-as το ορίζει και το DELETE /auth/view-as το καταργεί.

Σώμα αιτήματος

application/json

Αντικείμενο: FinanceReportRequest

basisstring
invoices: τιμολόγια, πιστωτικά τιμολόγια και αποδείξεις. payments: το αρχείο πληρωμών (ταμειακές ροές). Με payments το μόνο μέτρο είναι το paid, ενώ η διάσταση direction και το σύνολο δείχνουν την κίνηση χρημάτων, in ή out· μια μεταφορά μεταξύ των δικών σας νομικών οντοτήτων είναι internal.
Επιτρεπόμενες τιμές: invoicespayments
Προεπιλογή: "invoices"
group_byarray of FinanceDimension
items ≤ 3
measuresarray of FinanceMeasure
Προεπιλογή: invoiced (paid για payments).
currency_modeFinanceCurrencyMode
date_basisstring
Ποια ημερομηνία ορίζει την περίοδο και το φίλτρο from/to: η ημερομηνία του εγγράφου ή η ημερομηνία πληρωμής.
Επιτρεπόμενες τιμές: documentpayment
Προεπιλογή: "document"
filtersFinanceFilter
order_bystring
Μέτρο ή διάσταση για την ταξινόμηση. Από προεπιλογή, το πρώτο μέτρο με φθίνουσα σειρά.
order_descboolean
Προεπιλογή: true
limitinteger
Προεπιλογή: 1000≥ 1, ≤ 10000
languagestring
Γλώσσα των ετικετών των κατηγοριών και των ομάδων, en|ru. Προεπιλογή: en.

Αποκρίσεις

200Η αναφορά

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: FinanceReport

currency_modeFinanceCurrencyModeυποχρεωτικό
currencystring
Νόμισμα αναφοράς (λειτουργία reporting).
rowsarray of FinanceReportRowυποχρεωτικό
totalsarray of FinanceReportTotalυποχρεωτικό
Σύνολα για όλες τις γραμμές πριν από την περικοπή, μία εγγραφή ανά νόμισμα (σε αναφορά με διαχωρισμό κατά κατεύθυνση – ανά νόμισμα και κατεύθυνση, FinanceReportTotal.direction).
truncatedbooleanυποχρεωτικό
limitintegerυποχρεωτικό
total_rowsintegerυποχρεωτικό
Αριθμός ομαδοποιημένων γραμμών πριν από την περικοπή.
conversionFinanceConversion
warningsarray of string
Κωδικοί προειδοποίησης: profile_missing – τα εταιρικά στοιχεία του οργανισμού δεν έχουν οριστεί, γι’ αυτό η κατεύθυνση των τιμολογίων είναι από προεπιλογή in· catalog_missing – ο κατάλογος εταιρειών δεν έχει φορτωθεί· fx_rate_missing – για ορισμένα ποσά δεν υπάρχει συναλλαγματική ισοτιμία (conversion.unconverted)· fx_rate_stale – ορισμένες ισοτιμίες δεν είναι επίκαιρες· enrichment_pending – ορισμένα έγγραφα βρίσκονται ακόμη σε επεξεργασία και δεν περιλαμβάνονται στα σύνολα. Έναν άγνωστο κωδικό εμφανίστε με ένα γενικό μήνυμα.

400Το αίτημα δεν είναι έγκυρο: η τιμή μιας παραμέτρου ή η κατάσταση του αντικειμένου δεν επιτρέπει την ενέργεια (το `detail` είναι μήνυμα).

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

401Δεν στάλθηκαν διαπιστευτήρια (ούτε cookie συνεδρίας ούτε κλειδί API) ή το κλειδί δεν βρέθηκε.

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

403Η ενέργεια δεν επιτρέπεται: ο ρόλος δεν επαρκεί, δεν υπάρχει πρόσβαση στη συλλογή ή στην κάρτα, το αίτημα εκτελείται στη λειτουργία «View as» ή ο οργανισμός έχει ανασταλεί ή διαγραφεί (το `detail` είναι αντικείμενο με `code: org_suspended | org_deleted`).

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

429Πάρα πολλά αιτήματα (`api.rate_limited`), η ποσόστωση του οργανισμού για το λεπτό, την ημέρα ή τον μήνα εξαντλήθηκε (`api.quota_exceeded`· το `error.details` περιέχει τα `quota`, `limit` και `reset_at`), ο οργανισμός έφτασε στο όριό του ή η υπηρεσία απαντήσεων είναι απασχολημένη (`answers.engine_busy`). Περιμένετε τον χρόνο που δίνει η κεφαλίδα `Retry-After`.

Κεφαλίδες απόκρισης

Retry-After
Αριθμός δευτερολέπτων αναμονής πριν επαναλάβετε το αίτημα.
RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

503Μια υπηρεσία από την οποία εξαρτάται αυτό το αίτημα δεν είναι προσωρινά διαθέσιμη. Δοκιμάστε ξανά αργότερα.

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

Κωδικοί σφαλμάτων

Κωδικοί που μπορεί να επιστρέψει αυτό το τελικό σημείο στο error.code, εκτός από τους γενικούς κωδικούς κάθε αιτήματος.

Ασφαλείς επαναλήψεις

Στείλτε μια κεφαλίδα Idempotency-Key (για παράδειγμα ένα UUID) με κάθε POST και PATCH. Μια επανάληψη με το ίδιο κλειδί εντός 24 ωρών επιστρέφει την αποθηκευμένη απόκριση αντί να εκτελέσει ξανά το αίτημα.

Όρια ρυθμού

Οι αποκρίσεις περιέχουν τις κεφαλίδες RateLimit και RateLimit-Policy, καθώς και τις παλαιότερες X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset. Μια απόκριση 429 έχει την κεφαλίδα Retry-After σε δευτερόλεπτα: περιμένετε και επαναλάβετε το αίτημα.

← finance · Αναφορά API

curl -X POST 'https://api.sursa.com/v1/finance/report' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"basis":"invoices","group_by":["category"],"measures":["invoiced"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Δοκιμάστε το

Κλειδί API

Το κλειδί μένει στη μνήμη αυτής της καρτέλας και αποστέλλεται μόνο στο https://api.sursa.com.

Τα αιτήματα επηρεάζουν τα πραγματικά δεδομένα του οργανισμού σας.

X-View-As header

Idempotency-Key

Αν το πεδίο μείνει κενό, δημιουργείται νέο κλειδί για κάθε αίτημα.

Σώμα αιτήματος (JSON)