Meniu
Securizat & de încredere Datele tale sunt în siguranță
Suport dedicat 24/7 Suntem mereu aici pentru tine
Partener de încredere Soluții pentru business-ul tău

VOGO eBS · WS

Serviciile web VOGO eBS

Sistemele externe lucrează cu documentele, CRM-ul, registratura și portalul VOGO eBS prin REST și SOAP, cu aceleași drepturi și reguli ca ecranele aplicației.

Un client de integrare, un token OAuth 2.0, toate serviciile. Numai HTTPS.

  • REST și SOAP
  • OAuth 2.0, token de 15 minute
  • Aceleași drepturi ca pe ecran

Autentificare (login)

OAuth 2.0, client credentials. Clientul cere un token cu cheia și secretul lui și îl trimite la fiecare apel, în antetul Authorization: Bearer. Un token expirat, revocat sau al unui client oprit primește 401 invalid_token.

1. Clientul de integrare

Administratorul organizației îl creează în VOGO eBS, la Setări → IAM → „Clienți de integrare”: numele, utilizatorul de sistem, permisiunile, IP-urile permise. Secretul se arată o singură dată.

2. Tokenul

Cererea tokenului, cu cheia și secretul; răspunsul e tokenul, valabil 15 minute. Opțional, scope: mai puține permisiuni decât are clientul.

POST https://vogo.me/app/ws/token/
grant_type=client_credentials
&client_id=<cheia>&client_secret=<secretul>

3. Apelul

Acțiunea și parametrii, în corpul cererii, cu tokenul în antet.

POST https://vogo.me/app/ws/rest/v1/
Authorization: Bearer <token>
{"action": "folder.list", "params": {}}

Login pentru oameni, prin aplicație

O aplicație înregistrată de organizație (aplicația de telefon, un portal partener) loghează un om la https://vogo.me/app/ws/login/, cu aceeași logare ca pagina VOGO eBS: parola și al doilea factor, obligatoriu. Tokenul primit lucrează cu drepturile omului, în limita permisiunilor aplicației; schimbarea parolei sau închiderea sesiunilor îl oprește pe loc.

AcțiuneCe face
login.start Cheia aplicației, codul organizației, numele sau e-mailul și parola: un tichet de 10 minute și metoda celui de-al doilea factor; la codul pe e-mail, codul pleacă acum.
login.resend_code Codul pe e-mail, trimis din nou (cel mult o dată pe minut).
login.verify Tichetul și codul din 6 cifre (Google Authenticator sau e-mail): tokenul omului, de 15 minute, și tokenul de reînnoire.
login.refresh O pereche nouă de tokenuri; cel vechi nu mai merge, iar folosit din nou închide sesiunea.
login.me Omul autentificat: numele, contul, organizația, rolul, al doilea factor.
login.logout Ieșirea: sesiunea se închide și tokenurile ei se opresc.

Adresele

CeAdresaMetoda
Token https://vogo.me/app/ws/token/ POST, application/x-www-form-urlencoded
Login pentru oameni https://vogo.me/app/ws/login/ POST, application/json
REST https://vogo.me/app/ws/rest/v1/ POST, application/json; încărcările: multipart/form-data
SOAP https://vogo.me/app/ws/soap/ POST, text/xml (SOAP 1.1)
Descrierea SOAP (WSDL) https://vogo.me/app/ws/soap/?wsdl GET

Cine apelează

Sistemul extern

Cu tokenul clientului de integrare, în antetul Authorization: Bearer. Lucrează cu drepturile utilizatorului de sistem al clientului; 120 de cereri pe minut.

Ecranele aplicației

Ecranele VOGO eBS cheamă același serviciu, cu sesiunea omului logat și drepturile lui, de pe același site; 600 de cereri pe minut pe om. Azi: ecranele CRM.

Omul, prin aplicație

Un om al organizației, logat de o aplicație înregistrată cu parola și al doilea factor: drepturile lui, în limita permisiunilor aplicației.

Vizitatorul și clientul portalului

Citirile publice ale catalogului și cererile clientului cu contul lui din portal (capitolul Portal, în pregătire).

Administrarea clienților, în VOGO eBS

Numai administratorul ECM al organizației, în ecranul „Clienți de integrare” (Setări → IAM), https://vogo.me/app/ws/clients/.

Client nou

Numele, utilizatorul de sistem, permisiunile și, opțional, IP-urile permise. Cheia și secretul se arată o singură dată.

Secret nou

Un secret nou pentru client; cel vechi se oprește imediat, împreună cu tokenurile lui.

