Approve invoice by ID | en.docs.activeplatform

The Approve invoice by ID method is used for approving a postpaid invoice by ID in the platform with a third-party invoice issued to an account of the reseller by a third-party ERP system (see ). This method is used when it is necessary to specify the ID of the required invoice for accounts with several invoices in the platform within the same billing period. If an account has only one invoice in the platform within a billing period, it is possible to use another method without specifying the invoice ID — see Approve invoice.

As a result:

Optionally, you can specify the amount and currency of a third-party invoice, and then:The amount and currency of the approved invoice in the platform and its linked payment do not change.In the Customer Control Panel, for a payment linked to the approved invoice, a message is displayed with the amount and currency of a third-party invoice.If the amount and currency of a third-party invoice differ from the amount of an invoice in the platform and the reseller currency, a customer cannot pay for it from the account balance. Only other payment methods are available, including ones based on payment gateway connectors (see Managing payment gateway connectors). On a payment method page (see Способы оплаты), the specified amount of a third-party invoice is displayed to a customer. The amount of the payment in the platform does not change even after paying.If the amount and currency of a third-party invoice do not differ from the amount of an invoice in the platform and the reseller currency, a customer can pay for it from the account balance or by any other payment method.The specified amount and currency of a third-party invoice can be later retrieved by API from a payment linked to the approved invoice (see Get payment).
Optionally, you can attach to a payment linked to the postpaid invoice in the platform a receipt as a file or a link.
Optionally, you can specify a custom due date for the linked payment. By default, the due date is set according to the account class of the account.
The event handler The Invoice was approved is triggered (see ).
The payment status in the platform changes from Pending billing to Waiting for payment.
For a payment in the platform, a comment is added with the third-party invoice parameters.

After receiving payment for a third-party invoice, it is necessary to approve the payment in the platform by calling the method Complete invoice by ID.

Optionally, a manager can manually approve an invoice for the Postpay model, and approve or cancel its linked payment in the Operator Control Panel:

The platform matches a third-party invoice and invoice for the Postpay model using the start date of the billing period (billing_date).

POST {base_url}/api/v3/resellers/{reseller_id}/invoices/{invoice_id}/approve

Arguments

Name		Parameter Type	Data type	Required/Optional	Description
X-Api-Token		header	string	Required	API token of a manager that performs the operation (see )
Content-Type		header	string	Required	Media type of the request. Specify the following: application/vnd.api+json
Accept		header	string	Required	Supported media types of the answer. Specify the following: application/vnd.api+json
base_url		path	string	Required	ActivePlatform URL
invoice_id		path	integer	Required	ID of the invoice in the platform to approve
account_id		path	integer	Required	Account ID
document_id		form	string	Required	Third-party invoice name
billing_date		form	string	Required	Billing day (YYYY-MM-DD) — the start date of a billing period linked to the invoice
due_date		form	string	Optional	The payment due date (YYYY-MM-DD) — the latest date for completing a payment. On the next day, an unpaid payment gets the Expired status. Specify if it is necessary to use custom payment expiration period that differs from the account class settings (see ). The date must be in the future, including the current date
amount		form	object	Optional	Data about the amount of a third-party invoice issued by an ERP system. Specify if its amount or currency differs from the amount of an invoice in the platform and the reseller currency (see `total` in Get invoice and `currency` in Get downstream reseller )
	total	form	string	Optional	The third-party invoice amount. Must be greater than 0. Required if `amount` is specified
	currency	form	string	Optional	The ISO code of the third-party invoice currency. Can be specified the code of any currency in the platform (see Get list of currency rates ). Required if `amount` is specified
attachment		form	object	Optional	Data about a receipt for a third-party invoice issued by an ERP system. Specify to attach it to a payment in the platform
	type	form	string	Optional	The attachment type. Possible values: file — a file itself. link — a link to a file.
	data	form	string	Optional	Data about a receipt file for a third-party invoice issued by an ERP system: If `type = file`, specify a file in the base64 encoding. If `type = link`, specify a link to a file. Required if `attachment` is specified
	name	form	string	Optional	The receipt file name for notifications to a customer. Required if `attachment` is specified The file name must not contain any slashes `/`.

Response model

The response model is similar to Get invoice.

Errors

