API להפקת חשבוניות וקבלות - מבוא (חלק 1)

התחברות ל API להפקת מסמכים עם דוגמאות קוד בשפות שונות

המדריך הבא מציג הנחיות לממשק ה- API הישן. לממשק ה- API החדש שלנו, לחצו כאן.

 

כדי להפיק מסמכים באמצעות ה API עליכם לוודא שיש ברשותכם זוג מפתחות תקינים.
לחצו כאן ללמוד עוד על יצירת מפתחות API במערכת חשבונית ירוקה.

 

תיאור כללי של תהליך הפקת המסמכים

על מבנה הנתונים שמתאר את סוג המסמך ופרטיו להישלח למערכת חשבונית ירוקה בפורמט של JSON ושיטת POST. אחרי שנשלחת בקשה המערכת בודקת ומאמתת את תקינות הבקשה והמידע. לאחר מכן, במקרה שהבקשה תקינה, מתקבלת מאיתנו תשובה מתאימה עם ticket_id שמזהה את הבקשה באופן ייחודי במערכת. אם הבקשה אינה תקינה מתקבל קוד שגיאה ותיאור באנגלית.

שימו לב כי עליכם לעבוד בקידוד שפה UTF-8 בלבד!

תהליך הפקת המסמך מתבצע באופן א-סינכרוני. כלומר, לאחר שמתקבל אישור על תקינות הבקשה, התהליך עובר עיבוד ברקע ולאחר סיומו, נשלחת אליכם הודעה עם פרטי החשבונית שנוצרה לכתובת ה URL אותה הגדרתם בבקשה המקורית (callback_url).

זהו מבנה נתונים לדוגמא שעליכם לשלוח בבקשה להפקת חשבונית מס-קבלה:

    {
        "timestamp": 1380095506, //Current timestamp
        "callback_url": "{your-callback-url}",
        "doc_type": 320, //סוג מסמך
        "description": "תיאור מסמך",
        "client": {
            "name": "לקוח חדש",
            "tax_id": "123456789",
            "email": "user@email.com",
            "address": "רח' דיזנגוף 300",
            "city": "תל אביב",
            "zip": "1234567"
        },
        "income": [
            {
                "price": 500.00,
                "description": "תיאור שורת הכנסה"
            }
        ],
        "payment": [
            {
                "type": 2 //Cheque,
                "date": "2012-01-01", //YYYY-MM-DD
                "amount": 500.00,
                "bank": "מזרחי טפחות",
                "branch": "761",
                "account": "123456",
                "number": "10928"
            }
        ]
    }

 

את אובייקט הנתונים, שנקרא לו לצורך הענין בשם params, יש לחתום באופן הבא (דוגמא ב php):

    $params_encoded = json_encode($params);
    $signature = base64_encode(hash_hmac('sha256', $params_encoded, "{api_secret}", true));

 

לאחר מכן, יש לשלוח את החתימה ואת המפתח הציבורי שלכם למערכת ה API (דוגמא ב php):

    $data = array(
        "apiKey" => $apiKey,
        "params" => $params,
        "sig" => $signature
    );

    //Initializing curl
    $ch = curl_init();

    //Configuring curl options
    $options = array(
        CURLOPT_URL => "https://www.greeninvoice.co.il/api/documents/add",
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => "data=" . urlencode(json_encode($data)),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => array("Content-Type: application/x-www-form-urlencoded; charset=utf-8")
    );

    //Setting curl options
    curl_setopt_array($ch, $options);

    //Getting results
    $result = curl_exec($ch); // Getting jSON result string
    curl_close($ch);

 

לאחר שליחת הבקשה נחזיר אליכם תשובה מיידית (סינכרונית) עם פרטים כלליים:

{
  "error_code": 0,
  "error_description": "OK",
  "timestamp": 1406452638,
  "processing_time_ms": 3.778,
  "data": {
    "ticket_id": "3d0d7541-d5ad-aae4-69b6-f34adca9e12a" //מספר בקשה
  }
}

 

תשובה א-סינכרונית (מנגנון Callback), לאחר סיום הטיפול בבקשה:

מפתח ה API לכתיבה מוגדר בזמן הקמתו במצב דמו, כדי לאפשר לכם לבצע בדיקות מלאות. במצב כזה מוחזרים לכתובת ה callback שהגדרתם הנתונים הבאים ב POST:

//Get preview document URL    
$ticketId = $_POST["ticket_id"]; //מספר בקשה
$documentUrl = $_POST["url"]; //כתובת מסמך לדוגמא להורדה

במידה והשרת שלכם נכשל בקבלת הבקשה מאיתנו אנו ננסה שוב מדי 15-20 דקות עד להצלחה, במשך 36 שעות.
יש להחזיר status code 200 תוך 15 שניות לכל היותר, אחרת הבקשה תוגדר כנכשלה ואנו נבצע קריאה נוספת בחלון הזמן הבא.

לאחר מעבר למצב פעיל, המסמכים האמיתיים יופקו ותקבלו את המידע הרלבנטי להורדה שלהם:

//Get real document URLs    
$ticketId = $_POST["ticket_id"]; //מספר בקשה בפורמט GUID
$documentUrl = $_POST["url"]; //כתובת מסמך מקור להורדה
$id = $_POST["id"]; //מזהה ייחודי של המסמך בפורמט GUID
$document_id = $_POST["document_id"]; //מספר המסמך שהופק
$externalData = $_POST["external_data"]; //נתונים שהזנתם בבקשה המקורית
$clientId = $_POST["client_id"]; //מזהה לקוח במערכת שנוסף בבקשת יצירת מסמך בפורמט GUID

 

המשך קריאה:

עדיין זקוקים לעזרה?

אנחנו כאן בכל עניין ולכל שאלה. ביום עסקים רגיל, בין השעות 9:00 ל-18:00, אנחנו עונים תוך מספר דקות.