Documentation

  2. Home
  4. Docs
  6. Documentation
  8. Invoicing APIs – V1
  10. API: Create Collection Receipt

API: Create Collection Receipt

The purpose of this API is to create new collection receipt.

Request

URL https://your_account.modulus.biz/api/inv/v1/CollectionReceipt=YOUR_TOKEN
API Name CollectionReceipt
Method POST
Source Third Party Server
Recipient modulus® Server
Content Type application/json

Query String Parameters

Parameter Required Type Description
token Yes Text Your authentication token.

Payload Parameters

Parameter Required Type Description
customer_details Yes Object Refers to customer info the collection receipt issued to. The structure explained here .
branch_code Yes Text The code of an active branch.
account_code Yes Text The code of the cash account receives the cash amount.
date Yes Date Date format must be ISO 8601 (Example: “2020-01-10”).
book_id Yes Number Refers to cash book used for the collection receipt. Must be For Collection Receipt.
payment_term_id Yes Number Refers to the payment term used in the receipt.
exchange_rate No Decimal Number The exchange rate when the receipt is issued. Mandatory if the customer has foreign currency.
salesperson_id No Number Refers to salesperson linked to the branch of this Collection Receipt.
reference No Text Collection Receipt reference.
description No Text Collection Receipt description.
items Yes Array An array that contains at least one item. The structure explained here.

Item Parameter Details

Parameter Required Type Description
item_code Yes Text Item code.
unit_id Yes Number Refer to the unit of the sent quantity.
quantity Yes Decimal Number The quantity of the item can not be less than or equal to 0.
unit_price No Decimal Number The price of the item. If not sent will defined price in the customer or branch default price list.
discount No Decimal Number Discount per unit if exist but can not exceed price.

Customer Parameter Details

Parameter Required Type Description
code Yes Text The code of the customer the collection receipt is issued to.
name Yes Text The name of the customer the collection receipt is issued to.
type Yes Text The type of the customer the collection receipt is issued to. Possible values are: (individual/organization).
tax_registration_number No Number Customer’s Tax Registration Number.
account_code No Text The code of the cash account of the customer.
price_list_code No Number The code of the price list of the customer. It must have the same currency as the customer and account.
address No Object The address of the customer. The structure is explained here .
contact No Object The contact of the customer. The structure is explained here .

Address Parameter Details

Parameter Type Required Description
label Text Yes The label of the address.
country_code Text Yes The country code of the address (Example: “EG”).
city Text Yes The name of the city in the specified country.
address Text No Additional info of the address.

Contact Parameter Details

Parameter Type Required Description
type Text Yes The type of the contact provided. Possible values are: (mobile/phone/email/fax/website/other).
label Text Yes The label of the contact.
value Text Yes The value of the contact.

Responses

HTTP Status result title message object
Success Responses
200 OK true Success Collection Receipt added successfully. 
{
    "collection_receipt_id": xxx,
    "collection_receipt_serial": "YYY_ZZZZ",
    "document_type": "Collection Receipt",
    "creation_date_time": "yyy-mm-dd hh:MM:ss"
}
Failure Responses
400 Bad Request false Error Error message as elaborated here. 
{
    "error_code": xxx
}
500 Internal Server Error false Error Error message as elaborated here. 
{
    "error_code": xxx
}

Example 1

Request 
curl --request POST 'https://your_account.modulus.biz/api/inv/v1/CollectionReceipt=YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{ 
    "customer_details": {
        "code": "1",
        "name": "Test name",
        "type": "individual",
        "account_code": "1.6.10.2",
        "price_list_code": "1",
        "tax_registration_number": "1",
        "contact": {
            "type": "mobile",
            "label": "القاهرة الجديدة",
            "value": "0102224791"
        },
        "address": {
            "label": "HEADOFFICE",
            "country_code": "EG",
            "city": "Alexandria",
            "address": "Test Address"
        }
    },
    "account_code": "1.6.2.4",
    "exchange_rate": 20,
    "branch_code": "2",
    "date": "2024-01-01",
    "book_id": 4,
    "payment_term_id": 2,
    "items": [{
        "item_code": "451",
        "unit_id": 3,
        "quantity": 50,
        "unit_price": 100
    }]
}'
200 OK 
{
    "result": true,
    "title": "Success",
    "message": "Collection Receipt added successfully.",
    "object": {
        "collection_receipt_id": 34,
        "collection_receipt_serial": "CSH_2024_01_01_005",
        "document_type": "Collection Receipt",
        "creation_date_time": "2024-01-14 00:09:00"
    }
}

Example 2

Request 
curl --request POST 'https://your_account.modulus.biz/api/inv/v1/CollectionReceipt=YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{ 
    "customer_details": {
        "code": "1",
        "name": "Test name",
        "type": "individual",
        "account_code": "1.6.10.2",
        "price_list_code": "1",
        "tax_registration_number": "1",
        "contact": {
            "type": "mobile",
            "label": "القاهرة الجديدة",
            "value": "0102224791"
        },
        "address": {
            "label": "HEADOFFICE",
            "country_code": "EG",
            "city": "Alexandria",
            "address": "Test Address"
        }
    },
    "account_code": "1.6.3.4",
    "exchange_rate": 20,
    "branch_code": "2",
    "date": "2024-01-01",
    "book_id": 4,
    "payment_term_id": 2,
    "reference": "CR-0883",
    "items": [{
        "item_code": "6",
        "unit_id": 2,
        "quantity": 15,
        "unit_price": 40
    }]
}'
400 Bad Request 
{
    "result": false,
    "title": "Error",
    "message": "Invalid Account or not for collection.",
    "object": {
        "error_code": xxx
    }
}