Avize de expediție (ASN)

Un aviz de expediție (ASN) anunță depozitul că vine marfă: ce produse, în ce cantități și cu ce referință. Depozitul se pregătește pe baza avizului, iar la recepție cifrele (primit, acceptat, deteriorat, respins) apar pe liniile lui. Aceste rute sunt disponibile cheilor de client (permisiunile asns:read și asns:write); fiecare client vede și creează doar avizele proprii.

Endpoint-uri

Operație	Descriere
GET /api/v1/asns	Listă paginată, cea mai nouă întâi; filtru status, per_page (implicit 25, cel mult 100).
GET /api/v1/asns/{id}	Citește un aviz cu liniile lui.
POST /api/v1/asns	Anunță o recepție. Acceptă Idempotency-Key.
POST /api/v1/asns/{id}/cancel	Anulează un aviz pe care depozitul nu a început să-l recepționeze.

Schema răspunsului

Toate cele patru rute răspund cu aceeași schemă pentru o cheie de client: id, reference, status, expected_on, expected_at, arrived_at, carrier, tracking_number, container_number, seal_number, source, client_confirmed_at, closed_short_at, warehouse ({ "code": "…" } sau null) și lines[]. Fiecare linie are id, product_id, sku, expected_quantity, received_quantity, accepted_quantity, damaged_quantity, rejected_quantity, batch_number, expiry_date și origin. Nota de sosire a depozitului, sesiunea de recepție și câmpul notes nu fac parte din răspuns.

Cifrele de recepție ale unei linii se completează pe măsură ce depozitul recepționează marfa: received_quantity este tot ce a fost numărat, din care accepted_quantity este stocul bun, damaged_quantity marfa deteriorată sau expirată reținută, iar rejected_quantity marfa respinsă.

Exemplu, un aviz abia anunțat, înainte de recepție (verificat automat față de schema înghețată):

{
  "data": {
    "id": 42,
    "reference": "ASN-2026-0042",
    "status": "announced",
    "expected_on": "2026-06-20",
    "expected_at": null,
    "arrived_at": null,
    "carrier": "DHL",
    "tracking_number": "JD0146000012345",
    "container_number": null,
    "seal_number": null,
    "source": "client",
    "client_confirmed_at": null,
    "closed_short_at": null,
    "warehouse": null,
    "lines": [
      {
        "id": 311,
        "product_id": 812,
        "sku": "BRK-PAD-001",
        "expected_quantity": 20,
        "received_quantity": 0,
        "accepted_quantity": 0,
        "damaged_quantity": 0,
        "rejected_quantity": 0,
        "batch_number": "B-2026-06",
        "expiry_date": null,
        "origin": null
      }
    ]
  }
}

Creare aviz

POST /api/v1/asns.

Câmp	Tip	Obligatoriu	Note
reference	string ≤ 100	da	Referința ta. Unică per client: o referință deja folosită primește 409 cu code: duplicate_reference.
lines	array (min 1)	da	Liniile anunțate.
lines[].sku	string	da*	*Sau lines[].product_id. Produsul trebuie să existe în catalogul clientului.
lines[].product_id	integer	da*	Alternativă la sku.
lines[].expected_quantity	integer ≥ 1	da	Cantitatea anunțată.
lines[].batch_number	string ≤ 100	nu	Lot.
lines[].expiry_date	dată	nu	Data de expirare.
expected_on	dată	nu	Ziua așteptată a sosirii.
expected_at	dată și oră	nu	Momentul planificat; când lipsește expected_on, ziua se deduce din el.
carrier, tracking_number	string ≤ 100	nu	Transportatorul și numărul lui de urmărire.
container_number, seal_number	string ≤ 100	nu	Containerul și sigiliul.
receiving_instructions	string ≤ 2000	nu	Instrucțiuni pentru recepție.
notes	string ≤ 1000	nu	Notă; nu se întoarce în răspunsul pentru chei de client.
warehouse_id	integer	nu	Doar pe un tenant cu mai multe depozite; trebuie să fie un depozit al clientului, altfel 422 cu error: warehouse_not_entitled.

client_id nu se trimite cu o cheie de client: cererea cu acest câmp este refuzată (422), iar clientul este mereu cel al cheii.

Un produs negăsit în catalogul clientului respinge tot avizul cu 422 și code: unknown_product; nu se creează un aviz parțial. Un client suspendat sau în ieșire nu mai poate anunța marfă nouă.

curl -X POST https://tenant.notsowms.ro/api/v1/asns \
  -H "Authorization: Bearer tenant.7c4a8d09ca3762af61e59520943dc26494f8941b" \
  -H "Idempotency-Key: asn-2026-0042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ASN-2026-0042",
    "expected_on": "2026-06-20",
    "carrier": "DHL",
    "tracking_number": "JD0146000012345",
    "lines": [
      { "sku": "BRK-PAD-001", "expected_quantity": 20, "batch_number": "B-2026-06" }
    ]
  }'

Răspunsul 201 este avizul în schema de mai sus, sub data.

Reîncercare sigură cu Idempotency-Key

Trimite un identificator unic al cererii în antetul Idempotency-Key (sau în câmpul idempotency_key; cel mult 128 de caractere, altfel 422 cu error: invalid_idempotency_key). Aceeași cheie cu același conținut întoarce avizul deja creat, cu 200 și antetul Idempotent-Replayed: true, fără un al doilea aviz. Aceeași cheie cu conținut diferit este 409 cu { "error": "idempotency_conflict" }. Cheile sunt separate pe cheie API. Fără cheie, o cerere repetată cu aceeași referință este refuzată de regula duplicate_reference. Vezi și erori.

Citire și listare

curl "https://tenant.notsowms.ro/api/v1/asns?status=announced" \
  -H "Authorization: Bearer tenant.7c4a8d09ca3762af61e59520943dc26494f8941b"

curl https://tenant.notsowms.ro/api/v1/asns/42 \
  -H "Authorization: Bearer tenant.7c4a8d09ca3762af61e59520943dc26494f8941b"

Un aviz al altui client răspunde 404, la fel ca unul inexistent.

Anulare

POST /api/v1/asns/{id}/cancel anulează un aviz cu status: announced. Dacă depozitul a început recepția, cererea este refuzată cu 422 și code: not_cancellable; marfa deja primită nu se anulează. Răspunsul 200 este avizul cu status: cancelled.

curl -X POST https://tenant.notsowms.ro/api/v1/asns/42/cancel \
  -H "Authorization: Bearer tenant.7c4a8d09ca3762af61e59520943dc26494f8941b"

Confirmarea recepției prin webhook

Când depozitul finalizează o recepție, clientul poate primi evenimentul receiving.completed, care numește avizul (asn_id, asn_reference) și, pe fiecare linie, cantitățile accepted_quantity și damaged_quantity. Vezi Webhook-uri către clienții 3PL.