Sirdsdraugs.lv API

Sirdsdraugs.lv API ļauj sadarbības partnera (jebkurai Latvijas dzīvnieku patversmei) lapai publicēt informāciju par dzīvniekiem sirdsdraugs.lv platformā. Sadarbības partnera tīmekļa lapai jāsūta POST HTTP pieprasījums sirdsdraugs.lv platformai ikreiz, kad tiek pievienots jauns dzīvnieks, vai mainīta informācija par patversmē jau esošu dzīvnieku.

API URL

Jauna dzīvnieka pievienošanas vai jau esoša dzīvnieka informācijas modificēšanas gadījumā, jāsūta POST pieprasījums uz adresi http://sirdsdraugs.lv/api/import/

Pieprasījuma uzbūve

POST pieprasījuma parametri:

  • apiver - API versijas numurs, šobrīd = 1
  • apikey - API atslēgas numurs, 32 simbolu String, tiks nosūtīts sadarbības partnerim.
  • data - masīvs ar datiem.

Datu masīva saturs:

  • original_rec_id (obligāts) - unikāls ieraksta ID dzīvnieku tabulā (datu tips nav svarīgs)
  • pet_type_id (obligāts) - dzīvnieka tips (1 - kaķis, 2 - suns, 3 - cits dzīvnieks)
  • pet_name - dzīvnieka vārds vai null
  • description (obligāts) - apraksts vai null
  • sex (obligāts) - dzimums (v - vīriešu, s - sieviešu)
  • sterilized - vai dzīvnieks ir sterilizēts (1 - sterilizēts, 0 - nav sterilizēts)
  • age_in_months (obligāts) - dzīvnieka vecums mēnešos (int)
  • image1 (obligāts) - pilns HTTP ceļš uz pirmo bildi (1 no 4 poz) vai null
  • image2 - pilns HTTP ceļš uz pirmo bildi (2 no 4 poz) vai null
  • image3 - pilns HTTP ceļš uz pirmo bildi (3 no 4 poz) vai null
  • image4 - pilns HTTP ceļš uz pirmo bildi (4 no 4 poz) vai null
  • adopted (obligāts) - vai dzīvnieks ir adoptēts (1 - adoptēts, 0 - nav adoptēts). Viena no šī lauka fiziskajām nozīmēm ir aktivitātes statuss. Ja 1 - tiek rādīts mājas lapā, ja 0 - vairs netiek rādīts
  • date_adopted - dzīvnieka adoptēšanas datums vai null, ja vēl nav adoptēts
  • date_taken_in (obligāts) - dzīvnieka patversmē pieņemšanas datums vai null
  • date_modified (obligāts) - ieraksta modificēšanas datums (tips datetime)

Ja Jūsu sistēmā nav kāds no obligātajiem laukiem, tad tie būtu jāpievieno.

Atbildes uzbūve

Atbilde no servera veiksmīga (vai neveiksmīga) datu sūtīšanas mēģinājum agadījumā tiks sūtīta JSON formātā un saturēs sekojošus laukus:

  • status (obligāts)  - 1 vai 0. 1 - veiksmīgs pieprasījums, 0 - neveiksmīgs.
  • msg - Kļūdas paziņojums (neveiksmīga pieprasījuma gadījumā). Iespējamie atbildes ziņojumi kļūdas gadījumā: [incorect API key | Not all required data fields where supplied | Data not accepted]

JSON Atbildes piemērs

// Atbilde veiksmīgi notikuša pieprasījuma gadījumā:

[
    {
        "status": 1
    }
]    

// Atbilde neveiksmīgi notikuša pieprasījuma gadījumā:

[
    {
        "status": 1,
        "msg": "Not all required fields where supplied!"
    }
] 

PHP programmas piemērs:

POST veikšanai varat izmantot sekojošu funkciju:

function POST($url_, $data_, $optional_headers_ = null)
{
    $data = http_build_query($data_);
    $headers = ($optional_headers_ == null ? 'Content-type: application/x-www-form-urlencoded' : $optional_headers_);
    $opts = array('http' =>
                        array
                        (
                            'method'  => 'POST',
                            'header'  => $headers,
                            'content' => $data
                        )
                  );

    $ctx = stream_context_create($opts);
    $fp = @fopen($url_, 'r', false, $ctx);
    if (!$fp) 
    {
        return false;
    }

    $response = @stream_get_contents($fp);
    if ($response === false) 
    {
        return false;
    }
return $response;
}
 

Strādājošs programmas koda fragments:

 /* Pēc formas POST, ja ieraksts ir veiksmīgi pievienots, vai labots ($success), tad sūtam pievienotos vai labotos datus uz sirdsdraugs.lv */

if ($success) // Ja ieraksts veiksmīgi pievienots / labots
{
	$postdata = array();

	$postdata['apiver'] = 1;
	$postdata['apikey'] = 'f68929bz539we99851a6e3858314g30f'; // Atslēgas piemērs, īsta atslēga tiks iedota
	
	$data = array();
	
	$data['original_rec_id'] = '346';                                        
	$data['adopted'] = 0;
	$data['pet_type_id'] = 1;
	$data['sex'] ='v';
	// $data['sterilized'] = 1; // sūtam, ja lauks pieejams 
	$data['age_in_months'] = 23;
	$data['date_taken_in'] = '2012-12-12 00:00:00';
	//$data['pet_name'] = ''; // sūtam, ja ir
	$data['description'] = 'Labdabīgs tāds';
	$data['image1'] = "http://www.superpatvermse.lv/atteli/neris.jpg";
	//$data['image2'] = ""; // sūtam, ja lauks pieejams
	//$data['image3'] = ""; // sūtam, ja lauks pieejams
	//$data['image4'] = ""; // sūtam, ja lauks pieejams
	//$data['date_adopted'] = '2012-06-12 14:53:42'; // sūtam, ja ir zināms
	$data['date_modified'] = '2012-06-13 17:00:00';

	$postdata['data'] = $data;

	$response = POST("http://sirdsdraugs.lv/api/import/", $postdata);
	if ($response)
	{
            $resp_msg = '';
            $response_json = json_decode($response, true);
            $resp_status = $response_json['status']; // atbildes statuss no sirdsdraugs.lv 
            if ($resp_status==0) // ja ieraksts netika pievienots veiksmīgi, saņemam atbildes ziņojumu
                $resp_msg = $response_json['msg']; 
	}		
}


Noderīgi zināt

  • Uz platfromu sirdsdraugs.lv aizsūtītie dati netiek uzreiz publicēti portālā. Ja esat saņēmis atbildi no servera, ka ieraksts ir veiksmīgi pievienots, tad viss ir kārtībā. Portālā tas parādīsies ar pāris stundu aizturi.
  • Nosūtītie dzīvnieku attēli fiziski tiek glabāti sirdsdraugs.lv platformā. HTTP pieprasījums uz ielasāmajiem attēliem tiek veikts tikai un vienīgi tā ielasīšanas brīdī, t.i., ja pirms importa attēla url ir
    http://patversme.lv/img/big/5003e2a6ef258.png, tad pēc importa, piemēram,
    http://sirdsdraugs.lv/images/5003e2a6ef258.png