Documentație conector Dropshipper

În acest articol prezentăm informații necesare pentru partenerul care vinde în regim de dropshipping.

După configurarea partenerului în ERP, este necesar ca partenerul să implementeze transmiterea comenzilor prin acest API.

Acces la serviciu

Accesul la REST API se face cu autentificare BASIC HTTP, prin canal criptat cu SSL.

Pentru fiecare conector DropShip se genereaza un set de chei alcătuit din username și parola.

Credențialele sunt limitate pentru a scrie și citi comenzile.

Pentru termen și condiții și alte informații generice vezi articolul de mai jos care detaliază mai bine ce trebuie știut:

https://kb.bocp.eu/view/0/684-documentatie-bocp-rest-api-v1-beta.html

În continuare prezentăm endpointurile ce țin de transmiterea comenzilor în regim de DropShip:

/connector/$connectorid/order/$orderid/ 

$connectorid -  se va pune id-ul conectorului (linkul comuninicat către partener va conține acest id deja)

$orderid - id-ul comenzii din sistemul partenerului

Exemplu utilizare:

pentru a trimite comanda din sistemul extern, avand nr 122312 se trimite un POST catre:

https://secure.bocp.eu/app/rest/v1/$account/connector/$connectorid/order/122312/

pentru a actualiza comanda se trimite un PUT catre:

https://secure.bocp.eu/app/rest/v1/$account/connector/$connectorid/order/122312/

Actualizare comanda:

se permite trimiterea unui pachet partial la apelul PUT care sa contina:

obligatoriu:

• order_unique_id

optional una sau mai multe dintre următoarele câmpuri:

• order_status
• order_cancelled

la trimiterea produselor este important ca la cod produs sa se trimită codurile de la existente, în caz contrar se va returna eroare

pachetul de date cu comanda trebuie sa arate asa:

Sample order do send via post

Steps:

1. Copy the sample order below
2. Change the values to match your order
3. Send the order via POST method using json_encode() to this endpoint
4. set Content-Type: application/json

[
  'order_unique_id'=> 'ABC123456', //required
  'order_reference'=> 'ABC123456', //may be blank
  'order_date'=> '2024-01-01', //
  'order_status'=> 'new', //required
  'order_mentions'=> 'Please deliver in the morning',
  'shipping_method'=> 'courier', //required: courier, post, personal_pickup, other
  'client'=> [
    'name'=> 'John Doe',//company_name if company
    'representative'=> 'John Doe',//contact person name if name is company, may be blank
    'email'=> '',
    'phone'=> '0722222222',
    'vat_id'=> '',
    'registration_number'=> '',
    'client_unique_id'=> '123456', //recommended if available to identify same client again, will update client details!
    'invoice_address'=> [
      'city'=> 'Bucharest',
      'county'=> 'Bucharest',
      'country'=> 'Romania',
      'zip'=> '123456', //leave blank and we will guess it!
      'street'=> 'Street Name', //put all address details in this field if cannot separate it
      'number'=> '1',
      'building'=> '',
      'stair'=> '',
      'floor'=> '',
      'apartment'=> '',
      'GLN'=> ''
    ],
    'delivery_address'=> [
      'city'=> 'Bucharest',//sector if county is Bucharest
      'county'=> 'Bucharest',
      'country'=> 'Romania',
      'zip'=> '123456',
      'street'=> 'Street Name',
      'number'=> '1',
      'building'=> '',
      'stair'=> '',
      'floor'=> '',
      'apartment'=> '',
      'shipping_contact_name'=> 'John Doe',
      'shipping_contact_phone'=> '0722222222',
      'GLN'=> ''
    ]
  ],
  'items'=> [
    [
      'type'=> 'product', //required
      'code'=> 'ABC123456', //required
      'ean'=> '0789876543210', //may be blank
      'item_name'=> 'Product Name', //required
      'item_quantity'=> 2.00, //required
      'item_price'=> 100.00, //required
      'item_vat_percent'=> 19, //required
      'item_price_with_vat'=> 119, //required
      'line_value_with_vat'=> 238, //required
      'discounted_price_with_vat'=> 98, //optional
      'line_discount_value_with_vat'=> 4, //optional
    ],
    [
      'type'=> 'discount', //required
      'code'=> 'DISCOUNT', //required
      'ean'=> '', //may be blank
      'item_name'=> 'Promo Code: BONUS10', //required
      'item_quantity'=> 1.00, //required
      'item_price'=> -10.00, //required
      'item_vat_percent'=> 19, //required
      'item_price_with_vat'=> -11.9, //required
      'line_value_with_vat'=> -11.9, //required
    ],
    [
      'type'=> 'service', //required
      'code'=> 'SHIPPING', //required
      'ean'=> '', //may be blank
      'item_name'=> 'Shipping via courier', //required
      'item_quantity'=> 1.00, //required
      'item_price'=> 24.00, //required
      'item_vat_percent'=> 19, //required
      'item_price_with_vat'=> 28.56, //required
      'line_value_with_vat'=> 28.56, //required

    ],
    [
      'type'=> 'service', //required
      'code'=> 'SERVICE', //required
      'ean'=> '', //may be blank
      'item_name'=> 'Special gift wrap', //required
      'item_quantity'=> 1.00, //required
      'item_price'=> 50.00, //required
      'item_vat_percent'=> 19, //required
      'item_price_with_vat'=> 59.5, //required
      'line_value_with_vat'=> 59.5, //required

    ]
  ]

]

