API 2.1

Get a Document

Finalizes and retrieves a document by allocating a DocumentNumber and DownloadUrl. After DocumentCreate is successfully completed, DocumentGet should wait at least 10 seconds before it is called.

GET https://bo.magnifinance.com/api/v1.1/document?documentId={DocumentId}

Request

Header

Parameter	Required	Value
Email	required	string(50) The API user with specific permission to create documents and get information about your own documents into a company Example: api@magnifinance.com
Token	required	The token of the subscription in which the document will be generated.

*These parameters must be an HTTP headers within the request.

Query

Parameter	Required	Description
DocumentId	required	int Id of the document that you want to retrieve. Example value: "67053" In the REST API you should request as a query string parameter in the URL. Example: ?documentId=47257

Response

Parameter

Description

Type

int 0 = Success; 1 = Error; “Success” or “Error”. Object will be returned on Success; ErrorValue, ErrorHumanReadable, ValidationErrors will be returned on Error. Example value: Example value: "0"

Object

DocumentGetOut

DocumentNumber	string The document’s sequence number in the series. Example value: "FT FT/47"
DownloadUrl	string The document’s sequence number in the series. Example value: "https://magnifilesdev.s3.eu-west-1.amazonaws.com/18471/2022/d26b0727-fc66-4353-9047-eae50c3a896b.pdf?X-Amz-Expires=7200&response-cache-control=No-cache&response-content-disposition=attachment%3B%20filename%3DFTFT_47_companySprint47APItest_2022-04-04_BRL0%252c00.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ3INGX4GEGE7JUSA/20220405/eu-west-1/s3/aws4_request&X-Amz-Date=20220405T171024Z&X-Amz-SignedHeaders=host&X-Amz-Signature=786256202dc32a0be27144ef63db98f6f35ed45fc5d9a06545d14f03edc07495"
PaymentStatus	string The document’s payment status. There is three possible values: NoPayment, Incomplete, Complete. Example value: "Incomplete"
ErrorMessage	string Unprocessed error message.
TotalAmount	string The total amount of the document. Example value: "20,00"
UnpaidAmount	string The total amount of the document that is missing to be paid. It will be zero if the company did a reconciliation or mark manually as a paid. Example value: "1,00"
Details	Object All the date about the document.

Document

Object All the about the document.

DocumentStatusId

string A letter that indicates the state of the document. Example: "C" for Close, "D" for Draft, "A" for Canceled"C"

DocumentStatus

string The status of the document. Only "Closed" documents returns a PDF. "Closed"

LoadDateTime

string This will only return data if the document is "Waybill" or a "Delivery note", and indicates the time of the transportation. "2023-03-09T00:00:00"

LoadAddress

(Object) This object will only return data if the document is "Waybill" or a "Delivery note". It will return the complete address of starting point i.e the place of loading.