Oprire

Clientul oprit nu mai primește token, iar tokenurile lui se revocă pe loc.

Jurnalul apelurilor

Apelurile clientului: acțiunea, elementul, rezultatul, IP-ul, durata.

Ce au în comun toate serviciile

Cereri repetate fără dubluri

Operațiile care creează primesc o cheie de idempotență: aceeași cerere, repetată în 24 de ore, primește răspunsul primei, fără un element nou.

Numai POST, nimic în adresă

Acțiunea și parametrii stau în corpul cererii, ca în ecranele aplicației; excepția e descrierea SOAP (?wsdl).

Identificatori stabili

Elementele ECM se identifică prin uuid; listele lungi vin pe pagini, cu un cursor.

Token cu mai puține permisiuni

La cererea tokenului se pot cere mai puține permisiuni decât are clientul; niciodată mai multe.

Organizația, din token

Organizația și drepturile se iau din token sau din sesiune, nu din ce spune cererea; o organizație nu vede nimic din alta.

REST și SOAP, aceleași operații

Aceleași reguli și aceleași coduri de eroare; în SOAP, un refuz e un soap:Fault cu codul și referința.

Codurile de eroare

CodHTTPCând
invalid_request 400 Parametru lipsă sau greșit, acțiune necunoscută.
invalid_client 401 Cheie sau secret greșit (numai la token).
invalid_token 401 Token lipsă, expirat, revocat sau al unui client oprit.
insufficient_scope 403 Operația cere o permisiune pe care tokenul nu o are.
forbidden 403 Dreptul există, dar regula operației refuză.
not_found 404 Elementul nu există sau nu poate fi văzut — același răspuns pentru amândouă.
conflict 409 Numele există deja la destinație.
too_large 413 Fișier peste limită.
rate_limited 429 Prea multe cereri; antetul Retry-After dă secundele.
server_error 500 Eroare internă: mesaj generic, detaliul în jurnal sub referința din răspuns.

Securitatea

Secretul, arătat o dată

Se păstrează doar ca amprentă (Argon2id). Se poate genera altul; cel vechi se oprește imediat.

Tokenul, 15 minute

Aleator, păstrat doar ca amprentă. Oprirea clientului îi revocă toate tokenurile.

Blocarea încercărilor

5 secrete greșite în 15 minute blochează adresa IP; 50 într-o oră blochează clientul.

Limite

120 de cereri pe minut pe client, 10 cereri de token pe minut pe adresă IP; opțional, lista IP-urilor permise.

Drepturile unui om

Clientul lucrează cu drepturile utilizatorului de sistem ales, nici mai mult, nici mai puțin.

Jurnal și audit

Fiecare apel are un rând: clientul, acțiunea, elementul, rezultatul, IP-ul, durata; operațiile care schimbă ceva intră și în auditul aplicației.

Pentru servere, nu pentru browsere

Fără CORS; răspunsurile au Cache-Control: no-store și X-Content-Type-Options: nosniff.

XML sigur

SOAP refuză DOCTYPE și entitățile XML (XXE), iar cererea are o mărime maximă.

Fișierele verificate

Tipul real al fișierului se citește din conținut, nu din nume; numele e curățat de căi.

ECM — foldere și documente

Disponibil: REST și SOAP

Sistemul extern lucrează cu folderele și documentele organizației exact ca ecranul Documente: aceleași drepturi pe fiecare element, aceleași reguli, același audit. Identificatorii sunt uuid-urile elementelor. În SOAP, fișierele circulă în base64, până la 20 MB; cele mai mari se încarcă și se descarcă prin REST.

  • ws.read — citire și descărcare
  • ws.write — creare, redenumire, mutare, copiere, încărcare
  • ws.delete — ștergere

Foldere

Acțiune (REST) Operație SOAP Permisiune Ce face
folder.list FolderList ws.read Subfolderele unui folder sau, fără părinte, primul nivel.
folder.get FolderGet ws.read Un folder, cu drepturile apelantului pe el.
folder.rights FolderRights ws.read Ce poate face apelantul pe folder: vizualizare, descărcare, scriere, ștergere, administrare.
folder.create FolderCreate ws.write Folder nou într-un folder părinte.
folder.rename FolderRename ws.write Redenumirea unui folder.
folder.move FolderMove ws.write Mutarea unui folder în alt folder.
folder.copy FolderCopy ws.write Copierea unui folder, cu conținutul lui; numele ocupat devine „X - copie”.
folder.delete FolderDelete ws.delete Ștergerea unui folder gol.

