Documentație APIAPI Documentation · Contract propriu (BYOC)Own contract (BYOC)
Contract propriu (BYOC)Own contract (BYOC)
BYOC („Bring Your Own Contract”) înseamnă că emiți prin SmartShip pe contractul tău direct cu curierul: AWB-ul se creează în contul tău de la curier, la prețul negociat de tine. SmartShip îți dă platforma, API-ul, urmărirea și etichetele. Pagina descrie doar ce este diferit; tot restul (autentificare, obiectele sender / recipient / content, status, print, anulare, decontări) funcționează exact ca în documentația standard.BYOC ("Bring Your Own Contract") means you ship through SmartShip on your own direct contract with the courier: the AWB is created in your courier account, at your negotiated price. SmartShip provides the platform, the API, tracking and labels. This page covers only what is different; everything else (authentication, the sender / recipient / content objects, status, print, cancellation, payouts) works exactly as in the standard documentation.
Ce îți trebuieRequirements
1) BYOC activ pe cont, din platformă: Curieri Proprii. 2) Contul tău de curier conectat în aceeași secțiune (utilizator, parolă / cheie API de la curier). Contractul potrivit se alege automat după courier_id și contul tău — nu trimiți niciun ID de contract.1) BYOC enabled on your account, in the platform: Own Couriers. 2) Your courier account connected in the same section (username, password / courier API key). The right contract is picked automatically from courier_id and your account — you never send a contract ID.
Curieri disponibili pe BYOCCouriers available on BYOC
1Cargus1Cargus2SameDay (inclusiv livrare la easybox, vezi mai jos)2SameDay (including easybox delivery, see below)3FanCourier (inclusiv livrare la FANbox)3FanCourier (including FANbox delivery)5DragonStar5DragonStar6DPD6DPD14PTT Express14PTT Express34Transilvania Post34Transilvania Post35Komy (fără ramburs)35Komy (no cash on delivery)
Cum alegi contractul propriuHow to use your own contract
Câmpurile de mai jos se trimit la nivelul principal al cererii, nu în content. Fără use_own_contract: 1, AWB-ul se emite pe contractul SmartShip, cu tariful standard — trecerea pe contractul tău nu se face automat.The fields below go at the top level of the request, not inside content. Without use_own_contract: 1, the AWB is created on the SmartShip contract at standard pricing — switching to your contract is never automatic.
| CâmpField | Tip | DescriereDescription | |
|---|---|---|---|
show_byoc | integer | opționaloptional | La /cost: 1 = adaugă în răspuns și prețurile pe contractele tale. Același curier poate apărea de două ori (contractul tău și cel SmartShip); liniile tale au own_contract: true. Implicit 0.On /cost: 1 = also return the prices on your contracts. The same courier may appear twice (your contract and the SmartShip one); your lines have own_contract: true. Default 0. |
only_byoc | integer | opționaloptional | La /cost: 1 = DOAR contractele tale + SmartShip Delivery (16, dacă acoperă ruta). Răspuns mult mai rapid, fiindcă nu mai cotăm conturile SmartShip. Implicit 0.On /cost: 1 = ONLY your contracts + SmartShip Delivery (16, if it covers the route). Much faster, since SmartShip accounts are not quoted. Default 0. |
use_own_contract | integer | opționaloptional | La /awb/new: 1 = emite AWB-ul pe contractul tău la curierul din courier_id. Implicit 0.On /awb/new: 1 = create the AWB on your contract with the courier in courier_id. Default 0. |
Livrare la locker pe contract propriuLocker delivery on your own contract
easybox: pe BYOC nu există un curier separat pentru easybox. Emiți cu courier_id: 2 (SameDay) + use_own_contract: 1 + content.locker_id din /geolocation/easybox — livrarea comută automat la locker. Cu courier_id: 12 pe BYOC primești eroarea 4004.easybox: on BYOC there is no separate easybox courier. Create the AWB with courier_id: 2 (SameDay) + use_own_contract: 1 + content.locker_id from /geolocation/easybox — delivery switches to the locker automatically. With courier_id: 12 on BYOC you get error 4004.
FANbox: courier_id: 3 (FanCourier) + use_own_contract: 1 + content.locker_id din /geolocation/fanbox. Maxim 30 kg și un singur colet pe AWB.FANbox: courier_id: 3 (FanCourier) + use_own_contract: 1 + content.locker_id from /geolocation/fanbox. Max 30 kg and a single parcel per AWB.
Ce este diferit față de contractul SmartShipDifferences from the SmartShip contract
- Răspunsul la
/awb/newconțineown_contract: true, iarcosteste costul real de la curier, pe contractul tău.The/awb/newresponse containsown_contract: true, andcostis the courier's real cost on your contract. - Colet la schimb (
swap: 1): pe BYOC doar la PTT Express (14).Exchange parcel (swap: 1): on BYOC only with PTT Express (14). - Predare personală (
personal_drop_off) nu este disponibilă pe BYOC — eroarea4005.Personal drop-off (personal_drop_off) is not available on BYOC — error4005. - Komy (35) nu acceptă ramburs: cu
cash_on_delivery> 0 primești4050și nu apare nici la/cost.Komy (35) does not accept cash on delivery: withcash_on_delivery> 0 you get4050, and it is not returned by/costeither.
Coduri de eroare doar pe BYOCBYOC-only error codes
Pe lângă erorile din documentația standard, pe contract propriu mai poți primi:In addition to the errors in the standard documentation, on your own contract you may also get:
| 4001 | Curierul din courier_id nu este disponibil pe contract propriu (vezi lista de mai sus).The courier in courier_id is not available on own contract (see the list above). |
| 4002 | BYOC nu este activ pe cont. Câmpul cod spune motivul: NO_SUBSCRIPTION, GRACE_PERIOD (plată eșuată), NOT_STARTED, EXPIRED, LIMIT_REACHED (limita lunară a planului).BYOC is not active on the account. The cod field gives the reason: NO_SUBSCRIPTION, GRACE_PERIOD (failed payment), NOT_STARTED, EXPIRED, LIMIT_REACHED (monthly plan limit). |
| 4003 | Nu ai un contract conectat pentru acest curier — adaugă-l în Curieri Proprii.You have no connected contract for this courier — add it in Own Couriers. |
| 4004 | Ai trimis courier_id: 12 (easybox) pe BYOC — folosește courier_id: 2 + locker_id.You sent courier_id: 12 (easybox) on BYOC — use courier_id: 2 + locker_id. |
| 4005 | personal_drop_off: 1 nu este disponibil pe BYOC.personal_drop_off: 1 is not available on BYOC. |
| 4030 | Sold insuficient pentru taxa BYOC (sub limita permisă) — alimentează contul.Insufficient balance for the BYOC fee (below the allowed limit) — top up your account. |
| 4050 | Komy (35) cu ramburs — Komy nu acceptă ramburs.Komy (35) with cash on delivery — Komy does not accept COD. |
| 4010–4014 | Curierul a refuzat emiterea pe contractul tău (ex. autentificare SameDay eșuată, localitate neidentificată, eroare PTT Express / Transilvania Post). Câmpul courier_error conține răspunsul curierului.The courier rejected the AWB on your contract (e.g. SameDay authentication failed, unknown locality, PTT Express / Transilvania Post error). The courier_error field contains the courier's response. |
| 4043, 4044, 4045 | FANbox: locker_id invalid / peste 30 kg / mai mult de un colet.FANbox: invalid locker_id / over 30 kg / more than one parcel. |
ExempleExamples
Estimare doar pe contractele tale (only_byoc)Quote on your contracts only (only_byoc)
curl -X POST "https://api.smartship.ro/cost" \
-H "X-API-KEY: CHEIA_TA_API" \
-H "Content-Type: application/json" \
-d '{
"only_byoc": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Piese auto",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 0,
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"iban": "",
"open_package": 0
}
}'$payload = json_decode('{
"only_byoc": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Piese auto",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 0,
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"iban": "",
"open_package": 0
}
}', true);
$ch = curl_init("https://api.smartship.ro/cost");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
"X-API-KEY: CHEIA_TA_API",
"Content-Type: application/json",
],
]);
$response = json_decode(curl_exec($ch), true);const response = await fetch("https://api.smartship.ro/cost", {
method: "POST",
headers: {
"X-API-KEY": "CHEIA_TA_API",
"Content-Type": "application/json",
},
body: JSON.stringify({
"only_byoc": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Piese auto",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 0,
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"iban": "",
"open_package": 0
}
}),
});
const data = await response.json();import requests
response = requests.post(
"https://api.smartship.ro/cost",
headers={"X-API-KEY": "CHEIA_TA_API"},
json={
"only_byoc": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Piese auto",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 0,
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"iban": "",
"open_package": 0
}
},
)
data = response.json()Emitere pe contractul tău DPDCreate an AWB on your DPD contract
curl -X POST "https://api.smartship.ro/awb/new" \
-H "X-API-KEY: CHEIA_TA_API" \
-H "Content-Type: application/json" \
-d '{
"courier_id": 6,
"use_own_contract": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Piese auto",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 150,
"iban": "RO49AAAA1B31007593840000",
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"open_package": 0,
"order_id": "CMD-4821"
}
}'$payload = json_decode('{
"courier_id": 6,
"use_own_contract": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Piese auto",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 150,
"iban": "RO49AAAA1B31007593840000",
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"open_package": 0,
"order_id": "CMD-4821"
}
}', true);
$ch = curl_init("https://api.smartship.ro/awb/new");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
"X-API-KEY: CHEIA_TA_API",
"Content-Type: application/json",
],
]);
$response = json_decode(curl_exec($ch), true);const response = await fetch("https://api.smartship.ro/awb/new", {
method: "POST",
headers: {
"X-API-KEY": "CHEIA_TA_API",
"Content-Type": "application/json",
},
body: JSON.stringify({
"courier_id": 6,
"use_own_contract": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Piese auto",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 150,
"iban": "RO49AAAA1B31007593840000",
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"open_package": 0,
"order_id": "CMD-4821"
}
}),
});
const data = await response.json();import requests
response = requests.post(
"https://api.smartship.ro/awb/new",
headers={"X-API-KEY": "CHEIA_TA_API"},
json={
"courier_id": 6,
"use_own_contract": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Piese auto",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 150,
"iban": "RO49AAAA1B31007593840000",
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"open_package": 0,
"order_id": "CMD-4821"
}
},
)
data = response.json(){
"status": 200,
"message": "AWB created (BYOC).",
"awb": "81396540190",
"courier_id": 6,
"courier_name": "DPD",
"cost": 16.61,
"cost_fara_tva": 13.73,
"pdf_link": "https://smartship.ro/api/CHEIA_TA_API/print/81396540190",
"tracking_url": "https://smartship.ro/t/aB3xK9mQw2",
"own_contract": true
}
Emitere la FANbox, pe contractul tău FanCourierFANbox delivery on your FanCourier contract
curl -X POST "https://api.smartship.ro/awb/new" \
-H "X-API-KEY: CHEIA_TA_API" \
-H "Content-Type: application/json" \
-d '{
"courier_id": 3,
"use_own_contract": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Cosmetice",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 0,
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"open_package": 0,
"locker_id": "FAN0968"
}
}'$payload = json_decode('{
"courier_id": 3,
"use_own_contract": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Cosmetice",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 0,
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"open_package": 0,
"locker_id": "FAN0968"
}
}', true);
$ch = curl_init("https://api.smartship.ro/awb/new");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
"X-API-KEY: CHEIA_TA_API",
"Content-Type: application/json",
],
]);
$response = json_decode(curl_exec($ch), true);const response = await fetch("https://api.smartship.ro/awb/new", {
method: "POST",
headers: {
"X-API-KEY": "CHEIA_TA_API",
"Content-Type": "application/json",
},
body: JSON.stringify({
"courier_id": 3,
"use_own_contract": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Cosmetice",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 0,
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"open_package": 0,
"locker_id": "FAN0968"
}
}),
});
const data = await response.json();import requests
response = requests.post(
"https://api.smartship.ro/awb/new",
headers={"X-API-KEY": "CHEIA_TA_API"},
json={
"courier_id": 3,
"use_own_contract": 1,
"recipient": {
"name": "Ion Vasile",
"address": "Str. Memorandumului 28",
"email": "[email protected]",
"city": 256212,
"phone": "0720123456",
"country": "RO",
"sector": 0
},
"sender": {
"name": "Magazinul Meu SRL",
"address": "Str. Polonă 68",
"email": "[email protected]",
"city": 255154,
"phone": "0720333222",
"country": "RO",
"sector": 1
},
"content": {
"package_content": "Cosmetice",
"parcels": 1,
"weight": 2,
"cash_on_delivery": 0,
"length": 30,
"width": 20,
"height": 10,
"insurance": 0,
"open_package": 0,
"locker_id": "FAN0968"
}
},
)
data = response.json()Listă lockere FANboxList FANbox lockers
Returnează lista lockerelor FANbox (FAN Courier) disponibile pentru livrare la locker. Folosește locker_id de aici la emiterea pe contract propriu FanCourier (courier_id: 3 + use_own_contract: 1 + content.locker_id).Returns the list of FANbox (FAN Courier) lockers available for locker delivery. Use the locker_id from here when creating an AWB on your own FanCourier contract (courier_id: 3 + use_own_contract: 1 + content.locker_id).
curl -X GET "https://api.smartship.ro/geolocation/fanbox" \
-H "X-API-KEY: CHEIA_TA_API"$ch = curl_init("https://api.smartship.ro/geolocation/fanbox");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-API-KEY: CHEIA_TA_API",
"Content-Type: application/json",
],
]);
$response = json_decode(curl_exec($ch), true);const response = await fetch("https://api.smartship.ro/geolocation/fanbox", {
method: "GET",
headers: {
"X-API-KEY": "CHEIA_TA_API",
"Content-Type": "application/json",
},
});
const data = await response.json();import requests
response = requests.get(
"https://api.smartship.ro/geolocation/fanbox",
headers={"X-API-KEY": "CHEIA_TA_API"},
)
data = response.json()







