Documentație conector eCommerce - trimiterea comenzilor în BOCP CloudSales ERP

Transmiterea comenzilor în BOCP prin API-ul REST

În acest articol prezentăm informațiile necesare pentru implementarea transmiterii comenzilor în BOCP prin API-ul REST.

Concept

În ERP se creează un conector nou pentru fiecare sursă în parte.
Acest conector primește o cheie de acces pentru a putea transmite comenzile în BOCP.
Comenzile vor fi afișate în modulul Comenzi eCommerce, iar sursa va fi denumirea conectorului.
Se configurează un URL pentru notificări de comandă. Pe acest URL se vor trimite actualizări legate de comanda respectivă (emitere AWB și factură).

Sincornizarea stocurilor și prețurilor cu acest conector:

în lucru: la cerere vom expune aici o rută API pentru a trimite la BOCP produsele de pe site, această metodă va înregistra o referință și programa o notificare de stoc și preț pe un URL extern. În caz de nevoie vă rugăm să ne contactați.

Configurare

Se accesează modulul Integrări → Conectori eCommerce.

Se creează un conector nou de tip BOCP REST API Connector.
Atenție: numărul conectorilor disponibili poate varia în funcție de pachet.

Se introduce un nume pentru site, pentru a identifica sursa comenzilor.

După crearea conectorului, se generează automat un user și o parolă pentru API-ul REST și se afișează endpoint-ul API generat pentru acel conector.

Opțional, se poate configura un URL care va primi actualizările legate de comenzile primite.

Acces la serviciul API

Accesul la REST API se face cu autentificare HTTP BASIC, printr-un canal criptat SSL.

Pentru fiecare conector se utilizează un set de credențiale format din username și parolă.

Credențialele permit citirea și scrierea comenzilor.

Pentru termeni, condiții și alte informații generale, consultați articolul de mai jos, care detaliază informațiile necesare:
https://kb.bocp.eu/view/0/684-documentatie-bocp-rest-api-v1-beta.html

Endpoint-uri pentru transmiterea comenzilor

/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:

Copy the sample order below
Change the values to match your order
Send the order via POST method using json_encode() to this endpoint
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/
)