Documente

Acțiune (REST) Operație SOAP Permisiune Ce face
document.list DocumentList ws.read Documentele unui folder, pe pagini.
document.get DocumentGet ws.read Datele unui document: titlu, tip, versiune, fișier, mărime, folder.
document.types DocumentTypes ws.read Tipurile de document pe care le acceptă un folder.
document.upload DocumentUpload ws.write Încărcarea unui document nou; tipul real al fișierului se citește din conținut.
document.download DocumentDownload ws.read Fișierul documentului (REST: fișierul; SOAP: base64).
document.rename DocumentRename ws.write Redenumirea unui document.
document.move DocumentMove ws.write Mutarea unui document în alt folder.
document.copy DocumentCopy ws.write Copierea unui document în alt folder.
document.delete DocumentDelete ws.delete Ștergerea unui document nou, neînregistrat, fără flux.

CRM — contacte, campanii și evenimente

Disponibil: REST · SOAP în pregătire

Ecranele CRM ale aplicației folosesc chiar acest serviciu: ce merge pe ecran merge și din afară, la fel, cu aceleași validări, drepturi și jurnal. Identificatorii sunt numerele CRM ale organizației.

  • crm.read — citiri
  • crm.write — creare și modificare
  • crm.delete — ștergeri
  • crm.send — pornirea, oprirea și reluarea campaniilor, mailul de test
  • crm.admin — setările de trimitere

Contacte

Acțiune (REST) Permisiune Ce face
contact.list crm.read Contactele unei campanii sau toate, cel mult 3.000.
contact.get crm.read Un contact, cu firma, etichetele, corespondența și campaniile.
contact.save crm.write Contact nou sau modificat.
contact.delete crm.delete Ștergerea unui contact.
contact.labels_set crm.write Etichetele unui contact.

Corespondența unui contact

Acțiune (REST) Permisiune Ce face
mail.get crm.read Un mail: sens, de la, către, subiect, data, textul.
mail.download crm.read Fișierul .msg al mailului.
mail.add crm.write Un mail adăugat în corespondența contactului.
mail.delete crm.delete Ștergerea unui mail din corespondență.

Etichete

Acțiune (REST) Permisiune Ce face
label.list crm.read Etichetele, cu numărul de contacte.
label.save crm.write Etichetă nouă sau modificată.
label.delete crm.delete Ștergerea unei etichete.
label.bulk crm.write O etichetă pusă sau scoasă pe mai multe contacte.

Campanii și destinatari

Acțiune (REST) Permisiune Ce face
campaign.list crm.read Campaniile, cu cifrele lor și ale valurilor.
campaign.pickable crm.read Campaniile în care se pot adăuga contacte.
campaign.preview crm.read Câte contacte selectează un filtru, cu primele rânduri.
campaign.create crm.write Campanie nouă, din contactele alese.
campaign.create_from_filter crm.write Campanie nouă, dintr-un filtru.
campaign.add_contacts crm.write Contacte adăugate într-o campanie.
campaign.add_address crm.write O adresă adăugată de mână într-o campanie.
campaign.remove_contact crm.write Un contact scos dintr-o campanie.
campaign.rename crm.write Redenumirea unei campanii.
campaign.delete crm.delete Ștergerea unei campanii.
campaign.recipients crm.read Destinatarii cu starea lor sau valurile campaniei.
campaign.recipient_message crm.read Mailul exact primit de un destinatar.
campaign.wave_add crm.write Un val nou de destinatari.
campaign.wave_marks crm.write Marcajele destinatarilor unui val.

Trimiterea

Acțiune (REST) Permisiune Ce face
campaign.start crm.send Pornirea unei campanii.
campaign.stop crm.send Oprirea unei campanii.
campaign.resume crm.send Reluarea unei campanii oprite.
campaign.process crm.send Trimiterea lotului următor al unei campanii pornite.
template.send_test crm.send Mailul de test al unui șablon.

Șabloane și câmpuri calculate

Acțiune (REST) Permisiune Ce face
template.list crm.read Șabloanele.
template.get crm.read Un șablon, cu variantele și atașamentele lui.
template.save crm.write Șablon nou sau modificat.
template.rename crm.write Redenumirea unui șablon.
template.clone crm.write Copia unui șablon.
template.delete crm.delete Ștergerea unui șablon.
template.subject_variants crm.write Variante propuse pentru subiect.
template.preview crm.read Mailul unui șablon, pentru un contact anume.
attachment.add crm.write Un atașament adăugat la un șablon.
attachment.delete crm.delete Ștergerea unui atașament.
field.list crm.read Câmpurile calculate, operatorii și sursele.
field.save crm.write Câmp calculat nou sau modificat.
field.delete crm.delete Ștergerea unui câmp calculat.

