POSTOpret et produkt fra appen

Formål og præcis afgrænsning

Operationen opretter en vare eller ydelse i produktkartoteket med de felter, som partnerkontrakten udtrykkeligt accepterer. Den er beregnet til en integrationskilde, der kan identificere sit produkt med en stabil code og angive navn, art, enhed og eventuel ørepris.

Det er en create-operation, ikke et skjult upsert. Findes koden allerede i den relevante unikhedskontekst, returneres en konflikt (resource_conflict) frem for den eksisterende fulde produktrække. Skriveret giver dermed ikke et indirekte produktregisteropslag. En minimal succesfuld kvittering indeholder kun det oprettede produkts id, created og operationsmetadata.

Før kaldet

Vælg den eksplicit konfigurerede installation. HOURS_BASE er enten dens /api/partner/sandbox/v1 eller /api/partner/v1. Basisadressen vises i App Console for appen. Et sandboxtoken begynder med hsk_; et produktions-access-token begynder med hat_. De er ikke indbyrdes udskiftelige og er ikke Supabase-login-tokens.

Produktion kræver en godkendt apprevision, en kundegrant og de relevante scopes. Kundegrantet er givet af organisationsejeren med tofaktor (aal2), gælder de valgte konti og varer højst 90 dage. Endelig journalbogføring kræver et særskilt mandat. Sandbox kræver en klargjort appgeneration i et separat projekt. En gyldig tokenform alene er ikke adgang.

Input og grænser

Ukendte felter afvises. Hele body er højst 256 KiB, datoer skal være gyldige kalenderdatoer, og beløb er heltal i hele øre, højst 99 999 999 999 999 pr. linje. Valgfrie null-værdier og defaults normaliseres af serverens inputmodel. Organisation, aktør, intern kilde og bankkobling bestemmes ikke af payloaden.

Eksempel

Gem følgende syntetiske input som input.json.

{
  "code": "CONSULT-001",
  "name": "Rådgivning",
  "kind": "services",
  "unit": "time",
  "unit_price_minor": 80000
}

curl --silent --show-error --fail-with-body \
  --request POST "$HOURS_BASE/products" \
  --header "Authorization: Bearer $HOURS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @input.json

Succes og output

Forvent HTTP 201 ved succes:

{
  "id": "00000000-0000-4000-8000-000000000200",
  "created": true,
  "operation_id": "00000000-0000-4000-8000-000000000900",
  "replayed": false,
  "environment": "sandbox"
}

Et identisk replay giver samme successtatus og sætter replayed til true. Replay-svaret udelader environment, så klienten må ikke kræve feltet på replay. Produktions- og sandboxkontekst skal allerede være kendt fra kaldet, ikke udledes af en eventuelt manglende kvitteringsetiket.

Fejl og genforsøg

Manglende eller forkert miljøtoken afvises. Manglende scope, tilbagekaldt grant eller ændret apprevision stopper kaldet. Reference- og domænefejl skal afklares i stedet for at blive omskrevet til tilfældige gyldige værdier.

Ved timeout med ukendt udfald genbruges samme idempotensnøgle og samme input. En ændret payload under samme nøgle giver konflikt. En ny grant kan også give idempotency_grant_changed. Input, der afvises før regnskabskernen (invalid_input og invalid_amount), gemmer ingen kvittering, så samme nøgle kan genbruges med rettet input. Klientens forretningslog skal derfor gemme den oprindelige kontekst.

Varenummer, enhed og pris

Behandl code som en stabil forretningsreference. Undlad tidsstempler og tilfældige suffixer som løsning på en konflikt, medmindre der faktisk er tale om et nyt produkt. To skriveforsøg efter et netværksbrud skal bruge samme kode og samme idempotensnøgle.

kind skelner mellem goods og services. Enheden skal vælges fra det publicerede skemas tilladte værdier; gatewayen åbner ikke et frit felt for enhver lokal enhedsbetegnelse. unit_price_minor: null er ikke det samme som en pris på nul: den første angiver ingen værdi, mens den anden er en eksplicit gratis pris i øre.

Partner-API'et tilbyder ikke efterfølgende produktredigering eller arkivering. Byg derfor ikke et fuldt tovejs-synkroniseringsflow på dette create-kald alene. Produktkoder, som allerede optræder på bogførte dokumenter, gør en fremtidig ændringskontrakt særlig følsom.

Test din integration

Test korrekt kontekst, manglende scope, forkert miljø og fremmede referencer. Test også to samtidige identiske requests, ændret payload med samme nøgle og tabt svar efter commit. Kontrollér, at der kun er oprettet ét produkt; et 201-svar fra en simuleret server er ikke bevis herpå.

Se rettigheder, fejl og idempotens.