Skip to content

Commit 2e80b3e

Browse files
mijorusmijorus
committed
Merge 'readme.md' from 'fix-linting' into 'master'
1 parent 099541b commit 2e80b3e

1 file changed

Lines changed: 218 additions & 21 deletions

File tree

‎readme.md‎

Lines changed: 218 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,258 @@
11
# OpenAPI Library
22

3-
## Installation
3+
<!-- vscode-markdown-toc -->
4+
* 1. [Installation](#Installation)
5+
* 2. [Usage](#Usage)
6+
* 2.1. [Instanza della classe](#Instanzadellaclasse)
7+
* 2.2. [Esempi](#Esempi)
8+
* 3. [Modulo comuni](#Modulocomuni)
9+
* 3.1. [Esempi](#Esempi-1)
10+
* 4. [Modulo imprese](#Moduloimprese)
11+
* 4.1. [Utilizzo](#Utilizzo)
12+
* 4.2. [Esempi](#Esempi-1)
13+
* 5. [Modulo Marche Temporali](#ModuloMarcheTemporali)
14+
* 5.1. [Esempi](#Esempi-1)
15+
* 6. [Modulo SMS](#ModuloSMS)
16+
* 6.1. [Inviare un SMS](#InviareunSMS)
17+
* 7. [Modulo Visengine](#ModuloVisengine)
18+
19+
<!-- vscode-markdown-toc-config
20+
numbering=true
21+
autoSave=true
22+
/vscode-markdown-toc-config -->
23+
<!-- /vscode-markdown-toc -->
24+
25+
26+
## 1. <a name='Installation'></a>Installation
427

528
```sh
629
composer require altravia/openapi
730
```
831

9-
## Usage
32+
## 2. <a name='Usage'></a>Usage
1033

11-
### Instanza della classe
34+
### 2.1. <a name='Instanzadellaclasse'></a>Instanza della classe
1235

1336
```php
14-
$this->openapi = new \OpenApi\OpenApi($scopes,$user,$apikey,"test");
37+
require_once 'vendor/autoload.php';
38+
39+
$openapi = new \OpenApi\OpenApi($scopes, $user, $apikey, $environment);
1540
```
1641

1742
Dove `$scopes` è un array di stringhe o di oggetti in uno dei seguenti formati:
1843

1944
```php
20-
$scopes=[
45+
$scopes = [
2146
"GET:ws.ufficiopostale.com/comuni",
22-
["domain"=>"ws.ufficiopostale.com", "method"=>"comuni","mode"=>"GET"]
47+
[
48+
"domain"=>"ws.ufficiopostale.com",
49+
"method"=>"comuni",
50+
"mode" =>"GET"
51+
]
2352
];
2453
```
2554

2655
...e `$environment` è l'ambiente sceltro tra `'test'` (default) e `'production'`
2756

57+
OpenApi si occuperá di reperire automaticamente, o generare, un nuovo token quando necessario.
58+
59+
A questo punto, in base agli scopes indicati vengono creati i seguenti oggetti:
2860

29-
A questo punto, in base agli scopes indicati vengono creati i seguenti oggetto:
3061

3162
```php
32-
$this->openapi->ufficiopostale
33-
$this->openapi->imprese
34-
...
63+
// Ogni oggetto verrá creato solo se disponibile nello scope.
64+
$openapi->ufficiopostale;
65+
$openapi->comuni;
66+
$openapi->imprese;
67+
$openapi->visengine;
68+
$openapi->marcheTemporali;
69+
$openapi->geocoding;
70+
$openapi->SMS;
71+
$openapi->firmaDigitale;
72+
$openapi->pecMassiva;
3573
```
36-
3774
che possono essere usati al seguente modo:
3875

3976
```php
4077
$this->openapi->ufficioposale->getCitiesByCap('00132');
4178
```
79+
### 2.2. <a name='Esempi'></a>Esempi
80+
81+
```php
82+
require_once 'vendor/autoload.php';
83+
84+
// Dichiaro gli scopes necessari
85+
$scopes = [
86+
'GET:comuni.openapi.it/cap',
87+
'GET:imprese.altravia.com/advance',
88+
];
89+
90+
$openapi = new OpenApi\OpenApi($scopes, 'my_username','my_api_key', 'test');
91+
92+
// Comuni: prendi informazioni sul cap 00132
93+
$cap = $openapi->comuni->getCitiesByCap('00132');
94+
95+
// Imprese: prendi informazioni su una specifica impresa
96+
$impresa = $openapi->imprese->getByPartitaIva('12485671007');
97+
98+
// Ufficio Postale: ottieni informaizoni sul tracking
99+
$track = $this->openapi->ufficiopostale->track('123456789');
100+
```
101+
102+
103+
## 3. <a name='Modulocomuni'></a>Modulo comuni
104+
Consente di prendere informazioni su comuni e provincie.
105+
106+
* `getCitiesByCap`
107+
* `getComuneByCatasto`
108+
* `getRegioni`
109+
* `getProvince`
110+
* `getComuni`
111+
112+
### 3.1. <a name='Esempi-1'></a>Esempi
113+
114+
```php
115+
$provincia = 'RM';
116+
$comuni = $this->openapi->comuni->getComuni($provincia);
117+
118+
var_dump($comuni['comuni']);
119+
/*
120+
121+
["nome_provincia"]=>
122+
string(4) "Roma"
123+
["sigla_provincia"]=>
124+
string(2) "RM"
125+
["regione"]=>
126+
string(5) "Lazio"
127+
["comuni"]=>
128+
array(121) {
129+
[0]=>
130+
string(6) "Affile"
131+
...
132+
*/
133+
134+
135+
```
136+
137+
## 4. <a name='Moduloimprese'></a>Modulo imprese
138+
### 4.1. <a name='Utilizzo'></a>Utilizzo
139+
Il modulo imprese espone i seguenti metodi:
140+
* `getByPartitaIva`
141+
* `getClosed`
142+
* `getVatGroup`
143+
* `getPec`
144+
* `getBySearch`
145+
146+
Per `getBySearch` e `getByPartitaIva` è richiesto accesso allo scope `/advance`
147+
148+
### 4.2. <a name='Esempi-1'></a>Esempi
149+
Utilizziamo `getBySearch` per cercare un'azienda il cui nome inizia con `Altrav` a Roma
150+
151+
```php
152+
$autocomplete = $this->openapi->imprese->getBySearch('Altrav*', 'RM');
153+
154+
/*
155+
[0]=>
156+
object(stdClass)#41 (10) {
157+
["piva"]=>
158+
string(11) "12485671007"
159+
["cf"]=>
160+
string(11) "12485671007"
161+
["denominazione"]=>
162+
string(20) "ALTRAVIA SERVIZI SRL"
163+
[1]=>
164+
object(stdClass)#42 (10) {
165+
["id"]=>
166+
string(24) "4242424242"
167+
["denominazione"]=>
168+
string(18) "xxx Altravia Esempio 2"
169+
...
170+
*/
171+
```
172+
173+
## 5. <a name='ModuloMarcheTemporali'></a>Modulo Marche Temporali
174+
* `availability`
175+
* `checkLotto`
176+
* `purcahse`
177+
178+
### 5.1. <a name='Esempi-1'></a>Esempi
179+
180+
```php
181+
// Controlliamo la disponibilitá di una marca di inforcert o aruba
182+
$disponibilita = $this->openapi->marcheTemporali->availability('infocert', 1);
183+
184+
// Se le marche sono disponibili, acquistiamone una
185+
if ($disponibilita->availability > 0) {
186+
try {
187+
$marca = $this->openapi->marcheTemporali->purcahse('infocert', 1);
188+
} catch (\OpenApi\classes\exception\OpenApiMarcheTemporaliException $e) {
189+
error_log(var_dump($e));
190+
}
191+
}
192+
```
193+
194+
## 6. <a name='ModuloSMS'></a>Modulo SMS
195+
* `getRecipients`
196+
* `getMessage`
197+
* `sendMore`
198+
* `sendOne`
199+
200+
### 6.1. <a name='InviareunSMS'></a>Inviare un SMS
201+
Per inviare un SMS, per prima cosa definiamo i destinatari:
202+
203+
```php
204+
$recipient = '+39-3939989741';
205+
// OR
206+
$recipients = [
207+
[
208+
'number' => '+39-3939989741',
209+
'fields' => ['nome' => 'NomeDestinatario']
210+
]
211+
];
212+
```
42213

43-
# Modulo ufficio postale
214+
Possiamo ora procedere ad inviare un SMS:
215+
```php
44216

45-
# Modulo visure
217+
try {
218+
$priority = 1;
219+
$options = null;
220+
$singleSms = $this->openapi->SMS->sendOne('Nome del mittente', $recipient, 'lorem ipsum', null, $priority, $options);
221+
} catch (\OpenApi\classes\exception\OpenApiConnectionsException $e) {
222+
throw 'Non è stato possibile recapitare il messaggio';
223+
}
224+
```
46225

47-
# Modulo imprese
226+
Possiamo anche speficiare i prefissi in modo indipendente:
227+
```php
228+
$this->openapi->SMS->sendOne('Nome del mittente', '3939989741', 'lorem ipsum', '+42', 1, null);
229+
```
48230

49-
## `getByPartitaIva`
231+
O passare delle opzioni
232+
```php
233+
$options = ['timestamp_send' => '2021-04-20']
234+
$this->openapi->SMS->sendOne('Nome del mittente', '3939989741', 'lorem ipsum', '+42', 1, $options);
235+
```
50236

51-
### Introduction
237+
## 7. <a name='ModuloVisengine'></a>Modulo Visengine
238+
Come prima cosa, settiamo l'hash della visura che vogliamo richiedere
52239

53-
La funzione consente di recuperare i dati aziendali a partire dalla partita IVA
240+
```php
241+
// https://developers.openapi.it/services/visengine
242+
$this->openapi->visengine->setHash($visura->hash);
243+
```
54244

55-
### Description
245+
A questo punto, possiamo lanciare `createRequest`, che ritornerà una istanza vuota della visura che andremo a creare della struttura richiesta
56246

57-
`function getByPartitaIva(string $partitaIva, $ttl = 86400):object`
247+
```php
248+
$request = $this->openapi->visengine->createRequest();
249+
```
58250

59-
* $partitaIva: La partita IVA da cercare
60-
* $ttl: Time To Release, per quanti secondi la chiamata resta in cache prima di essere effettuata una seconda volta
251+
Prodediamo a completare l'oggetto, che potremmo passare a sendRequest quando pronto
61252

253+
```php
254+
$request->setJson(['$0' => 'abcd', '$1' => '12485671007']);
255+
// url di callback, oggetto con dati aggiuntivi, metodo
256+
$request->setCallbackData('https://example.com', new stdClass(), 'POST');
257+
$visura = $this->openapi->visengine->sendRequest($request);
258+
```

0 commit comments

Comments
 (0)