Sample json data:

{
    "order_unique_id": "ABC123456",
    "order_reference": "ABC123456",
    "order_date": "2024-01-01",
    "order_status": "new",
    "order_mentions": "Please deliver in the morning",
    "shipping_method": "courier",
    "client": {
        "name": "John Doe",
        "representative": "John Doe",
        "email": "",
        "phone": "0722222222",
        "vat_id": "",
        "registration_number": "",
        "client_unique_id": "123456",
        "invoice_address": {
            "city": "Bucharest",
            "county": "Bucharest",
            "country": "Romania",
            "zip": "123456",
            "street": "Street Name",
            "number": "1",
            "building": "",
            "stair": "",
            "floor": "",
            "apartment": "",
            "GLN": ""
        },
        "delivery_address": {
            "city": "Bucharest",
            "county": "Bucharest",
            "country": "Romania",
            "zip": "123456",
            "street": "Street Name",
            "number": "1",
            "building": "",
            "stair": "",
            "floor": "",
            "apartment": "",
            "shipping_contact_name": "John Doe",
            "shipping_contact_phone": "0722222222",
            "GLN": ""
        }
    },
    "items": [
        {
            "type": "product",
            "code": "ABC123456",
            "ean": "0789876543210",
            "item_name": "Product Name",
            "item_quantity": 2,
            "item_price": 100,
            "item_vat_percent": 19,
            "item_price_with_vat": 119,
            "line_value_with_vat": 238,
            "discounted_price_with_vat": 98,
            "line_discount_value_with_vat": 4
        },
        {
            "type": "discount",
            "code": "DISCOUNT",
            "ean": "",
            "item_name": "Promo Code: BONUS10",
            "item_quantity": 1,
            "item_price": -10,
            "item_vat_percent": 19,
            "item_price_with_vat": -11.9,
            "line_value_with_vat": -11.9
        },
        {
            "type": "service",
            "code": "SHIPPING",
            "ean": "",
            "item_name": "Shipping via courier",
            "item_quantity": 1,
            "item_price": 24,
            "item_vat_percent": 19,
            "item_price_with_vat": 28.56,
            "line_value_with_vat": 28.56
        },
        {
            "type": "service",
            "code": "SERVICE",
            "ean": "",
            "item_name": "Special gift wrap",
            "item_quantity": 1,
            "item_price": 50,
            "item_vat_percent": 19,
            "item_price_with_vat": 59.5,
            "line_value_with_vat": 59.5
        }
    ]
}

Notificari transmise legate de o comanda inregistrata

La configurare se introduce un URL care va primi o notificare la diferite evenimente.

URL-ul de notificare va fi anuntat prin metoda POST cu un pachet de date in format JSON.

Notificarile primite se pot citi in php prin exemplul:

$json = json_decode(file_get_contents('php://input'));

BOCP așteaptă un răspuns intepretând codul HTTP returnat, în felul urmator:

• HTTP cod 200: se consideră pachet acceptat și se închide procesul de notificare
• HTTP cod 4xx: se consideră site inexistent, comandă lipsă sau orice altă eroare permanentă și se închide notificarea
• Orice alt cod HTTP: se va retrimite periodic notificarea până când primim un cod listat mai sus

Urmatoarele tipuri de notificari vor fi transmise, ce se pot trata folosind campul notification_type:

Modificare status

exemplu pachet trimis, in format JSON:

stdClass Object
(
    [order_unique_id] => 923
    [notification_type] => status
    [status_text] => Livrată
)

Emitere Factura Fiscala

exemplu pachet trimis, in format JSON:

stdClass Object
(
    [order_unique_id] => 923
    [notification_type] => invoice
    [invoice_number] => 5243
    [invoice_date] => 2024-09-12
    [invoice_series] => SLON
    [invoice_total] => 252.00
    [invoice_currency] => RON
    [invoice_total_RON] => 252.00
    [invoice_url_html] => https://secure.bocp.eu/factura-html-linkwillbehere/
    [invoice_url_pdf] => https://secure.bocp.eu/factura-pdf-linkwillbehere/
)

Emitere AWB

exemplu pachet trimis, in format JSON:

stdClass Object
(
    [order_unique_id] => 923
    [notification_type] => awb
    [awb_number] => 1ONBLN291059727
    [awb_packet_count] => 1
    [weight] => 
    [awb_service_type] => Standard
    [shipping_payer] => expeditor
    [cash_on_delivery] => 0.00
    [cash_on_delivery_currency] => RON
    [delivery_country] => Romania
    [delivery_country_code] => RO
    [declared_value] => 252.00
    [awb_type] => sameday
    [awb_subtype] => 
    [awb_url_pdf] => https://secure.bocp.eu/awb-pdf-linkwillbehere/
)