Skip to content

Latest commit

 

History

History
188 lines (158 loc) · 5.59 KB

API-REFERENCE.md

File metadata and controls

188 lines (158 loc) · 5.59 KB

Carbone Render Go SDK

The Carbone Go SDK provides a simple interface to communicate with Carbone Cloud API easily.

Install the GO SDK

go install github.com/carboneio/carbone-sdk-go@latest

Quickstart with the GO SDK

Try the following code to render a report in 10 seconds. Just replace your API key, the template you want to render, and the data as a stringified JSON.

package main

import (
	"io/ioutil"
	"log"

	"github.com/carboneio/carbone-sdk-go/carbone"
)

func main() {
	csdk, err := carbone.NewCarboneSDK("YOUR-ACCESS-TOKEN")
	if err != nil {
		log.Fatal(err)
  }
  // Path to your template
  templateID := "./folder/template.odt"
  // Add your data here
	jsonData := `{"data":{},"convertTo":"pdf"}`
	reportBuffer, err := csdk.Render(templateID, jsonData)
	if err != nil {
		log.Fatal(err)
	}
	err = ioutil.WriteFile("Report.pdf", reportBuffer, 0644)
	if err != nil {
		log.Fatal(err)
	}
}

GO SDK API

NewCarboneSDK

func NewCarboneSDK(SecretAccessToken ...string) (*CSDK, error)

Function to create a new instance of CSDK (CarboneSDK). The access token can be pass as the first argument to NewCarboneSDK (args[0]) or by the environment variable "CARBONE_TOKEN". The Api URL can be pass the second argument (args[1]) or by the environment variable "CARBONE_URL". To set a new environment variable, use the command:

$ export CARBONE_TOKEN=your-secret-token

Check if it is set by running:

$ printenv | grep "CARBONE_TOKEN"

Example

// Carbone access token passed as parameter
csdk, err := carbone.NewCarboneSDK("YOUR-ACCESS-TOKEN")
// Carbone access token passed as environment variable "Carbone TOKEN"
csdk, err := carbone.NewCarboneSDK()
// Carbone access token passed as parameter with a custom API URL as second parameter
csdk, err := carbone.NewCarboneSDK("TOKEN", "https://test.carbone.io")

Render

func (csdk *CSDK) Render(pathOrTemplateID string, jsonData string, payload ...string) ([]byte, error)

The render function takes pathOrTemplateID the path of your local file OR a templateID, jsonData a stringified JSON, and an optional payload.

It returns the report as a []byte. Carbone engine deleted files that have not been used for a while. By using this method, if your file has been deleted, the SDK will automatically upload it again and return you the result.

When a template file path is passed as an argument, the function verifies if the template has been uploaded to render the report. If not, it calls AddTemplate to upload the template to the server and generate a new template ID. Then it calls RenderReport and GetReport to generate the report. If the path does not exist, an error is returned.

When a templateID is passed as an argument, the function renders with RenderReport then call GetReport to return the report. If the templateID does not exist, an error is returned.

Example

reportBuffer, err := csdk.Render("./templates/invoice.docx", `{"data":{"nane":"eric"},"convertTo":"pdf"}`, "OptionalPayload1234")
if err != nil {
	log.Fatal(err)
}
// create the file
err = ioutil.WriteFile("Report.pdf", reportBuffer, 0644)
if err != nil {
	log.Fatal(err)
}

AddTemplate

func (csdk *CSDK) AddTemplate(templateFileName string, payload ...string) (APIResponse, error)

Add the template to the API and returns an APIResponse struct (that contains a TemplateID). You can add multiple times the same template and get different templateId thanks to the optional payload.

Example

resp, err := csdk.AddTemplate("./tests/template.test.odt")
if err != nil {
	t.Error(err)
}
if resp.Success == false {
	t.Error(resp.Error)
}
if len(resp.Data.TemplateID) <= 0 {
	t.Error(errors.New("templateId not returned from the api"))
}
fmt.Println("templateID:", resp.Data.TemplateID)

GetTemplate

func (csdk *CSDK) GetTemplate(templateID string) ([]byte, error)

Pass a templateID to the function and it returns the template as []byte. The templateID must exist otherwise an error is returned by the server.

	templateData, err := csdk.GetTemplate("TemplateId")
	if err != nil || len(templateData) <= 0 {
		t.Error(err)
	}
	err = ioutil.WriteFile(filename, templateData, 0644)
	if err != nil {
		t.Error(err)
	}

DeleteTemplate

func (csdk *CSDK) DeleteTemplate(templateID string) (APIResponse, error)

Example

resp, err := csdk.DeleteTemplate(templateID)
if err != nil {
	t.Error(err)
}
if resp.Success == false {
	t.Error(resp.Error)
}

GenerateTemplateID

func (csdk *CSDK) GenerateTemplateID(filepath string, payload ...string) (string, error)

The Template ID is predictable and idempotent, pass the template path and it will return the templateID. You can get a different templateId thanks to the optional payload.

SetAccessToken

func (csdk *CSDK) SetAccessToken(newToken string)

It sets the Carbone access token.

SetAPIVersion

func (csdk *CSDK) SetAPIVersion(version int)

It sets the the Carbone version requested. By default, it is calling the version 2 of Carbone.

Note: You can only set a major version of carbone.

GetAPIVersion

func (csdk *CSDK) GetAPIVersion() (int, error)

It returns the Carbone version.

SetApiHeaders

Set custom Carbone headers, it will be injected for all API requests.

csdk.SetAPIHeaders(map[string]string{
	"carbone-template-delete-after": "86400", // https://carbone.io/api-reference.html#template-storage
	"carbone-webhook-url": "https://...", // https://carbone.io/api-reference.html#api-webhook
})