Status	Error code	Error text	Comment
400	INVOICE-0001	Required parameters are not provided	Specify all required parameters in the request
	INVOICE-0005	Incorrect specified billing date for the invoice	The specified billing day `billing_date` does not match the specified invoice in the platform
	INVOICE-0007	Only postpaid invoice can be approved	The payment model of the specified invoice is not Postpay, so the invoice cannot be approved (see Get invoice)
	INVOICE-0008	Only closed invoice can be approved	The status of the specified invoice is not Closed, so the invoice cannot be approved (see Get invoice)
	INVOICE-0009	Only non-zero invoice can be approved	The amount of the specified invoice is 0, so the invoice cannot be approved (see Get invoice)
	INVOICE-0013	Parameter "total" cannot be less than 0 or equal to 0	The specified amount of a third-party invoice `total` is less than or equal to 0, so the invoice cannot be approved
	INVOICE-0014	Parameter "currency" contains an unsupported currency by the reseller	Check the supported currency codes in Get list of currency rates
	INVOICE-0015	Parameter "type" contains an unsupported value	Check the specified `type` value
	INVOICE-0016	Payment related to this invoice has been cancelled. Invoice approval is not possible	A manager manually cancelled a linked payment (see ). The invoice cannot be approved or completed
	INVOICE-0018	Parameter "data" contains an unsupported file format	Check the format of a receipt file specified in `data`
	INVOICE-0023	Parameter "due_date" contains an unsupported value	Check the format of `due_date`: YYYY-MM-DD
	INVOICE-0024	Parameter "due_date" cannot be less than the invoice approval date or equal to the invoice approval date	Check the date in `due_date`: it must be in the future, starting from the current date +1 day
422	INVOICE-0003	Unable to approve invoice one more time	The invoice is already approved

Request example

XML

POST /api/v3/resellers/1/invoices/2046/approve
Host: test.activeplatform.com
Content-Type: application/vnd.api+json
X-Api-Token: vY5fwetestK3gJXZH5uHCw
Accept: application/vnd.api+json

JSON

{
    "document_id": "NS2000015",
    "billing_date": "2020-04-01",
    "amount": {
        "total": "123.45",
        "currency": "USD"
    },
    "attachment": {
        "type": "file",
        "data": "data:application/pdf;base64,'SSBob2xkIHRoZSBwb3NpdGlvbiBvZiBhIHFhIGVuZ2luZWVyLiBRQSBlbmdpbmVlciByZXNwb25zaWJpbGl0aWVzIGluY2x1ZGUgZGVzaWduaW5nIGFuZCBpbXBsZW1lbnRpbmcgdGVzdHMsIGRlYnVnZ2luZyBhbmQgZGVmaW5pbmcgY29ycmVjdGl2ZSBhY3Rpb25zLiBJIGFsc28gcmV2aWV3IHN5c3RlbSByZXF1aXJlbWVudHMgYW5kIHRyYWNrIHF1YWxpdHkgYXNzdXJhbmNlIG1ldHJpY3MgKGUuZy4gZGVmZWN0IGRlbnNpdGllcyBhbmQgb3BlbiBkZWZlY3QgY291bnRzLikgVGhlIFFBIHRlY2huaWNpYW4gcm9sZSBwbGF5cyBhbiBpbXBvcnRhbnQgcGFydCBpbiBvdXIgY29tcGFueeKAmXMgcHJvZHVjdCBkZXZlbG9wbWVudCBwcm9jZXNzLg=='",
        "name": "Invoice NS2000015"
    }
}

Response example

JSON

{
    "data": {
        "id": "2046",
        "type": "invoices",
        "attributes": {
            "created_at": "2019-04-18T09:02:01.257560+0300",
            "updated_at": "2019-05-02T06:12:41.990713+0300",
            "document_id": "NS2000015",
            "status": "closed",
            "total": "987.65",
            "account_id": 505,
            "from_date": "2019-04-17",
            "to_date": "2019-05-01",
            "payment_model": "postpay",
            "approved": "true"
        },
        "relationships": {
            "subscriptions": {
                "data": [
                    {
                        "id": "3009839",
                        "type": "subscriptions"
                    }
                ]
            },
            "payments": {
                "data": [
                    {
                        "id": "12201",
                        "type": "payments"
                    }
                ]
            },
            "charges": {
                "data": [
                    {
                        "id": "323740",
                        "type": "charges"
                    }
                ]
            },
            "corrections": {
                "data": []
            }
        }
    }
}