Import de contacte

Acțiune (REST) Permisiune Ce face
import.file crm.write Import dintr-un fișier .xlsx.
import.paste crm.write Import din text lipit.
import.manual crm.write Import din adrese scrise de mână.
import.template crm.read Fișierul-model .xlsx.
import.list crm.read Importurile făcute.
import.log crm.read Jurnalul unui import.

Evenimente

Acțiune (REST) Permisiune Ce face
event.list crm.read Evenimentele, cu numărul de înscriși.
event.get crm.read Un eveniment.
event.save crm.write Eveniment nou sau modificat.
event.delete crm.delete Ștergerea unui eveniment.
event.participants crm.read Înscrișii unui eveniment, cu starea lor.
participant.status crm.write Starea unui înscris.

Setările de trimitere

Acțiune (REST) Permisiune Ce face
settings.get crm.admin Setările de trimitere; secretele apar numai ca „salvat / nesalvat”.
settings.save crm.admin Setările de trimitere modificate.
settings.import_legacy crm.admin Preluarea setărilor vechi.
settings.new_token crm.admin Un token nou al serviciului de trimitere, arătat o singură dată.

Registratură — registre și înregistrări

Contract publicat · serviciul în pregătire

Numărul de înregistrare îl dă numai motorul registraturii, în tranzacție, cu auditul lui: o cerere invalidă nu consumă număr. Drepturile sunt ale registrului, ca pe ecran: cine vede, cine înregistrează, cine anulează.

  • registry.read — citiri
  • registry.write — înregistrare, editare, documente, e-mailurile primite
  • registry.cancel — anularea unei înregistrări
  • registry.send — trimiterea unui e-mail din corespondență
  • registry.admin — definirea registrelor

Registrele în care se lucrează

Acțiune (REST) Permisiune Ce face
registry.list registry.read Registrele în care apelantul are drepturi, cu drepturile lui.
registry.next_number registry.read Numărul următor al unui registru, fără să-l consume.

Înregistrări

Acțiune (REST) Permisiune Ce face
registration.list registry.read Înregistrările unui registru, cu filtre și pe pagini.
registration.search registry.read Căutare după număr sau conținut.
registration.get registry.read Datele unei înregistrări.
registration.register registry.write O înregistrare nouă: numărul și data.
registration.update registry.write Editarea unei înregistrări; numărul nu se schimbă.
registration.cancel registry.cancel Anularea unei înregistrări; numărul rămâne ocupat.

Documentele unei înregistrări

Acțiune (REST) Permisiune Ce face
registration.documents registry.read Documentele înregistrării, cu cel principal marcat.
registration.attach registry.write Documentul principal sau o versiune nouă a lui.
registration.add_documents registry.write Documente adăugate la înregistrare.
registration.link_documents registry.write Documente din ECM legate de înregistrare.
registration.set_main registry.write Un document devine principal.
registration.remove_document registry.write Un document scos din înregistrare; rămâne în ECM.
registration.file registry.read Fișierul unui document al înregistrării.
registration.eml registry.read Mesajul original al unei înregistrări venite pe e-mail.

Accesul la o înregistrare

Acțiune (REST) Permisiune Ce face
registration.acl_get registry.read Cine are acces la înregistrare și cu ce drepturi.
registration.acl_save registry.write Accesul la înregistrare, modificat.

Corespondența unei înregistrări

Acțiune (REST) Permisiune Ce face
registration.mail_thread registry.read Mailurile primite și trimise ale înregistrării.
registration.mail_send registry.send Un mail trimis, legat de înregistrare.

Terți și tipuri de document

Acțiune (REST) Permisiune Ce face
party.search registry.read Căutarea unui terț: nume, cod fiscal, cod.
doctype.add registry.write Un tip de document nou.
efactura.read registry.read O factură din SPV citită, gata de înregistrat.

E-mailurile primite

Acțiune (REST) Permisiune Ce face
inbox.list registry.read E-mailurile din adresele urmărite.
inbox.fetch registry.write Citirea acum a adreselor urmărite.
inbox.register registry.write Număr de înregistrare pentru un e-mail primit, cu răspunsul automat.
inbox.reply registry.send Răspunsul automat, trimis din nou.

Definirea registrelor