AddressDetail	string The address of the starting point of the "Waybill" or "Delivery note". Example value: "Av. Sidónio Pais, Nº 2, 2 Esq. A"
City	string The city of the starting point of the "Waybill" or "Delivery note". Example value: "Lisboa"
PostalCode	string The postal-code of the starting point of the "Waybill" or "Delivery note". Example value: "1050-215"
CountryCode	string The country of the starting point of the "Waybill" or "Delivery note". (To consult the code list for each country, access the link: ISO 3166-1 alpha-2. Example value: "PT"

DestinationAddress

(Object) This object will only return data if the document is "Waybill" or a "Delivery note". It will return the complete address of the destination point i.e the place of unloading.

AddressDetail	string The address of the destination point of the "Waybill" or "Delivery note". Example value: "Av. Sidónio Pais, Nº 2, 2 Esq. A"
City	string The city of the destination point of the "Waybill" or "Delivery note". Example value: "Lisboa"
PostalCode	string The postal-code of the destination point of the "Waybill" or "Delivery note". Example value: "1050-215"
CountryCode	string The country of the destination point of the "Waybill" or "Delivery note". (To consult the code list for each country, access the link: ISO 3166-1 alpha-2. Example value: "PT"

VehicleLicence

string(30) The license plate of the vehicle using the "Waybill" or "Delivery note". Example value: "AA 16 AA"

TotalCredit

string The total amount payable if applicable. Example value: "0.00"

TotalDebit

string The total amount to be received if applicable. Example value: "1.00"

Date

date Document date. Format: yyyy-mm-dd. Example value: "2022-03-20"

DueDate

date Document Due date. Format: yyyy-mm-dd. Example value: "2022-03-20"

Description

string General description that is included in the document Example value: "Your description"

Type

string Type of the document that was created. Example: “T” for Invoice/Receipt, “I” for Invoice, “S” for Simplified Invoice,“C” for Credit Note, “D” for Debit Note, "B" for budget,"Z" for purchase order, "W" for Waybill, "Y" for Delivery Note, "P" for Pro-forma.

Serie

string The document series (sequence) in which the document was created. Series have a unique name per document type. Basically the series corresponds to the name of an existing series associated with the type of indication in the Type field, document within the Document structure. You can view a list of series for each type of document following the path in the system: Settings -> General -> Document series Example value: "FR"

int The id of the document that you want to update. The parameter "id" can be passed when you want to update some information in a document alredy created in draft or you want to close the document. Example value: 56232

TaxExemptionReasonCode

string Return a tax exemption reason code presented on this list. This justifies when there is at least one line with 0% tax in the document. Example value: "M01"

DocumentReference

string The document reference is the document number of the document that document that was created is based on. Example value: "FT FT/40420"

Currency

string The Currency of the document based on the Code: (ISO 4217) Example value: "BRL"

Retention

decimal Percentage of the document total amount that was retained as tax with the operation. Example value: "8"

EuroRate

decimal Number by which to multiply the amounts to get then alternative currency amount. Example value: "1"

ExternalId

string An id that was defined by you to identify the document and to prevent document duplications. Example value: "test51519125"

Lines

(Object) List of APIInvoicingProduct Object with all the lines (products or services) that appear in the document.

Code	string Identifies the product. Example value: "PRODUCT CODE 123"
Description	string Description of the product. Example value: "My Product Description"
UnitPrice	decimal Amount per unit. Example value: "2.45"
Quantity	decimal Number of units. Example value: "1"
Unit	string Unit name. Example value: "KG"
Type	string “S” for services, “P” for product. Example value: "P"
TaxValue	decimal Percentage of tax. Example value: "23"
ProductDiscount	decimal Percentage of discount. Example value: "0"
CostCenter	string Cost center of the product line. Example value: "Espanha"

PurchaseOrder

stringA description of the purchase order that is used to formalize a purchase. Example value: "This is a Purchase Order field"

Receiver

Object All the data about the company receiver of the document.

taxId	int Tax id of the company receiver. Example value: "599138645"
Name	string The commercial name of the company receiver. Example: "MagniFinance"
Address	string The address of the company receiver. Example: "Rua das Barreiras"
City	string The city of the company receiver. Example: "Lisboa"
PostCode	string The postal code of the company receiver. Example: "1000-000"
CountryCode	string Receiver company country code in ISO 3166-1 alpha-2 "PT"
PhoneNumber	string Receiver company phone number. Example: "912345678"
CountryName	string Name of the country of the company receiver. Example value: "Portugal"
CompanyLegalName	string Receiver company legal name. Example value: "Magni EShop Partner"
Email	string The email of the company receiver. Example value: "email@example.com"
IBAN	string Company receiver international bank account number. Example value: "PT50002700000001234567833"

Totals

Object All the data about totals of the document.

Amount	decimal The total amount of the document as number data type. Example value: 20.22
AmountText	string The total amount of the document as text data type, separated by commas. Example value: "20,22"
WithoutTax	decimal The total amount of the document without Tax as number data type. Example value: 20.22
WithoutTaxText	string The total amount of the document without Tax as text data type separated by commas. Example value: "20,22"
Tax	decimal Percentage of tax as number data type. Example value: 23.00
TaxText	string Percentage of tax as text data type separated by commas. Example value: "23,00"
Discount	decimal The total of discount of the document as percentage as number data type. Example value: 20.22
DiscountText	string The total of discount of the document as percentage as text data type separated by commas. Example value: "20,22"
Retention	decimal The total of Retention rate of the document as percentage as number data type. Example value: 20.22
RetentionText	string The total of Retention rate of the document as percentage as text data type separated by commas. Example value: "20,22"
AmountBeforeDiscountAndTax	decimal The total amount before discount and tax of document as number data type. Example value: 1.0000000000
AmountBeforeDiscountAndTaxText	string The total amount before discount and tax of document as text data type separated by commas. Example value: "1,00"
TotalAmountWithExchangeRate	decimal The total amount with exchange rate will return different of zero when you have a currency different of "Euro". This data returns as number data type. Example value: 0.00
TotalAmountWithExchangeRateText	string The total amount with exchange rate will return different of zero when you have a currency different of "Euro". This data returns as text data type separated by commas. Example value: 0.00
TotalCreditAmount	decimal The total amount payable if applicable. Example value: 0.00
TotalCreditAmountText	string The total amount payable if applicable. This data returns as text data type separated by commas. Example value: "0.00"
TotalDebitAmount	decimal The total amount to be received if applicable. Example value: 0.00
TotalDebitAmountText	string The total amount to be received if applicable. This data returns as text data type separated by commas. Example value: "0.00"

Type

ErrorValue

MagniEnum

Value	int Identifies the error with a number. To identify the types of errors in more detail, click here Example value: "14"
Name	string Identifies the error with a token. Example value: "SaveFailed"

ErrorHumanReadable

string Text that explains the error found. Example value: "ValidationError"

ValidationErrors

List of ValidationError

Type	string Identifies the error with a token. Example value: "DocumentIsADuplicate"
Field	string Name of the field in which validation failed. Example value: "DocumentDetailExternalId"
Value	string Value which failed validation. Example value: "6"
ElementNumber	string Identifies index of the field in which validation failed. Example value: "67204"
Detail	string detailed error explanation. Example value: "Duplicate Document"

IsError

boolean Whether the request failed or not. Example value: "false"

IsSuccess

boolean Whether the request succeeded or not. Example value: "true"

Request Sample

Below you can check some examples of the REST request in some technologies.

cURL


                        curl --location --request GET 'https://bo.magnifinance.com/api/v1.1/document?documentId={DOCUMENTID}' \
                        --header 'email: XXX@example.com' \
                        --header 'token: XXX' \

Javascript (fetch)


                        var myHeaders = new Headers();
                        myHeaders.append("email", "XXX@example.com");
                        myHeaders.append("token", "XXX");

                        var raw = "";

                        var requestOptions = {
                        method: 'GET',
                        headers: myHeaders,
                        body: raw,
                        redirect: 'follow'
                        };

                        fetch("https://bo.magnifinance.com/api/v1.1/document?documentId={DOCUMENTID}", requestOptions)
                        .then(response => response.text())
                        .then(result => console.log(result))
                        .catch(error => console.log('error', error));

NodeJs (axios)


                        var axios = require('axios');
                        var data = '';

                        var config = {
                        method: 'get',
                        url: 'https://bo.magnifinance.com/api/v1.1/document?documentId={DOCUMENTID}',
                        headers: {
                        'email': 'XXX@example.com',
                        'token': 'XXX',
                        },
                        data : data
                        };

                        axios(config)
                        .then(function (response) {
                        console.log(JSON.stringify(response.data));
                        })
                        .catch(function (error) {
                        console.log(error);
                        });

Example Response

Success


                       {
    "RequestId": "cd8cfa73-81f5-4a51-bb0d-059c138d3102",
    "Object": {
        "DocumentNumber": "FR FR/5",
        "DownloadUrl": "https://magniurlexample/9379/2023/cdc7b523-242b-4c57-aeca-463f756eb57d.pdf?X-Amz-Expires=3600&response-cache-control=No-cache&response-content-disposition=attachment%3B%20filename%3DFRFR_5_XXXo_2023-03-09_EUR1%252c23.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ3INGX4GEGE7JUSA/20230309/eu-west-1/s3/aws4_request&X-Amz-Date=20230309T144144Z&X-Amz-SignedHeaders=host&X-Amz-Signature=1629a916abdf0fe578eab25370d1a1b33be35bb4714070edde0391b35a2d7fad",
        "PaymentStatus": null,
        "ErrorMessage": null,
        "TotalAmount": null,
        "UnpaidAmount": null,
        "Details": {
            "Document": {
                "DocumentStatusId": "C",
                "DocumentStatus": "Closed",
                "LoadDateTime": null,
                "LoadAddress": null,
                "DestinationAddress": null,
                "VehicleLicence": null,
                "TotalCredit": 0.00,
                "TotalDebit": 0.0,
                "Date": "2023-03-09T00:00:00",
                "DueDate": "2023-03-09T00:00:00",
                "Description": "xxxx",
                "Type": "T",
                "Serie": "FR",
                "Id": 80622,
                "TaxExemptionReasonCode": null,
                "DocumentReference": "",
                "Currency": "EUR",
                "Retention": 0.00,
                "EuroRate": null,
                "ExternalId": null,
                "Lines": [
                    {
                        "Code": "999",
                        "Description": "Serviços gerais",
                        "UnitPrice": 1.00000000,
                        "Quantity": 1.00,
                        "Unit": "Un.",
                        "Type": "S",
                        "TaxValue": 23.00,
                        "ProductDiscount": 0.0000,
                        "CostCenter": "General CCC"
                    }
                ],
                "PurchaseOrder": ""
            },
            "Receiver": {
                "TaxId": "107903857",
                "Name": "cliente teste pedro",
                "Address": "123",
                "City": "lx",
                "PostCode": "1111-111",
                "CountryCode": "PT",
                "PhoneNumber": "999999999",
                "CountryName": "Portugal",
                "LegalName": "empresa teste pedro",
                "Email": null,
                "IBAN": null
            },
            "Totals": {
                "Amount": 1.230000000000,
                "AmountText": "1,23",
                "WithoutTax": 1.0000000000,
                "WithoutTaxText": "1,00",
                "Tax": 0.230000000000,
                "TaxText": "0,23",
                "Discount": 0.0,
                "DiscountText": "0,00",
                "Retention": 0.0,
                "RetentionText": "0,00",
                "AmountBeforeDiscountAndTax": 1.0000000000,
                "AmountBeforeDiscountAndTaxText": "1,00",
                "TotalAmountWithExchangeRate": 0.0,
                "TotalAmountWithExchangeRateText": "0,00",
                "TotalCreditAmount": 1.0000000000,
                "TotalCreditAmountText": "1,00",
                "TotalDebitAmount": 0.0,
                "TotalDebitAmountText": "0,00"
            }
        }
    },
    "Type": 0,
    "ErrorValue": null,
    "ErrorHumanReadable": null,
    "ValidationErrors": null,
    "IsSuccess": true,
    "IsError": false
}

Error


{
"RequestId": "dc5983e0-a93c-4690-a2c4-4379978382fd",
"Object": null,
"Type": 1,
"ErrorValue": {
"Value": 6,
"Name": "ElementDoesNotExist"
},
"ErrorHumanReadable": null,
"ValidationErrors": null,
"IsSuccess": false,
"IsError": true
}

REST API

SOAP API

API 2.1

Get a Document

Request

Header

Query

Response

Request Sample

cURL

Javascript (fetch)

NodeJs (axios)

Example Response

Success

Error