2.1 Integration för 3PL-partner

Early Bird Connect kan användas när en 3PL-partner plockar, packar och skickar butikens ordrar. Butiken och partnern behöver komma överens om vem som bokar transporten. Den här guiden beskriver både inställningarna i appen och de orderuppgifter som partnerns integration kan läsa från Shopify.

Välj vem som bokar transporten

Öppna Frakt → Driftläge i Early Bird Connect och välj det upplägg ni har kommit överens om.

Partnern bokar transporten

Välj Fullt 3PL-läge (endast priser och paketskåp). Early Bird Connect visar fraktalternativ och paketskåpsval och skriver kundens val till Shopify-ordern. Appen skapar inga transportbokningar eller etiketter.

Partnern bokar transporten via sin egen Early Bird-integration, hanterar etiketten och slutför orderns fulfillment i Shopify med spårningsuppgifter.

Appen bokar och skapar etiketten

Välj Autoboka även 3PL-ordrar (endast etikett). Early Bird Connect skapar transportbokningen och etiketten även för ordrar som Shopify tilldelar en 3PL.

Partnern plockar, packar och slutför orderns fulfillment i Shopify. Partnern behöver kunna använda appens etikett och spårningsuppgifter och ska inte skapa en andra transportbokning.

Metafälten i den tekniska delen nedan gäller Fullt 3PL-läge. Om ni väljer läget där appen skapar etiketter måste ni först verifiera hur partnern får tillgång till etikett och spårning i ert arbetsflöde.

Autoboka ordrar du själv skickar bokar bara automatiskt för butikens egna lagerplatser och hoppar över ordrar som tilldelas en 3PL. Det är ett annat upplägg än Fullt 3PL-läge.

Anslut butiken tillsammans med partnern

1. Välj Vi använder en 3PL-partner när ni kommer igång med appen.
2. Be partnern om Early Bird-användarnamnet och lösenordet som hör till den här butiken, och kontrollera om uppgifterna gäller Produktion eller Sandbox. Butiken behöver anslutas även när partnern ska boka transporterna.
3. Bestäm om partnern bokar i sitt eget system eller behöver etiketter från appen. Kontrollera därefter det sparade valet under Frakt → Driftläge. Att butiken använder en 3PL är inte i sig samma sak som att Fullt 3PL-läge är valt.
4. Konfigurera butikens fraktalternativ och eventuella paketskåp. Se Frakt i kassan och Paketskåp.
5. Behåll rätt lager- och 3PL-platser i Shopify. Driftläget ersätter inte Shopifys tilldelning av ordrar till den plats som ska plocka och packa.

Driftläget gäller hela butiken, inte ett separat 3PL-val på varje order. Fullt 3PL-läge stoppar nya bokningar i appen, även manuella. Befintliga bokningar fortsätter att få statusuppdateringar; ett byte av driftläge avbokar eller överlämnar dem inte automatiskt.

För partnerns utvecklare: läs ordermetafälten

I Fullt 3PL-läge skriver appen metafält på Shopify-ordern i namnrymden earlybird. Fälten är butiksägda, så partnerns egen Shopify-integration kan läsa dem med butikens godkännande och rätt orderbehörighet. Använd den uttryckliga namnrymden earlybird, inte $app:earlybird.

Samtliga fält har Shopify-typen single_line_text_field. Värdena läses som strängar.

Exempel med Shopify Admin GraphQL API

Partnerns integration behöver en egen giltig Shopify Admin API-token för butiken och behörigheten read_orders. Token skickas i X-Shopify-Access-Token. Som standard kan integrationen läsa ordrar från de senaste 60 dagarna; äldre ordrar kräver ytterligare åtkomst. Se Shopifys dokumentation om autentisering och orderåtkomst.

Kör följande fråga mot butikens Shopify Admin GraphQL API. Variabeln id ska vara orderns globala Shopify-ID, till exempel gid://shopify/Order/1234567890.

