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 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.Balance401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated 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.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Richiesta
Caricamento...
Risposta 200
{
"balance": {
"amount": "245.90",
"currency": "EUR"
}
}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.CustomerBalance401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated 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.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Richiesta
Caricamento...
Risposta 200
{
"customer_id": "3723",
"balance": {
"amount": "23.75",
"currency": "EUR"
}
}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 422IDEMPOTENCY_KEY_REUSED; while the first call is running, 409IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400IDEMPOTENCY_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.CreditTransfer400Malformed or invalid request. Codes:VALIDATION_ERROR(withdetails.errors),INVALID_JSON,IDEMPOTENCY_KEY_REQUIRED,UNSUPPORTED_VERSION.Error401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated 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.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error410Version retired. CodeVERSION_RETIRED.Error422The request is well formed but a business rule refuses it. Codes:INSUFFICIENT_CREDIT,SERVICE_NOT_AVAILABLE,CARRIER_NOT_AVAILABLE,IDEMPOTENCY_KEY_REUSED, ...Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Richiesta
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.