Zcomercial - API Docs

Welcome to Zcomercial API v1

If you're reading this, you need to issue invoices but don't want to lose focus from building a great solution and writing amazing code. Did we cover your scenario? Ok, great. Let's do this.

Quick Start:
1. Sign up FREE for 10 days
2. Get your API key
3. Create an Invoice

https://api.zcomercial.com

API Format

All request bodies should have content type application/json and be valid JSON. The Content-Type header must be set in all requests that include a JSON body:

Content-Type: application/json

 Content-Type: application/json

Authentication

You authenticate to the Zcomercial API by providing your API Key in the Authorization header of every request:

Authorization: [YOUR_API_KEY]

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Info! Make sure you keep your API Key a secret!.

To authenticate, provide the API Key in the request header:



curl 'https://api.zcomercial.com/v1' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

Make sure to replace sferdfbGE47fb22eZvKYlo2Cc0fo87EHa in the example with your own API Key.

Errors

Erros

200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on example's end. (These are rare.)

Invoice

Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients.

Get

Returns all .

HTTP Request
GET https://api.zcomercial.com/v1/invoice



curl "https://api.zcomercial.com/v1/invoice" \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

The above command returns JSON structured like this:


{
  "invoice": [
    {
      "id": "60ce210ff3363",
      "sequence_number": "PP 2021/4",
      "status": "Final",
      "archived": "0",
      "type": "Factura",
      "date": "2021-04-25",
      "saft_hash": "GWAa",
      "due_date": "2021-05-02",
      "reference": "",
      "observations": "",
      "retention": "0",
      "currency": "AKZ",
      "valor": "20000",
      "custumer": {
        "id": "999",
        "name": "Zingangu comercial, Lda",
        "fiscal_id": "9999999999"
      },
      "items": [
        {
          "name": "serviço de net",
          "description": "serviço de net",
          "unit_price": "5000",
          "quantity": "2",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 10000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 10000
        },
        {
          "name": "Novo biometrico",
          "description": "Novo biometrico",
          "unit_price": "5000",
          "quantity": "1",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 5000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 5000
        },
        {
          "name": "timbrado",
          "description": "timbrado",
          "unit_price": "5000",
          "quantity": "1",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 5000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 5000
        }
      ],
      "mx_reference": {
        "entity": "00000",
        "value": "20000",
        "reference": ""
      }
    },
"meta": {
    "total_count": 1,
    "offset": 0,
    "limit": 20
  }

Get a specific invoice.

HTTP Request
GET https://api.zcomercial.com/v1/invoice/<ID>



curl "https://api.zcomercial.com/v1/invoice" \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

The above command returns JSON structured like this:


{
  "invoice": {
      "id": "60ce210ff3363",
      "sequence_number": "PP 2021/4",
      "status": "Final",
      "archived": "0",
      "type": "Factura",
      "date": "2021-04-25",
      "saft_hash": "GWAa",
      "due_date": "2021-05-02",
      "reference": "",
      "observations": "",
      "retention": "0",
      "currency": "AKZ",
      "valor": "20000",
      "custumer": {
        "id": "999",
        "name": "Zingangu comercial, Lda",
        "fiscal_id": "9999999999"
      },
      "items": [
        {
          "name": "serviço de net",
          "description": "serviço de net",
          "unit_price": "5000",
          "quantity": "2",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 10000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 10000
        },
        {
          "name": "Novo biometrico",
          "description": "Novo biometrico",
          "unit_price": "5000",
          "quantity": "1",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 5000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 5000
        },
        {
          "name": "timbrado",
          "description": "timbrado",
          "unit_price": "5000",
          "quantity": "1",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 5000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 5000
        }
      ],
      "mx_reference": {
        "entity": "00000",
        "value": "20000",
        "reference": ""
      }
    }
 }

Creat

Creates a new invoice, invoice_receipt, credit_note or debit_note.

Creating new clients or items along with the invoice

This method also allows to create a new client and/or new items in the same request with the following behavior:

If the client name does not exist a new one is created.
If items do not exist with the given names, new ones will be created.
If item name already exists, the item is updated with the new values.
Taxes
Regarding item taxes, if the tax name is not found, the default tax is applyed to that item. accounts should also send the IVA exemption reason if the invoice contains exempt items (IVA 0%).

HTTP Request
POST https://api.zcomercial.com/v1/invoice/create

Body Request

Name	Type	Required	Description
`invoice`	Object	Required	Invoice data to be created
`date`	String	Required	The invoice date. Must be in format yyy/mm/dd . If format is invalid, date will be set to current date.
`due_date`	String	Required	The invoice due date. Must be in format yyy/mm/dd. If format is invalid, date will be set to current date.
`reference`	String		The invoice purchase order reference field.
`observations`	String		Invoice observations, these will be printed with the invoice.
`retention`	String		Withholding tax percentage (%). Must be a number between 0 and 99.99.
`tax_exemption`	String	Depends	Angolan IVA exemption code. accounts on invoices with IVA exempt items (0%). Refer to the <> for the complete list of “IVA Exemption Codes”.
`client`	Object	Required
`name`	String	Required	The invoice’s client. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.
`id`	String	Required	The client’s unique code. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.
`email`	String		Client email address. Must be a valid email address ex: foo@bar.com
`address`	String		Client company address.
`city`	String		Client’s city.
`postal_code`	String		Client’s postal code for it’s company address.
`country`	String		Country, normally used for a company country. Although country is optional, when supplied, it should match one of the country list on the <> of this Documentation.
`fiscal_id`	String		The client fiscal ID (Número de Contribuinte)
`website`	String		The client web address
`phone`	String		The client phone number
`fax`	String		The client fax number
`observations`	String		The client default observations. This is added to the observations field of all the invoices sent to this client.
`items`	Array	Required	An array of invoice items. If items with the given names do not exist, they are created. If an item already exists, it is updated with the new values. At least one is required.
`name`	String	Required	Name of the item. Must be unique.
`description`	String	Required	Item’s description
`unit_price`	Number	Required	Item’s unit price. Must be a number equal or greater than 0.0.
`quantity`	Number	Required	Quantity. Must be a number equal or greater than 0.
`type`	String		P - to Product or S - to Service
`discount`	Number		The item discount percentage(%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.
`tax`	Object		The tax applied to the item line. If not present the default tax is applied to the item
`name`	String		The tax name to be used on this item line. If not found the default tax is applied to the line item
`mx_reference`	String		Generates a Multicaixa Reference after you finalize your invoice. This option is only available for Angolan Accounts. You must have the feature enabled on your account first.
`owner_invoice_id`	Integer		The (owner) invoice associated to this document. This option is only available for credit_notes or debit_notes. You can also send the (owner) guide id when creating an invoice to associate an invoice to a guide.
`tax_exemption_reason`	String		Used when updating a document and removing all tax exempt items. The code M00 means 'Without tax exemption'.
`currency_code`	String		If your plan as multicurrency, you can issue invoices in another currency than your account's default currency. The currency_code should be one of the following currency codes.
`rate`	String		When sending a currency_code you can specify its' rate.



curl -XPOST 'https://api.zcomercial.com/v1/invoice/create' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \
  -d '{
  "invoice":
	{
		"date":"2021-04-25",
		"due_date":"",
		"observations":"",
		"reference":"",
		"retencao":"",
		"type":"FT",
		"client": 
			{
			"name":"Zingangu comercial, Lda",
			"fiscal_id":"9999999999",
			"email":"info@zingangu.com",
            "website":"www.zingangu.com",
			"address":"Centralidade Vida Pacifica",
			"city":"Luanda",
			"country": "Angola",
			"tphone":"",
			"fax":"",
			"mobile":"",
			"postal_code":"",
			"short_name":""
			},
		"items":
				[ 
					{
						"nome":"registo de dominio (.teste17)",
						 "unit_price":"5000",
						 "quantity":"2",
						 "discount":"0",
						 "type":"S",
						 "description":"serviço de net"
					},
					{
						"name":"relogio biometrico A3",
						"unit_price":"5000",
						"quantity":"1",
						"discount":"0",
						"type":"P",
						"description":"Novo biometrico"
					},
					{
						"name":"camisola S",
						"unit_price":"5000",
						"quantity":"1",
						"discount":"0",
						"type":"P",
						"description":"timbrado"
						}
				]
	}
	
}' \

The above command returns JSON structured like this:


{
  "invoice": {
      "id": "60ce210ff3363",
      "sequence_number": "PP 2021/4",
      "status": "Final",
      "archived": "0",
      "type": "Factura",
      "date": "2021-04-25",
      "saft_hash": "GWAa",
      "due_date": "2021-05-02",
      "reference": "",
      "observations": "",
      "retention": "0",
      "currency": "AKZ",
      "valor": "20000",
      "custumer": {
        "id": "999",
        "name": "Zingangu comercial, Lda",
        "fiscal_id": "9999999999"
      },
      "items": [
        {
          "name": "serviço de net",
          "description": "serviço de net",
          "unit_price": "5000",
          "quantity": "2",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 10000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 10000
        },
        {
          "name": "Novo biometrico",
          "description": "Novo biometrico",
          "unit_price": "5000",
          "quantity": "1",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 5000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 5000
        },
        {
          "name": "timbrado",
          "description": "timbrado",
          "unit_price": "5000",
          "quantity": "1",
          "tax": {
            "id": "676",
            "name": "IVA",
            "value": "0"
          },
          "discount": "0",
          "subtotal": 5000,
          "tax_amount": "0",
          "discount_amount": "0",
          "total": 5000
        }
      ],
      "mx_reference": {
        "entity": "00000",
        "value": "20000",
        "reference": ""
      }
    },
}

Chenge-status

building

Creat

Creates a payment which generates a receipt. This endpoint is only available for invoices, vat_moss_invoices.

HTTP Request
GET https://api.zcomercial.com/v1/invoice/create

Body Request

Name	Type	Required	Description
`payment`	Object	Required	Payment data
`payment_mechanism`	String		How the payment was made. Check the appendix for possible values. Defaults to client settings or account settings if defined. Otherwise, defaults to ‘TB’.
`note`	String		Observations.
`amount`	Number	Required	Amount of the partial payment. Must be a value greater or equal to zero.
`payment_date`	String		Date of the payment. Defaults to today.



curl -XPOST 'https://api.zcomercial.com/v1/invoice/payment' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \
  -d '{
  "payment": {
    "invoice": "60d0e316ef705",
    "payment_mechanism": "TB",
    "note": "Observations",
    "amount": 100,
    "payment_date": "2021-05-28 15:34:39"
  }
}' \

The above command returns JSON structured like this:


{
  "receipt": {
    "id": "60d0e62368fff",
    "sequence_number": "RC 2021/41",
    "status": "Pago",
    "archived": "0",
    "type": "Recibo",
    "date": "2021-05-28",
    "saft_hash": "",
    "due_date": "0000-00-00",
    "reference": "",
    "observations": "Observations",
    "retention": "0",
    "currency": "",
    "valor": "100",
    "custumer": {
      "id": "1459",
      "name": "Arpetic, Lda",
      "fiscal_id": "5417295089"
    },
    "items": [
      {
        "name": "serviço de net",
        "description": "serviço de net",
        "unit_price": "5000",
        "quantity": "2",
        "tax": {
          "id": "676",
          "name": "IVA",
          "value": "0"
        },
        "discount": "0",
        "subtotal": 10000,
        "tax_amount": "0",
        "discount_amount": "0",
        "total": 10000
      },
      {
        "name": "Novo biometrico",
        "description": "Novo biometrico",
        "unit_price": "5000",
        "quantity": "1",
        "tax": {
          "id": "676",
          "name": "IVA",
          "value": "0"
        },
        "discount": "0",
        "subtotal": 5000,
        "tax_amount": "0",
        "discount_amount": "0",
        "total": 5000
      },
      {
        "name": "timbrado",
        "description": "timbrado",
        "unit_price": "5000",
        "quantity": "1",
        "tax": {
          "id": "676",
          "name": "IVA",
          "value": "0"
        },
        "discount": "0",
        "subtotal": 5000,
        "tax_amount": "0",
        "discount_amount": "0",
        "total": 5000
      }
    ]
  }
}

Cancel-payment

building

Send by Email

Sends a document by email.

HTTP Request
POST https://api.zcomercial.com/v1/invoice/pdf
br> Body Request

Name	Type	Required	Description
`message`	Object	Required	Email data.
`client`	Object		Client email and save options.
`email`	String	Required	Document will be sent to this email address. Must be a valid email address: foo@bar.com
`save`	String	Required	Saves this email as your client email address. (0 – Does not save the client’s email. 1 – Saves / Updates the client’s email).
`subject`	String		The subject of the email.
`body`	String		The body of the email.
`cc`	String		Email CC field. Must be a valid email address ex: foo@bar.com
`bcc`	String		Email BCC field. Must be a valid email address ex: foo@bar.com
`logo`	String		Send email with logo. Defaults to 0. Only available in some plans. It’s ignored if the account doesn’t have the logo configured. Not available for trial accounts. (0 - Send email without logo. 1 - Send email with logo )



curl -XPOST 'https://api.zcomercial.com/v1/invoice/send' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \
  -d '{
  "message": {
		"doc": "Invoice",
		"id": "60d12a142cefa",
    "client": {
      "email": "someone@example.com",
      "save": "0"
    },
    "subject": "Invoice from company",
    "body": "This is where the email body goes",
    "cc": "cc.client@company.com",
    "bcc": "bcc.client@company.com",
    "logo": "0"
  }
}' \

