Hoe werkt de API van Order2Flow ( EDI )?

Laat zakelijke klanten via de EDI-API van Order2Flow rechtstreeks orders plaatsen en opvragen, beveiligd met een eigen API-token.

Onze EDI biedt een API-interface, zodat je klanten direct en veilig hun orders in Order2Flow kunnen plaatsen. Hiervoor hoeven zij zelf geen toegang te hebben tot de webinterface van Order2Flow.

Hieronder lees je hoe je een EDI-user aanmaakt. Daarna leggen we uit hoe je klant, als user, een order invoert via onze API.

Voor deze pagina moet de functie EDI in je account aan staan. Zie je de genoemde schermen niet, neem dan contact met ons op.

Uitleg EDI algemeen #

Validatie #

• Validatie gebeurt via een JWT-token.
• Via de backend kan voor een user een token worden aangemaakt, die gebruikt moet worden als bearer token in de requests naar de EDI.
• De EDI-endpoints zijn toegankelijk voor de rol “ediuser”.
• De gebruiker wordt opgezocht op basis van de token.
• Er is alleen toegang tot bronnen die door die user zijn aangemaakt, en die horen bij het gekoppelde account.
• Toegang tot EDI is toegang tot alle EDI-endpoints.

Stappen om een EDI-gebruiker toe te voegen #

1. Maak een nieuwe user aan met de rol “Edi User”.
2. Maak een account aan dat gelinkt is aan deze user. Het is mogelijk om meerdere accounts te koppelen aan één EDI user.
3. Genereer een API-token vanuit het overzicht onder Instellingen > Gebruikers en toegang > Gebruikers met de knop EDI API-token en kopieer deze token. Je ziet de token maar één keer.

Known issues #

• De rollen van een gebruiker worden opgeslagen in het token. Als de rol van een ediuser wordt gewijzigd, blijft het oude token geldig met de oude rechten. Het is aan te raden in dat geval een nieuw token te genereren.
• Er kan nu met “addToExistingOrder” met true/false worden toegevoegd aan de call om de standaard instellingen te overschrijven.

Uitleg velden: #

• reference (string, optioneel): Een unieke referentie voor de order. Als deze niet wordt meegegeven, genereert het systeem er een.
• account (string, optioneel): De naam van het account waartoe de order behoort. Alleen verplicht als de EDI-gebruiker aan meer dan één account is gekoppeld.
• orderLines (array, verplicht): Een lijst van één of meer orderregels.
  • quantity (string|integer, verplicht): Het aantal.
  • product (object, verplicht): Een object om het product te identificeren. Geef ofwel sku, ean, of id op.
  • width, length (integer, optioneel): Afmetingen in millimeters, vereist voor producten met prijsberekening per oppervlakte.
  • notes, description (string, optioneel): Extra notities of een omschrijving voor de orderregel.
  • files (array, optioneel): Een lijst van bestanden om aan deze orderregel te koppelen.
    • content (string, verplicht): De inhoud van het bestand, Base64-encoded.
    • name (string, optioneel): De bestandsnaam, inclusief extensie (bv. tekening.pdf). Indien niet opgegeven, wordt een generieke naam gebruikt.
    • label (string, optioneel): Een korte omschrijving of label voor het bestand (max 25 characters).

Uitleg order-EDI Order aanmaken #

url: /edi/v3/catalog/orders
method: POST
authorization: bearer token
header: Content-Type: application/json
body (json):

{
    "reference": "unieke_order_referentie",
    "account": "account_naam",
    "addToExistingOrder": false,
    "orderLines": [
        {
            "quantity": "2",
            "width": 1000,
            "length": 1000,
            "notes": "notitie voor orderregel",
            "description": "omschrijving voor orderregel",
            "product": {
                "sku": "Product-SKU-123"
            },
            "files": [
                {
                    "name": "tekening.pdf",
                    "content": "JVBERi0xLjQKJe...",
                    "label": "Technische tekening"
                },
                {
                    "content": "iVBORw0KGgoAAA...",
                    "label": "Referentiefoto"
                }
            ]
        },
        {
            "quantity": "1",
            "product": {
                "ean": "1234567890123"
            }
        }
    ]
}

Bovenstaande request zal een response/ resultaat geven soortgelijk aan onderstaande:

{
    "_data": {
        "orderId": 22,
        "reference": "unieke_order_referentie",
        "success": true
    }
}

Order ophalen #

url: /edi/v3/catalog/orders/[order id]
method: GET
authorization: bearer token

Aan onderstaande kan een optionele parameter worden toegevoegd, namelijk: expand (voorbeeld url suffix: ?expand=orderLine,fulfilment,transport). Dit zal een response/resultaat geven soortgelijk aan onderstaande:

{
    "_data": {
        "id": 21,
        "shippingMethod": null,
        "paymentMethod": null
    }
}

Welke knoppen je ziet, hangt af van je rechten.