query EarlyBirdHandoff($id: ID!) {
  order(id: $id) {
    id
    name
    shippingLines(first: 10) {
      nodes {
        title
        code
        source
        isRemoved
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
    operatingMode: metafield(namespace: "earlybird", key: "operating_mode") {
      type
      value
    }
    serviceCode: metafield(namespace: "earlybird", key: "service_code") {
      value
    }
    deliveryPointId: metafield(namespace: "earlybird", key: "delivery_point_id") {
      value
    }
    deliveryPointName: metafield(namespace: "earlybird", key: "delivery_point_name") {
      value
    }
    deliveryPointAddress: metafield(namespace: "earlybird", key: "delivery_point_address") {
      value
    }
  }
}

Ett saknat metafält ger null. Exemplet hämtar upp till tio fraktrader; om hasNextPage är true behöver integrationen även hämta resterande sidor. Borttagna fraktrader (isRemoved: true) ska inte användas som aktuellt fraktval. Fälten finns beskrivna i Shopifys referenser för Order och ShippingLine.

Kontrollera fraktvalet före bokning

operating_mode = rates_only betyder att ordern behandlades i Fullt 3PL-läge. Det bevisar inte att kunden valde Early Bird. Markeringen skrivs även på betalda ordrar med andra fraktalternativ.

Partnern behöver därför kontrollera orderns aktuella fraktrader mot butikens konfigurerade Early Bird-alternativ och mappa tjänstekoden till rätt tjänst i sitt bokningssystem. Om appen inte kan identifiera tjänsten kan service_code innehålla fraktradens ursprungliga kod. Okända koder ska granskas; de ska inte automatiskt behandlas som hemleverans.

För box.delivery behövs ett giltigt delivery_point_id samt mottagarens telefon och e-post. Saknas skåp-ID ska partnern invänta eller reda ut valet innan bokning. Namn och adress är kompletterande uppgifter och ersätter inte ID:t.

Metafälten beskriver kundens val och är ingen bekräftelse på att en transport har bokats eller att adressen kan levereras till. Partnern behöver validera adress, tjänst och övriga bokningsuppgifter i sin Early Bird-integration. Läs även hur fraktalternativ och täckningskontroll fungerar.

När uppgifterna skrivs och ändras

Metafälten skrivs när appen behandlar Shopifys orders/paid-händelse. Det sker i bakgrunden efter betalningen. Partnerns egen orderimport eller betalningshändelse kan därför komma före metafälten. Läs om ordern med återförsök om uppgifterna saknas; frånvaro är inte ett säkert besked om driftläge eller fraktval. Misslyckas appens skrivning i betalningsflödet returnerar appen ett fel så att Shopify kan försöka leverera händelsen igen.

Om kunden väljer eller byter paketskåp efter köpet försöker appen uppdatera samma metafält. Dessa senare skrivningar görs utan att stoppa kundens skåpval vid ett tillfälligt fel, så metafälten kan i det läget saknas eller visa ett tidigare val. Ett senare skåpbyte gör ett nytt skrivförsök. Partnern och butiken behöver därför ha en rutin för sena ändringar och avvikande uppgifter innan transporten bokas.

Gör orderimport och bokning tåliga mot upprepade händelser: kontrollera om partnerns system redan har bokat transporten innan en ny bokning skapas.

Testa överlämningen före driftstart

• Anslutning: kontrollera butikens Early Bird-konto, miljö, driftläge och partnerns åtkomst till ordermetafälten.
• Hemleverans: betala en testorder, läs fraktvalet och home, och verifiera att partnern skapar en enda transportbokning. I Fullt 3PL-läge ska appen inte skapa en bokning.
• Paketskåp: verifiera box.delivery, rätt skåp-ID, telefon och e-post. Testa även saknat och ändrat skåpval efter köpet.
• Andra fraktalternativ: verifiera att partnern inte bokar Early Bird enbart för att rates_only finns på ordern.
• Fördröjningar och fel: testa saknade metafält, en upprepad orderhändelse och en adress som transportören inte accepterar. Ordern ska kunna hanteras utan dubbelbokning.
• Leveransflödet: verifiera etikett, spårning och att rätt part slutför fulfillment i Shopify.

Behöver ni hjälp att få överlämningen att fungera? Kontakta oss via supportformuläret och ange butik, 3PL-partner, valt driftläge och ordernummer. Bifoga gärna det exakta felmeddelandet.