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.
Endpoint
GET https://bo.magnifinance.com/api/v1.1/document?documentId={DocumentId}
Request
Header
| Parameter | Required | Value |
|---|---|---|
| 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. |
note
*These parameters must be 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: "0" |
| Object | DocumentGetOut |
DocumentGetOut Object
| Parameter | Description |
|---|---|
| DocumentNumber | string The document's sequence number in the series. Example value: "FT FT/47" |
| DownloadUrl | string The URL to download the document PDF. Example value: "https://magnifilesdev.s3.eu-west-1.amazonaws.com/..." |
| PaymentStatus | string The document's payment status. There are 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 marked manually as paid. Example value: "1,00" |
| Details | Object All the data about the document. |
Details Object
Document
| Parameter | Description |
|---|---|
| DocumentStatusId | string A letter that indicates the state of the document. Example: "C" for Close, "D" for Draft, "A" for Canceled |
| DocumentStatus | string The status of the document. Only "Closed" documents returns a PDF. Example: "Closed" |
| LoadDateTime | string This will only return data if the document is "Waybill" or a "Delivery note", and indicates the time of the transportation. Example: "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. |
| 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. |
| 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 The document type code: "T" for Invoice/Receipt, "I" for Invoice, "S" for Simplified Invoice, "C" for Credit Note, "D" for Debit Note, "B" for Quote, "P" for Pro-forma Invoice, "Z" for Purchase Order, "W" for Waybill, "Y" for Delivery Note. See the document types. Example value: "T" |
| Serie | string The document series (sequence) in which the document was created. Series have a unique name per document type. 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" |
| Id | 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 already 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. |
| PurchaseOrder | string A description of the purchase order that is used to formalize a purchase. Example value: "This is a Purchase Order field" |
LoadAddress / DestinationAddress
| Parameter | Description |
|---|---|
| AddressDetail | string The address of the starting/destination point of the "Waybill" or "Delivery note". Example value: "Av. Sidonio Pais, No 2, 2 Esq. A" |
| City | string The city of the starting/destination point of the "Waybill" or "Delivery note". Example value: "Lisboa" |
| PostalCode | string The postal-code of the starting/destination point of the "Waybill" or "Delivery note". Example value: "1050-215" |
| CountryCode | string The country of the starting/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" |
Lines (APIInvoicingProduct)
| Parameter | Description |
|---|---|
| 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" |
Receiver
| Parameter | Description |
|---|---|
| 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. Example: "PT" |
| PhoneNumber | string Receiver company phone number. Example: "912345678" |
| CountryName | string Name of the country of the company receiver. Example value: "Portugal" |
| LegalName | string Receiver company legal name. Example value: "Magni EShop Partner" |
string The email of the company receiver. Example value: "email@example.com" | |
| IBAN | string Company receiver international bank account number. Example value: "PT50002700000001234567833" |
Totals
| Parameter | Description |
|---|---|
| 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" |
Error Response
| Parameter | Description |
|---|---|
| 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" |
| ElementNumber | int Which element failed when the field repeats (for example the line number in Lines); 0 otherwise. Example value: 0 |
| 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 Samples
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 requestOptions = {
method: 'GET',
headers: myHeaders,
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));
Node.js (axios)
var axios = require('axios');
var config = {
method: 'get',
url: 'https://bo.magnifinance.com/api/v1.1/document?documentId={DOCUMENTID}',
headers: {
'email': 'XXX@example.com',
'token': 'XXX'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python (requests)
import requests
url = "https://bo.magnifinance.com/api/v1.1/document"
headers = {
"email": "XXX@example.com",
"token": "XXX"
}
params = {
"documentId": "{DOCUMENTID}"
}
response = requests.get(url, headers=headers, params=params)
print(response.json())
PHP (cURL)
<?php
$documentId = "{DOCUMENTID}";
$url = "https://bo.magnifinance.com/api/v1.1/document?documentId=" . $documentId;
$headers = [
"email: XXX@example.com",
"token: XXX"
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
C# (HttpClient)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("email", "XXX@example.com");
client.DefaultRequestHeaders.Add("token", "XXX");
var documentId = "{DOCUMENTID}";
var response = await client.GetAsync(
$"https://bo.magnifinance.com/api/v1.1/document?documentId={documentId}"
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Java (HttpClient)
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
HttpClient client = HttpClient.newHttpClient();
String documentId = "{DOCUMENTID}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://bo.magnifinance.com/api/v1.1/document?documentId=" + documentId))
.header("email", "XXX@example.com")
.header("token", "XXX")
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
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&...",
"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": "Servicos 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
}