OpenAPI Library

• 1. Installation
• 2. Usage
     • 2.1. Instanza della classe
     • 2.2. Esempi
• 3. Modulo comuni
     • 3.1. Esempi
• 4. Modulo imprese
     • 4.1. Utilizzo
     • 4.2. Esempi
• 5. Modulo Marche Temporali
     • 5.1. Esempi
• 6. Modulo SMS
     • 6.1. Inviare un SMS
• 7. Modulo Visengine

1. Installation

composer require altravia/openapi

2. Usage

2.1. Instanza della classe

require_once 'vendor/autoload.php';

$openapi = new \OpenApi\OpenApi($scopes, $user, $apikey, $environment);

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

$scopes = [
    "GET:ws.ufficiopostale.com/comuni",
    [
        "domain"=>"ws.ufficiopostale.com", 
        "method"=>"comuni",
        "mode"  =>"GET"
    ]
];

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

OpenApi si occuperá di reperire automaticamente, o generare, un nuovo token quando necessario.

A questo punto, in base agli scopes indicati vengono creati i seguenti oggetti:

// Ogni oggetto verrá creato solo se disponibile nello scope.
$openapi->ufficiopostale;
$openapi->comuni;
$openapi->imprese;
$openapi->visengine;
$openapi->marcheTemporali;
$openapi->geocoding;
$openapi->SMS;
$openapi->firmaDigitale;
$openapi->pecMassiva;

che possono essere usati al seguente modo:

$this->openapi->ufficioposale->getCitiesByCap('00132');

2.2. Esempi

require_once 'vendor/autoload.php';

// Dichiaro gli scopes necessari
$scopes = [
    'GET:comuni.openapi.it/cap',
    'GET:imprese.altravia.com/advance',
];

$openapi = new OpenApi\OpenApi($scopes, 'my_username','my_api_key', 'test');

// Comuni: prendi informazioni sul cap 00132
$cap = $openapi->comuni->getCitiesByCap('00132');

// Imprese: prendi informazioni su una specifica impresa
$impresa = $openapi->imprese->getByPartitaIva('12485671007');

// Ufficio Postale: ottieni informaizoni sul tracking
$track = $this->openapi->ufficiopostale->track('123456789'); 

3. Modulo comuni

Consente di prendere informazioni su comuni e provincie.

• getCitiesByCap
• getComuneByCatasto
• getRegioni
• getProvince
• getComuni

3.1. Esempi

$provincia = 'RM';
$comuni = $this->openapi->comuni->getComuni($provincia);

var_dump($comuni['comuni']); 
/*

["nome_provincia"]=>
  string(4) "Roma"
  ["sigla_provincia"]=>
  string(2) "RM"
  ["regione"]=>
  string(5) "Lazio"
  ["comuni"]=>
  array(121) {
    [0]=>
    string(6) "Affile"
    ...
*/

4. Modulo imprese

4.1. Utilizzo

Il modulo imprese espone i seguenti metodi:

• getByPartitaIva
• getClosed
• getVatGroup
• getPec
• getBySearch

Per getBySearch e getByPartitaIva è richiesto accesso allo scope /advance

4.2. Esempi

Utilizziamo getBySearch per cercare un'azienda il cui nome inizia con Altrav a Roma

$autocomplete = $this->openapi->imprese->getBySearch('Altrav*', 'RM');

/*
 [0]=>
  object(stdClass)#41 (10) {
    ["piva"]=>
    string(11) "12485671007"
    ["cf"]=>
    string(11) "12485671007"
    ["denominazione"]=>
    string(20) "ALTRAVIA SERVIZI SRL"
 [1]=>
  object(stdClass)#42 (10) {
    ["id"]=>
    string(24) "4242424242"
    ["denominazione"]=>
    string(18) "xxx Altravia Esempio 2"
    ...
 */

5. Modulo Marche Temporali

• availability
• checkLotto
• purcahse

5.1. Esempi

// Controlliamo la disponibilitá di una marca di inforcert o aruba
$disponibilita = $this->openapi->marcheTemporali->availability('infocert', 1);

// Se le marche sono disponibili, acquistiamone una
if ($disponibilita->availability > 0) {
    try {
        $marca = $this->openapi->marcheTemporali->purcahse('infocert', 1);
    } catch (\OpenApi\classes\exception\OpenApiMarcheTemporaliException $e) {
        error_log(var_dump($e));
    }
}

6. Modulo SMS

• getRecipients
• getMessage
• sendMore
• sendOne

6.1. Inviare un SMS

Per inviare un SMS, per prima cosa definiamo i destinatari:

$recipient = '+39-3939989741';
// OR
$recipients = [
    [
        'number' => '+39-3939989741', 
        'fields' => ['nome' => 'NomeDestinatario']
    ]
];

Possiamo ora procedere ad inviare un SMS:

try {
    $priority = 1;
    $options = null;
    $singleSms = $this->openapi->SMS->sendOne('Nome del mittente', $recipient, 'lorem ipsum', null, $priority, $options);
} catch (\OpenApi\classes\exception\OpenApiConnectionsException $e) {
    throw 'Non è stato possibile recapitare il messaggio';
}

Possiamo anche speficiare i prefissi in modo indipendente:

$this->openapi->SMS->sendOne('Nome del mittente', '3939989741', 'lorem ipsum', '+42', 1, null);

O passare delle opzioni

$options = ['timestamp_send' => '2021-04-20']
$this->openapi->SMS->sendOne('Nome del mittente', '3939989741', 'lorem ipsum', '+42', 1, $options);

7. Modulo Visengine

Come prima cosa, settiamo l'hash della visura che vogliamo richiedere

// https://developers.openapi.it/services/visengine
$this->openapi->visengine->setHash($visura->hash);

A questo punto, possiamo lanciare createRequest, che ritornerà una istanza vuota della visura che andremo a creare della struttura richiesta

$request = $this->openapi->visengine->createRequest();

Prodediamo a completare l'oggetto, che potremmo passare a sendRequest quando pronto

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