Fatturazione

Leggi il tuo saldo e quello dei tuoi clienti, e sposta credito a un cliente della tua rete. Il tuo account deve essere abilitato alla rete clienti; gli altri account ricevono 403 FEATURE_NOT_ENABLED.

GET/balance

Get your prepaid balance

In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.

Solo per gli account abilitati alla rete clienti. Gli altri account ricevono 403 FEATURE_NOT_ENABLED.

Remaining prepaid credit of your (master) account.

Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.

Autenticazione: la tua chiave API nell'header X-API-Key.

Risposte

  • 200Balance.Balance
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

GET
/balance
Caricamento...

Risposta 200

{
  "balance": {
    "amount": "245.90",
    "currency": "EUR"
  }
}
GET/customers/{customer_id}/balance

Get the balance of a customer

In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.

Solo per gli account abilitati alla rete clienti. Gli altri account ricevono 403 FEATURE_NOT_ENABLED.

Remaining prepaid credit of a customer of your network. 404 CUSTOMER_NOT_FOUND when the customer does not exist or is not in your network.

Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.

Autenticazione: la tua chiave API nell'header X-API-Key.

Parametri

  • Name
    customer_id
    Type
    string
    obbligatorio
    Description

    Customer id.

Risposte

  • 200Balance.CustomerBalance
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

GET
/customers/{customer_id}/balance
Caricamento...

Risposta 200

{
  "customer_id": "3723",
  "balance": {
    "amount": "23.75",
    "currency": "EUR"
  }
}
POST/credit-transfers

Move credit to a customer

In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.

Solo per gli account abilitati alla rete clienti. Gli altri account ricevono 403 FEATURE_NOT_ENABLED.

Transfers prepaid credit from your master account to a customer of your network. The master credit must cover the amount, otherwise 422 INSUFFICIENT_CREDIT. Only for accounts with the network function. Your own top-up by card is a dashboard feature, not part of this API.

Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.

Autenticazione: la tua chiave API nell'header X-API-Key.

Parametri

  • Name
    Idempotency-Key
    Type
    string
    obbligatorio
    Description

    Unique key (UUID recommended, max 255 characters) that makes the write safe to retry. A retry with the same key and body returns the first response with Idempotent-Replayed: true; same key with a different body is 422 IDEMPOTENCY_KEY_REUSED; while the first call is running, 409 IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400 IDEMPOTENCY_KEY_REQUIRED.

    length ≥ 1, length ≤ 255.

Corpo della richiesta CreditTransferCreate

  • Name
    customer_id
    Type
    string
    obbligatorio
    Alias italiano: idcustomer
    Description

    Customer to credit; must belong to your network.

  • Name
    amount
    Type
    MoneyAmount
    obbligatorio
    Alias italiano: amount
    Description

    Amount to move from your master account. Must not exceed your master credit.

Risposte

  • 201Transfer done.CreditTransfer
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 422The request is well formed but a business rule refuses it. Codes: INSUFFICIENT_CREDIT, SERVICE_NOT_AVAILABLE, CARRIER_NOT_AVAILABLE, IDEMPOTENCY_KEY_REUSED, ...Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

POST
/credit-transfers
Caricamento...

Risposta 201

{
  "id": "ct_01JD2X",
  "customer_id": "3723",
  "amount": {
    "amount": "100.00",
    "currency": "EUR"
  },
  "master_balance": {
    "amount": "145.90",
    "currency": "EUR"
  },
  "created_at": "2026-12-09T09:31:59+00:00"
}

Modelli

Oggetti usati dalle richieste e dalle risposte di questa pagina.

ParceLabsVersion

CorrelationId

KeyLocale

Balance

  • Name
    balance
    Type
    Money
    obbligatorio
    Alias italiano: saldo
    Description

    Remaining prepaid credit.

Money

An amount of money. Responses always use this object; requests send a plain number (see MoneyAmount).

  • Name
    amount
    Type
    string
    obbligatorio
    Alias italiano: importo
    Description

    Decimal amount as a string with exactly two decimals. Never a float.

  • Name
    currency
    Type
    string
    obbligatorio
    Alias italiano: valuta
    Description

    ISO 4217 currency. v1 is EUR only.

    Valori ammessi: EUR.

Unauthorized

Forbidden

Gone

TooManyRequests

ServerError

BadGateway

CustomerBalance

  • Name
    customer_id
    Type
    string
    obbligatorio
    Alias italiano: idcustomer
    Description

    Customer id.

  • Name
    balance
    Type
    Money
    obbligatorio
    Alias italiano: balance_customer
    Description

    Remaining prepaid credit of the customer.

NotFound

CreditTransferCreate

  • Name
    customer_id
    Type
    string
    obbligatorio
    Alias italiano: idcustomer
    Description

    Customer to credit; must belong to your network.

  • Name
    amount
    Type
    MoneyAmount
    obbligatorio
    Alias italiano: amount
    Description

    Amount to move from your master account. Must not exceed your master credit.

MoneyAmount

Amount in EUR sent in a request, as a JSON number with a dot as decimal separator (never a comma). Up to two decimals.

Location

Postal location used to price a shipment.

  • Name
    postal_code
    Type
    string
    obbligatorio
    Alias italiano: cap
    Description

    Postal code.

  • Name
    city
    Type
    string
    obbligatorio
    Alias italiano: localita
    Description

    City or town.

  • Name
    province
    Type
    string
    Alias italiano: provincia
    Description

    Italian province code. Use -- for foreign addresses.

  • Name
    state_code
    Type
    string
    Alias italiano: codice_stato
    Description

    State or province code. Required for US and CA destinations, otherwise omit.

  • Name
    country_code
    Type
    string
    obbligatorio
    Alias italiano: nazione
    Description

    ISO 3166-1 alpha-2 country code.

IdempotentReplayed

CreditTransfer

  • Name
    id
    Type
    string
    Alias italiano: id
    Description

    Transfer id. QUESTION FOR CLAUDIO: legacy returns none; needed for idempotent replays and audit.

  • Name
    customer_id
    Type
    string
    obbligatorio
    Alias italiano: idcustomer
    Description

    Credited customer.

  • Name
    amount
    Type
    Money
    obbligatorio
    Alias italiano: amount
    Description

    Amount moved.

  • Name
    master_balance
    Type
    Money
    Alias italiano: saldo_principale
    Description

    Master balance after the transfer.

  • Name
    created_at
    Type
    string (date-time)
    obbligatorio
    Alias italiano: timestamp
    Description

    When.

BadRequest

Unprocessable

Was this page helpful?