Κινήσεις υπολοίπου

Η κλήση GET /balance/transactions επιστρέφει τις κινήσεις του υπολοίπου του λογαριασμού σας (πληρωμές, χρεώσεις voucher, SMS / Viber, συνδρομές), από τις νεότερες προς τις παλαιότερες, με φίλτρα και cursor pagination. Είναι οι ίδιες κινήσεις με το Ιστορικό Υπολοίπου του περιβάλλοντος πελάτη. Το τρέχον υπόλοιπο το δίνει το GET /account.

WARNING

Θα πρέπει να συμπεριλάβετε το API Token σας σε κάθε αίτημα ως Bearer Token. Αντικαταστήστε το YOUR_TOKEN με το API Token του καταστήματος (chub_...). Δείτε το Overview.

Method	URI	Headers
GET	`/api/v2/balance/transactions`	`Authorization`: `Bearer YOUR_TOKEN`

Μεταβλητές αποστολής

Όλες οι παράμετροι είναι προαιρετικές και στέλνονται στο query string. Τα φίλτρα συνδυάζονται με AND.

Variable Name	Type	Usage
`type`	`String`	`credit` (πιστώσεις) ή `debit` (χρεώσεις).
`transaction_type`	`String`	Το είδος της κίνησης, δείτε Είδη κινήσεων. Μέγιστο 50 χαρακτήρες. Άγνωστη τιμή δίνει κενό αποτέλεσμα.
`from`	`Date` (`Y-m-d`)	Κινήσεις από αυτή την ημερομηνία και μετά (συμπεριλαμβάνεται, από τα μεσάνυχτα).
`to`	`Date` (`Y-m-d`)	Κινήσεις μέχρι αυτή την ημερομηνία (συμπεριλαμβάνεται ολόκληρη η ημέρα). Πρέπει να είναι ίση ή μεταγενέστερη της `from`.
`per_page`	`Integer`	`1` έως `100`. Προεπιλογή `50`.
`cursor`	`String`	Το `meta.next_cursor` / `meta.prev_cursor` προηγούμενης σελίδας.

Ημερομηνίες

Οι ημερομηνίες from / to ερμηνεύονται στη ζώνη ώρας της εφαρμογής (Europe/Athens), ενώ οι ώρες στην απάντηση είναι σε UTC. Π.χ. μια κίνηση με created_at 2026-09-30T21:05:00Z είναι στις 01/10/2026 00:05 ώρα Ελλάδας και επιστρέφεται με from=2026-10-01.

Είδη κινήσεων (`transaction_type`)

`transaction_type`	`type`	Περιγραφή
`voucher`	`debit`	Χρέωση έκδοσης voucher. Έχει `voucher_number`.
`sms_premium`	`debit`	Χρέωση SMS Premium. Έχει `voucher_number` όταν το μήνυμα αφορά αποστολή.
`sms_economy`	`debit`	Χρέωση SMS Economy. Έχει `voucher_number` όταν το μήνυμα αφορά αποστολή.
`viber_message`	`debit`	Χρέωση μηνύματος Viber. Έχει `voucher_number` όταν το μήνυμα αφορά αποστολή.
`monthly_fee`	`debit`	Μηνιαία συνδρομή.
`annual_fee`	`debit`	Ετήσια συνδρομή.
`viva_payment`	`credit`	Πληρωμή μέσω Viva.
`viva_recurring`	`credit`	Πληρωμή από πάγια εντολή Viva.
`viva_auto_charge`	`credit`	Αυτόματη χρέωση κάρτας μέσω Viva.
`manual_credit`	`credit`	Πίστωση από το CourierHub.

Σε παλαιότερες κινήσεις μπορεί να υπάρχουν και οι τιμές payment, credit (πιστώσεις) και sms_reserved, sms_settle_refund, sms_settle_charge (δέσμευση και εκκαθάριση SMS με το παλιό σύστημα χρέωσης). Μην βασίζεστε σε κλειστή λίστα: για την κατεύθυνση της κίνησης χρησιμοποιήστε το type.

Απάντηση αιτήματος

Η εφαρμογή σας επιστρέφει δεδομένα σε μορφή JSON με τη μορφή {data, links, meta}, ταξινομημένα από τη νεότερη κίνηση.

Variable Name	Type	Description
`id`	`Integer`	Το ID της κίνησης.
`type`	`String`	`credit` (πίστωση) ή `debit` (χρέωση).
`transaction_type`	`String` ή `null`	Το είδος της κίνησης.
`amount`	`String`	Το ποσό με πρόσημο και 4 δεκαδικά: οι χρεώσεις είναι αρνητικές (π.χ. `"-0.0450"`), οι πιστώσεις θετικές (π.χ. `"20.0000"`). Τα 4 δεκαδικά χρειάζονται γιατί οι τιμές SMS και voucher μπορεί να είναι κάτω από ένα λεπτό.
`balance_after`	`String`	Το υπόλοιπο μετά την κίνηση, στρογγυλεμένο σε 2 δεκαδικά.
`currency`	`String`	Το νόμισμα, πάντα `EUR`.
`description`	`String` ή `null`	Η περιγραφή της κίνησης στα Ελληνικά, όπως στο Ιστορικό Υπολοίπου. Προορίζεται για ανθρώπους: η μορφή της μπορεί να αλλάξει.
`voucher_number`	`String` ή `null`	Ο αριθμός voucher της αποστολής που αφορά η κίνηση (χρέωση voucher, SMS / Viber για αποστολή). Παραμένει και μετά την ακύρωση της αποστολής. `null` για κινήσεις χωρίς αποστολή (πληρωμές, συνδρομές).
`created_at`	`String`	Πότε έγινε η κίνηση (ISO 8601, UTC).

