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

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.

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 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. 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"`
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

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"`
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 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
}

Endpoint​

Request​

Header​

Query​

Response​

DocumentGetOut Object​

Details Object​

Document​

LoadAddress / DestinationAddress​

Lines (APIInvoicingProduct)​

Receiver​

Totals​

Error Response​

Request Samples​

cURL​

JavaScript (fetch)​

Node.js (axios)​

Python (requests)​

PHP (cURL)​

C# (HttpClient)​

Java (HttpClient)​

Example Response​

Success​

Error​