Guide

Sette i produksjon

Ti vaner som skiller en solid integrasjon fra en supportsak. Hvert punkt peker på siden som svarer på det, så et hull du finner her, har et sted å gå — og siste seksjon er hva du sender oss når noe fortsatt ikke stemmer.

Veien fra første samtale til produksjon er fire trekk: snakk med oss, få legitimasjonen din, gjør ditt første kall, sett i produksjon. Denne siden er det fjerde. Når du kommer hit, virker mekanikken allerede — legitimasjonen finnes, tokenet lages, kallene kommer tilbake med virkelige poster — og det som står igjen, er den operasjonelle formen på integrasjonen: hvor hemmeligheten bor, hvor lite et token har lov til å gjøre, hva som skjer når et kall feiler klokka tre om natta, og hva du gjør den dagen hemmeligheten må byttes.

Ingenting av det er et skjema som skal sendes inn eller en sertifisering som skal bestås. Gå gjennom listen, og følg lenken der et punkt ennå ikke er avklart.

De ti punktene

1. Hemmeligheter ligger i en secret manager. clientSecret dukker aldri opp i versjonskontroll, i en konfigfil som ligger i git, i en logglinje, i en sak eller i en chattemelding. Den vises nøyaktig én gang, i svaret som oppretter legitimasjonen, og Visena lagrer bare en enveis hash — den kan aldri vises igjen. Legitimasjon og tokener dekker hvor den kommer fra, og hva du gjør når den er tapt.
2. Én legitimasjon per system og miljø. Egne par for staging og produksjon, hvert navngitt etter systemet som holder det — erp-sync-prod, ikke api — slik at det å tilbakekalle ett aldri tar ned et annet. Legitimasjon og tokener.
3. Tokener mellomlagres og gjenbrukes. Lag ett token, hold det til omtrent 60 sekunder før expires_in, og lag så et nytt. Aldri én tokenforespørsel per API-kall. Den minimale mellomlagringen står i Legitimasjon og tokener.
4. Scopes er minimale. En jobb som bare leser, kjører på scope=read. Lekker det tokenet, er skadeomfanget nøyaktig det du ba om, og et skrivekall gjort med det kommer tilbake som 403. Skrivebeskyttet tilgang viser avvisningen i praksis.
5. Id-er lagres ordrett. Maskerte id-er som xK9mQ2 er ugjennomsiktige strenger: lagre nøyaktig det du fikk, tolk aldri en for mening, lag aldri en selv. Begreper.
6. Skriving foretrekker PATCH. Send bare feltene du eier, med Content-Type: application/merge-patch+json. En full PUT satt sammen av en delvis kopi av posten blanker stille ut alt du utelot. Å gjøre kall setter de to ved siden av hverandre.
7. Oppretting sjekker for duplikater først. Person- og firmasynker kaller duplikatsjekken før de oppretter, og håndterer 409 på firmaer: et organisasjonsnummer som allerede finnes, betyr at posten er der, og at skrivingen er en oppdatering. Sjekkene er dokumentert på Company og Person.
8. Synker bruker cursor og tidslinjer. Én full eksport gjennom /cursor, og deretter /timeline — eller /document/changes for dokumenter — mot et vannmerke du lagrer. Ingenting lister hele datasettet på nytt etter en tidsplan. Lister, paginering og synk forklarer hvilken modus hver jobb vil ha.
9. Nye forsøk er disiplinerte. Eksponentiell backoff med jitter på nettverksfeil og 5xx, én ny tokenutstedelse på 401, og aldri et blindt nytt forsøk på 400, 403, 409, 415 eller 422 — samme forespørsel gir samme svar. Regelen står i Feil og feilsøking.
10. Rotering er innøvd. Du har kjørt opprett ny → rull ut → tilbakekall gammel minst én gang, i ro, før dagen du må gjøre det under press. Begge legitimasjonene virker under byttet, så det finnes ikke noe nedetidsvindu å forhandle om. Legitimasjon og tokener har de tre trekkene.

Når du trenger oss

Ta kontakt på sales@visena.com, eller gjennom kontaktpersonen din i Visena — den navngitte kontakten du har fra den første samtalen om integrasjonen. Send de fire tingene nedenfor, så finner vi forespørselen hos oss i stedet for å be deg reprodusere den.

Før du skriver: sjekk symptomet mot tabellen for rask diagnose i Feil og feilsøking — alle forespørsler svarer plutselig 401, lesing virker mens skriving svarer 403, en tokenforespørsel avvises med invalid_scope. De har kjente årsaker og trenger ingen sak.

Hvor du går videre

Dette er den siste guidesiden i seksjonen. Herfra er dokumentasjonen referanse: ni ressurser, én side hver, med hver parameter, hver responsform og hver statuskode. Hver sti i den er bygget likt — /{instanceName}/api/v1/{locale}/person, i entall, uten partner/-segment.

Les denne siden uken før du setter i produksjon, ikke uken etter. De fleste av de ti punktene er billige å rette mens integrasjonen fortsatt peker mot staging, og dyre når en produksjonsjobb først avhenger av dem.