Τα links και meta περιγράφονται στη σελιδοποίηση.

Παράδειγμα επιτυχημένης αναζήτησης.

json

{
    "data": [
        {
            "id": 5,
            "type": "debit",
            "transaction_type": "sms_premium",
            "amount": "-0.0450",
            "balance_after": "30.89",
            "currency": "EUR",
            "description": "SMS • 7012345679 • → 306912345678 • 1 τμχ. • Χρέωση 0.0450 EUR (δέσμευση 0.0450 EUR)",
            "voucher_number": "7012345679",
            "created_at": "2026-10-19T07:16:00Z"
        },
        {
            "id": 4,
            "type": "debit",
            "transaction_type": "voucher",
            "amount": "-0.0700",
            "balance_after": "30.93",
            "currency": "EUR",
            "description": "Χρέωση αποστολής 1 voucher (περίοδος από 01/10/2026)",
            "voucher_number": "7012345679",
            "created_at": "2026-10-19T07:15:00Z"
        },
        {
            "id": 3,
            "type": "credit",
            "transaction_type": "viva_payment",
            "amount": "20.0000",
            "balance_after": "31.00",
            "currency": "EUR",
            "description": "Πληρωμή μέσω Viva",
            "voucher_number": null,
            "created_at": "2026-10-19T06:00:00Z"
        },
        {
            "id": 2,
            "type": "debit",
            "transaction_type": "monthly_fee",
            "amount": "-19.0000",
            "balance_after": "11.00",
            "currency": "EUR",
            "description": "Μηνιαία συνδρομή October 2026",
            "voucher_number": null,
            "created_at": "2026-09-30T21:05:00Z"
        },
        {
            "id": 1,
            "type": "credit",
            "transaction_type": "viva_payment",
            "amount": "30.0000",
            "balance_after": "30.00",
            "currency": "EUR",
            "description": "Πληρωμή μέσω Viva",
            "voucher_number": null,
            "created_at": "2026-09-30T21:05:00Z"
        }
    ],
    "links": {
        "next": null,
        "prev": null
    },
    "meta": {
        "per_page": 50,
        "next_cursor": null,
        "prev_cursor": null
    }
}

Το balance_after δίνεται στρογγυλεμένο σε 2 δεκαδικά, ενώ το CourierHub κρατά το υπόλοιπο με 4: μετά τη χρέωση SMS το υπόλοιπο είναι 30.8850 και εμφανίζεται "30.89". Γι' αυτό η διαφορά δύο διαδοχικών balance_after μπορεί να μην είναι ακριβώς ίση με το amount.

Χρεώσεις voucher του Οκτωβρίου 2026 (?type=debit&transaction_type=voucher&from=2026-10-01&to=2026-10-31)

json

{
    "data": [
        {
            "id": 4,
            "type": "debit",
            "transaction_type": "voucher",
            "amount": "-0.0700",
            "balance_after": "30.93",
            "currency": "EUR",
            "description": "Χρέωση αποστολής 1 voucher (περίοδος από 01/10/2026)",
            "voucher_number": "7012345679",
            "created_at": "2026-10-19T07:15:00Z"
        }
    ],
    "links": {
        "next": null,
        "prev": null
    },
    "meta": {
        "per_page": 50,
        "next_cursor": null,
        "prev_cursor": null
    }
}

Παράδειγμα σφάλματος (μη έγκυρες παράμετροι).

GET /api/v2/balance/transactions?type=refund&from=19/10/2026&to=2026-10-01

json

{
    "message": "The given data was invalid.",
    "code": "validation_failed",
    "errors": {
        "type": [
            "The selected type is invalid."
        ],
        "from": [
            "The from field must match the format Y-m-d."
        ],
        "to": [
            "The to field must be a date after or equal to from."
        ]
    }
}

Παραδείγματα κλήσεων

Όλες οι χρεώσεις του Οκτωβρίου 2026, 100 ανά σελίδα:

bash

curl -G https://courierhub.gr/api/v2/balance/transactions \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "type=debit" \
  --data-urlencode "from=2026-10-01" \
  --data-urlencode "to=2026-10-31" \
  --data-urlencode "per_page=100"

Για τις επόμενες σελίδες ακολουθήστε το links.next, όπως στο παράδειγμα του Overview.

Κινήσεις υπολοίπου ​

Μεταβλητές αποστολής ​

Είδη κινήσεων (transaction_type) ​

Απάντηση αιτήματος ​

Παραδείγματα κλήσεων ​

Κινήσεις υπολοίπου

Μεταβλητές αποστολής

Είδη κινήσεων (`transaction_type`)

Απάντηση αιτήματος

Παραδείγματα κλήσεων