Generate pdf

Returns the url of the PDF for the specified document. This is an asynchronous operation, which means the PDF file may not be ready immediately.

HTTP Request
POST https://api.zcomercial.com/invoice/pdf



curl -XPOST 'https://api.zcomercial.com/v1/invoice/pdf' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \
  -d '{
  "pdf": {
    "doc": "invoice",
    "id": "60d12a142cefa",
    "second_copy": "null"
  }
}' \

or


curl -XPOST 'https://api.zcomercial.com/v1/invoice/pdf' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \
  -d '{
  "pdf": {
    "doc": "invoicemini",
    "id": "60d12a142cefa",
    "second_copy": "null"
  }
}' \

or



curl -XPOST 'https://api.zcomercial.com/v1/invoice/pdf' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \
  -d '{
  "pdf": {
    "doc": "receipt",
    "id": "60d12a142cefa",
    "second_copy": "null"
  }
}' \

The above command returns JSON structured like this:


{
  "pdf": {
    "invoice_url": "http://pdfurl"
  }
}

Welcome to Zcomercial API v1

API Format

Authentication

Errors

Erros

Invoice

Get

Creat

Chenge-status

building

Related documents

building

Creat

Cancel-payment

building

Send by Email

Generate pdf

Clients

building

Items

building

SAF T

building