Qrona Newsletter API · guide

Batch och idempotens

Många anrop i ett, och anrop som tål att skickas igen efter ett nätverksfel – utan att någon får två bekräftelsemejl eller en order räknas två gånger.

POST /batch

Upp till 500 anrop i ett, i tur och ordning. Varje operation har en metod, en sökväg under /api/v1 och en kropp, och kontrolleras och körs precis som om den skickats för sig: med nyckelns behörigheter, samma regler och samma fel. Svaret har status och kropp för varje operation, i samma ordning. En som misslyckas stoppar inte de andra – titta på results[].status.

curl -X POST https://newsletter.qrona.se/api/v1/batch \
  -H "Authorization: Bearer $QRONA_NEWSLETTER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f0c2b8e-3a1d-4c5e-9f7a-6b2d8e0c1a3f" \
  -d '{
    "operations": [
      { "method": "PUT", "path": "/stores/butik-se/customers/1042", "body": { "email": "anna@example.se" } },
      { "method": "PUT", "path": "/stores/butik-se/orders/50087", "body": { "customer": { "id": "1042", "email": "anna@example.se" }, "order_total": 548, "lines": [{ "id": "1", "product_id": "731", "quantity": 2, "price": 249 }] } },
      { "method": "GET", "path": "/stores/butik-se/orders?limit=10" }
    ]
  }'

{
  "results": [
    {
      "status": 201,
      "body": {
        "id": "1042",
        "email": "anna@example.se",
        "orders_count": 0
      }
    },
    {
      "status": 201,
      "body": {
        "id": "50087",
        "financial_status": "paid",
        "order_total": 548
      }
    },
    {
      "status": 200,
      "body": {
        "data": [
          "…"
        ],
        "has_more": false,
        "next_cursor": null
      }
    }
  ],
  "succeeded": 3,
  "failed": 0
}

• Kroppen får vara upp till 5 MB. En batch räknas som ett anrop mot gränsen per minut, men högst 20 batchar per minut och nyckel.
• En batch kan inte innehålla en batch. Läs mer i referensen: POST /batch.

PUT är alltid säkert att göra om

Butiker, kunder, produkter, ordrar och kundkorgar skrivs med PUT på butikens egna id:n. Samma anrop två gånger ger samma resultat, så en import som avbröts kan köras om från början, och en order skickas igen varje gång den ändras. Det gäller även kontakter med POST /contacts/upsert.

Idempotency-Key

För andra POST-anrop – en ny kontakt, en anmälan till en lista, en batch – skicka headern Idempotency-Key med ett nytt uuid för varje nytt anrop. Får ni inget svar (timeout, nätverksfel): skicka exakt samma anrop med samma nyckel. Har det första redan gått igenom får ni dess svar igen, med headern Idempotent-Replayed: true, i stället för att det görs två gånger.

curl -X POST https://newsletter.qrona.se/api/v1/lists/3f1c2a4e-8b7d-4c1e-9f0a-2d6b5e7c8a91/members \
  -H "Authorization: Bearer $QRONA_NEWSLETTER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0d6e1c4a-9b2f-4e7d-8a3c-5f1b7e9d2c4a" \
  -d '{ "email": "anna@example.se", "consent": { "text": "Ja, jag vill få nyhetsbrev från Exempel AB." } }'

• Nyckeln gäller i 24 timmar och för er API-nyckel. Den får vara 1–255 synliga ASCII-tecken.
• Samma nyckel med en annan sökväg eller kropp ger 422 idempotency_key_reused.
• Kör det första anropet fortfarande ger ett nytt 409 idempotency_in_progress: vänta och försök igen.
• Ett svar med 5xx sparas inte, så då görs anropet på riktigt nästa gång.