API och webhooks
Publicerat av Resly AB
Skapa försändelser och hämta filer via API
Bygg en koppling från underlag till signering och hämta rätt förseglade fil när ärendet är klart.
REST API v2
REST API v2 använder basen /v2 och en API-nyckel i HTTP-huvudet x-resly-api-key. API-dokumentationen beskriver tillgängliga operationer och vilka uppgifter de tar emot.
Nyckeln är kopplad till en användare och organisation. Anrop kontrolleras mot medlemskap och operationens behörighetsregler. Använd dokumentationen för den aktuella REST-operationen när du bygger kopplingen.
Mer om rest api v2
Använd dokumentationen för den REST-operation du vill utföra för att se tillåtna fält och åtgärder. API-basen är /v2 och autentiseringen använder en API-nyckel med 64 tecken. Nyckeln kopplas till en användare och organisation, och anropet kontrolleras mot medlemskap samt åtgärdens behörighetsregler. Att en funktion finns i GraphQL innebär inte att samma operation finns i REST.
Äldre REST API v1
Det äldre REST API v1 har en egen dokumentation och använder begrepp och dataformat som skiljer sig från v2, till exempel signees. Autentisering sker med x-resly-api-key.
Följ v1-dokumentationen för den operation kopplingen använder. Vid det samlade anropet kan aktiv archiveData skapa en avtalspost före dryrun-kontrollen. Använd därför inte den kombinationen som ett test utan bestående ändringar.
Mer om äldre rest api v1
V1 använder en separat OpenAPI-fil, operationsuppsättning och konverterare. Exempelvis omvandlas signees till participants med en lista över signeringsmetoder, och archiveData kan skapa en avtalspost som kopplas till försändelsen. Svar och statusvärden konverteras tillbaka till v1. Även här används x-resly-api-key. Att koden fortfarande monterar gränssnittet är inte ett besked om framtida avvecklingsdatum eller full kompatibilitet med alla v2-funktioner. Vid det samlade v1-anropet kan aktiv archiveData skapa avtalsposten innan försändelsens dryrun-kontroll. Använd därför inte dryrun med aktiv archiveData som ett prov utan bestående ändringar.
Skapa och publicera försändelse via API
POST /v2/envelopes/create-and-publish tar emot envelope, signers, files och valfria options. Filer anges med filename och base64-innehåll i fileData. Med options.skipPublish sparas ett utkast; annars försöker anropet publicera ärendet.
Queryparametern dryrun=true genomför inledande kontroller utan att skapa försändelsen, men provar inte hela lagrings- och utskicksprocessen. Vid fel efter skapandet försöker tjänsten rensa det påbörjade ärendet. Kontrollera resultat och befintliga ärenden före omförsök.
Mer om skapa och publicera försändelse via api
Tjänsten samlar fält-, deltagar- och filfel innan skapandet. API-filer avkodas från base64 och filtyp läses från innehållet. Queryvärdet dryrun måste vara strängen true; då returneras ett tomt objekt efter de första kontrollerna utan att försändelsen skapas. Det är inte ett fullständigt prov av lagring, PDF-konvertering, publiceringsrätt eller utskick. options.skipValidation hoppar över den samlade första felspärren men inte automatiskt senare kontroller i skapande, deltagarhantering och uppladdning. Efter skapande läggs deltagare och filer till i följd, därefter körs publiceringskontrollen om options.skipPublish inte valts. Vid fel efter att ett ärende skapats försöker tjänsten radera det; städningsfel loggas. Det är ingen garanti att alla externa effekter återställs.
Hämta fillänk
Använd GET /v2/content/{objectType}/{objectId}/{fileId} med envelopes för försändelser eller deals för avtal. Anropet kontrollerar åtkomsten och returnerar filuppgifter och en tillfällig URL. Hämta därefter filen från länken.
I ordinarie lagring gäller länken i tio minuter. Begär en ny om tiden gått ut. Välj rätt fil-id för original, Wordunderlag eller förseglat resultat och kontrollera att själva nedladdningen lyckas. Demon använder en exempel-PDF.
Mer om hämta fillänk
För API-hämtning använder du filens id tillsammans med försändelsens eller avtalets id. REST-anropet GET /v2/content/{objectType}/{objectId}/{fileId} använder envelopes för försändelser och deals för avtal. Åtkomsten kontrolleras innan länken skapas. Svaret innehåller filuppgifter och en tillfällig URL; hämta därefter själva filen från den länken. I ordinarie lagring gäller länken i tio minuter. Om den har gått ut behöver du begära en ny. Välj rätt fil-id för original, Word-underlag eller förseglat resultat. Ett lyckat länksvar bekräftar inte att filen finns tillgänglig i lagringen eller att filöverföringen har slutförts. Kontrollera även resultatet av själva nedladdningen. I demot används simulerad lagring och en exempel-PDF.
Uppdateringar i realtid
Arbetsytan kan ta emot uppdateringar när ett ärende ändras, så att aktuell information kan visas medan sidan är öppen. Uppdateringarna följer användarens åtkomst.
Efter ett avbrott eller om statusen verkar inaktuell kan du behöva öppna eller läsa in ärendet på nytt. Webhooks är ett separat sätt att skicka händelser till ett annat system.
Mer om uppdateringar i realtid
WebSocket-ytan är /sub-graphql och använder autentisering vid anslutning samt kontextkontroller för operationerna. Prenumerationen envelopeChanged kontrollerar försändelseåtkomst vid start och filtrerar publicerade händelser på organisation och försändelse-id. Utgivning sker via systemets pubsub. Detta är inte en varaktig leveranskö eller ett löfte om att en frånkopplad klient får alla missade ändringar; läs aktuellt objekt igen när tillståndet behöver bekräftas.