Acțiune (REST) Permisiune Ce face
registry.def_list registry.admin Registrele organizației, cu definiția lor.
registry.create registry.admin Registru nou.
registry.clone registry.admin Copia unui registru.
registry.update registry.admin Definiția modificată; contorul nu se atinge.
registry.delete registry.admin Ștergerea unui registru în care nu s-a înregistrat nimic.
registry.default_config registry.admin Configurația implicită a coloanelor.
registry.accept_add registry.admin Ce acceptă registrul: o clasă sau un tip de document.
registry.accept_remove registry.admin Scoaterea unui element acceptat.
registry.accept_direction registry.admin Sensul unui element acceptat: intrare, ieșire.
registry.accept_default_type registry.admin Tipul de document implicit.
registry.grant_save registry.admin Drepturile unui rol în registru.
registry.grant_remove registry.admin Scoaterea drepturilor unui rol.

Portal — catalogul de servicii și cererile clienților

Contract publicat · serviciul în pregătire

Pagina publică a portalului, cererea clientului și administrarea catalogului. Cererea depusă primește numărul din registratură; o cerere trimisă de două ori primește același număr, niciodată un al doilea. Apelanții: vizitatorul (citirile publice și, unde instituția permite, depunerea fără cont), clientul cu contul lui din portal, ecranul de administrare și sistemul extern cu token.

  • portal.read — catalogul și cererile depuse ale organizației
  • portal.submit — depunerea unei cereri în numele unui solicitant fără cont
  • portal.admin — catalogul de servicii și regulile de afișare a câmpurilor

Catalogul public

Acțiune (REST) Permisiune Ce face
catalog.list portal.read Serviciile publicate ale portalului, cu termenul, costul și categoria.
catalog.service portal.read Un serviciu: descrierea, termenul, costul, documentele cerute, formularul.
catalog.template portal.read Șablonul oficial al unui serviciu, de descărcat.
portal.settings portal.read Aspectul portalului: stema, titlul, tema.

Cererea clientului

Acțiune (REST) Permisiune Ce face
request.preview portal.submit Cererea verificată, cum va fi înregistrată; nu se salvează nimic.
request.draft_pdf portal.submit Cererea completată, ca PDF, fără număr.
request.submit portal.submit Depunerea cererii, cu documentele: numărul de înregistrare și recipisa pe e-mail.
request.list portal.read Cererile: ale clientului sau ale organizației, cu stadiul lor.
request.get portal.read O cerere, cu câmpurile, documentele și stadiul.
account.get contul clientului Datele contului clientului din portal.

Catalogul de servicii (administrare)

Acțiune (REST) Permisiune Ce face
service.list portal.admin Toate serviciile, cu categoria lor.
service.get portal.admin Un serviciu, cu documentele cerute și șablonul.
service.template portal.admin Șablonul unui tip de document.
service.save portal.admin Serviciu nou sau modificat.

Regulile de afișare a câmpurilor

Acțiune (REST) Permisiune Ce face
rule.list portal.admin Regulile, cu formularele și câmpurile lor.
rule.save portal.admin Regulă nouă sau modificată.
rule.delete portal.admin Ștergerea unei reguli.
rule.export_dmn portal.admin Regulile, ca tabel de decizie DMN 1.3.
rule.import_dmn portal.admin Regulile dintr-un tabel DMN, într-o singură tranzacție.

Întrebări frecvente

Ce îmi trebuie ca să încep?

Un client de integrare, creat de administratorul organizației în VOGO eBS (Setări → IAM → „Clienți de integrare”): primiți cheia și secretul, apoi cereți tokenul.

Același token merge la toate serviciile?

Da. Același token merge la toate serviciile, prin REST și prin SOAP, în limita permisiunilor clientului.

REST sau SOAP?

Aceleași operații, aceleași reguli. REST primește JSON prin POST; SOAP primește XML, după descrierea de la https://vogo.me/app/ws/soap/?wsdl.

Ce drepturi are clientul?

Ale utilizatorului de sistem ales la crearea clientului. Permisiunea (scope) spune ce poate încerca; drepturile acelui utilizator spun ce reușește.

Ce se întâmplă dacă repet o cerere de creare?

Cu aceeași cheie de idempotență, în 24 de ore, primiți răspunsul primei cereri, fără un element nou.

Integrare

Legați-vă sistemul de VOGO eBS

Spuneți-ne ce sistem conectați și ce date schimbă; vă răspundem cu pașii și cu contractul serviciilor.

WhatsApp ecm@vogodigital.ro