API 2.1
Create a Document
Create a document according to the input parameters. This method supports all invoice group type documents (invoice, invoice/receipt, simplified invoice, credit note, debit note). After successful processing, the DocumentId is returned in the result.
POST https://bo.magnifinance.com/api/v1.1/document
Is it IPPN?
Sample Body
{
"IsToClose" : "",
"SendTo" : "",
"Client" :
{
"NIF": "",
"Name":"",
"Address":"",
"City":"",
"PostCode":"",
"CountryCode":"",
"PhoneNumber":"",
"CountryName":"",
"LegalName":"",
"Email":"",
"IBAN":""
},
"Document" :
{
"Type": "",
"Serie": "",
"Id": "",
"Date": "",
"DueDate": "",
"Description": "",
"DocumentReference": "",
"TaxExemptionReasonCode": "",
"Currency": "",
"EuroRate": "",
"Retention": "",
"ExternalId": "",
"Lines" :
[
{
"Code": "",
"Description": "",
"UnitPrice": "",
"Quantity": "",
"Unit": "",
"Type": "",
"TaxValue": "",
"ProductDiscount": "",
"CostCenter": ""
}
]
}
}
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 | string(50) The token of the subscription in which the document will be generated. |
*These parameters must be an HTTP headers within the request.
Body
| Parameter | Required | Description |
|---|---|---|
| IsToClose | required | boolean Should the document be closed (true) in which case it cannot be later changed and a PDF and document number are generated or should the document be created as a draft (false) in which case no PDF or document number are generated. Example value: "true" |
| SendTo | optional | string Upon closing the document an email can be sent with a notification of the document to an email address. Example value: "info@magnifinance.com" |
Client
| Parameter | Required | Description |
|---|---|---|
| Name | required | string(75) Client familiar name. Example value: "MagniFinance" |
| NIF | required | string(20) Client Tax ID. The tax id must be valid. Example value: "166737755" |
| Address | optional | string(200) Client address. Example value: "Av. Sidónio Pais, Nº 2, 2 Esq. A 1050 - 215" |
| City | optional | string(50) Client city. Example value: "Lisboa" |
| PostCode | optional | string(50) Client post code. The post code must be valid. Example value: "1050-214" |
| CountryCode | required | string(2) Client country (To consult the code list for each country, access the link: ISO 3166-1 alpha-2 "PT" |
| CountryName | optional | string Name of the country. Example value: "Portugal" |
| PhoneNumber | optional | string(50) Client phone number. Example value "999999999" |
| Legal Name | optional | string(500) Client legal name, client’s name on invoices, whether not informed, ‘Name’ will be considered. Example value: "MagniFin lda" |
| optional | string(255) Client email address. Example value: "info@magnifinance.com" | |
| IBAN | optional | string(300) Client international bank account number. Example value: "PT50002700000001234567833" |
Document
| Parameter | Required | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Type | required | string(1) Type of the document to be created. Possible types are “T” for Fatura/Recibo, “I” for Fatura, “S” for Fatura Simplificada, “C” for credit note and “D” for Debit Note. Example value:"T" | |||||||||||||||||||||||||||
| Serie | optional | string(30) Document series (sequence) in which the document will be created. The series have a unique name per document type. If not sent, the default series for that type of document in that subscription will be used. 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" | |||||||||||||||||||||||||||
| Id | optional | 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" | |||||||||||||||||||||||||||
| Date | required | date Document date. This date must be posterior to the previously closed document date for this series. Format: yyyy-mm-dd. Example value: "2022-03-20" | |||||||||||||||||||||||||||
| DueDate | required | date Date in which payment is due. Must be posterior to Date. Format: yyyy-mm-dd. Example value: "2022-03-20" | |||||||||||||||||||||||||||
| Description | optional | string(300) Description to be included in the document.Should have more than two characters. Example value: "Here you put the description" | |||||||||||||||||||||||||||
| DocumentReference | optional | string(50) The document reference is the document number of the document that document that will be created is based on. This field is mandatory for credit or debit notes. Example value: "FT FT/40420" | |||||||||||||||||||||||||||
| TaxExemptionReasonCode | optional | string(3) Required if there is at least one line with 0% tax. Justifies why 0% tax was used. To access the complete list, click here. Are the values of the column: code. Example value: "M01" | |||||||||||||||||||||||||||
| Currency | optional | string(3) Currency to be used additionally to EUR. (ISO 4217) Example value: "BRL" | |||||||||||||||||||||||||||
| EuroRate | optional | decimal Number by which to multiply the amounts to get then alternative currency amount. Example value: "1" | |||||||||||||||||||||||||||
| Retention | optional | decimal Percentage of the document total amount that will be retained as tax with this operation. Example value: "8" | |||||||||||||||||||||||||||
| ExternalId | optional | string(50) Your identifier for this document. Used to prevent document duplication. Uniqueness is verified in combination with the client information. Example value: "test51519125" | |||||||||||||||||||||||||||
| PurchaseOrder | optional | string(50)A purchase order is used to formalize a purchase. Example value: "This is a Purchase Order field" | |||||||||||||||||||||||||||
| Lines | required | (Object) List of APIInvoicingProduct This is the list of products that will appear in the document. | |||||||||||||||||||||||||||
|
Obs: What you should do when you does not have the client's NIF (Tax Id)? If a customer does not wish to provide their personal tax identifier for the invoice, generic "End Consumer” information can be used by providing the NIF (Tax Id): 999 999 990. The customer’s name can also be added if the customer requires their name on the document and can be used to identify the customer without NIF.
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 | DocumentCreateOut | ||||||||
|
|||||||||
| ErrorValue | MagniEnum | ||||||||
|
|||||||||
| string Text that explains the error found. Example value: "ValidationError" | |||||||||
| ValidationErrors | List of ValidationError | ||||||||
|
|||||||||
| 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 --location --request POST 'https://bo.magnifinance.com/api/v1.1/document' \
--header 'email: XXX@example.com ' \
--header 'token: XXX' \
--header 'Content-Type: application/json' \
--data-raw '{
"IsToClose" : "",
"SendTo" : "",
"Client" : {
"NIF": "",
"Name":"",
"Address":"",
"City":"",
"PostCode":"",
"CountryCode":"",
"PhoneNumber":"",
"CountryName":"",
"LegalName":"",
"Email":"",
"IBAN":""
},
"Document" : {
"Type": "",
"Date": "",
"DueDate": "",
"Description": "",
"Serie": "",
"TaxExemptionReasonCode": "",
"Currency": "",
"EuroRate": "",
"Retention": "",
"Lines" : [
{
"Code": "",
"Description": "",
"UnitPrice": "",
"Quantity": "",
"Unit": "",
"Type": "",
"TaxValue": "",
"ProductDiscount": ""
},
{
"Code": "",
"Description": "",
"UnitPrice": "",
"Quantity": "",
"Unit": "",
"Type": "",
"TaxValue": "",
"ProductDiscount": "",
"CostCenter": ""
}
]
}
}'
var myHeaders = new Headers();
myHeaders.append("email", "XXX@example.com");
myHeaders.append("token", "XXX");
myHeaders.append("Content-Type", "application/json");
var raw = JSON.stringify({
"IsToClose": "",
"SendTo": "",
"Client": {
"NIF": "",
"Name": "",
"Address": "",
"City": "",
"PostCode": "",
"CountryCode": "",
"PhoneNumber": "",
"CountryName": "",
"LegalName": "",
"Email": "",
"IBAN": ""
},
"Document": {
"Type": "",
"Date": "",
"DueDate": "",
"Description": "",
"Serie": "",
"TaxExemptionReasonCode": "",
"Currency": "",
"EuroRate": "",
"Retention": "",
"Lines": [
{
"Code": "",
"Description": "",
"UnitPrice": "",
"Quantity": "",
"Unit": "",
"Type": "",
"TaxValue": "",
"ProductDiscount": ""
},
{
"Code": "",
"Description": "",
"UnitPrice": "",
"Quantity": "",
"Unit": "",
"Type": "",
"TaxValue": "",
"ProductDiscount": "",
"CostCenter": ""
}
]
}
});
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("https://bo.magnifinance.com/api/v1.1/document", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
var axios = require('axios');
var data = JSON.stringify({
"IsToClose": "",
"SendTo": "",
"Client": {
"NIF": "",
"Name": "",
"Address": "",
"City": "",
"PostCode": "",
"CountryCode": "",
"PhoneNumber": "",
"CountryName": "",
"LegalName": "",
"Email": "",
"IBAN": ""
},
"Document": {
"Type": "",
"Date": "",
"DueDate": "",
"Description": "",
"Serie": "",
"TaxExemptionReasonCode": "",
"Currency": "",
"EuroRate": "",
"Retention": "",
"Lines": [
{
"Code": "",
"Description": "",
"UnitPrice": "",
"Quantity": "",
"Unit": "",
"Type": "",
"TaxValue": "",
"ProductDiscount": ""
},
{
"Code": "",
"Description": "",
"UnitPrice": "",
"Quantity": "",
"Unit": "",
"Type": "",
"TaxValue": "",
"ProductDiscount": "",
"CostCenter": ""
}
]
}
});
var config = {
method: 'post',
url: 'https://bo.magnifinance.com/api/v1.1/document',
headers: {
'email': 'XXX@example.com',
'token': 'XXX',
'Content-Type': 'application/json'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Example Response
Success
{
"RequestId": "98c3bc62-911d-4f14-a5f4-d610c66e8b8b",
"Object": {
"DocumentId": 67195,
"ErrorMessage": null
},
"Type": 0,
"ErrorValue": null,
"ErrorHumanReadable": null,
"ValidationErrors": null,
"IsSuccess": true,
"IsError": false
}
- A: It serves to indicate the id of a document that you want to edit or to Get the PDF of a document passing the Id as a parameter of the get document method. They can only edit documents that are not in the closed state. For document creation, you do not need to fill in the id.
Error
{
"RequestId": "211b32b1-701a-4944-9292-8f8034a3b3a7",
"Object": null,
"Type": 1,
"ErrorValue": {
"Value": 14,
"Name": "SaveFailed"
},
"ErrorHumanReadable": "ValidationError",
"ValidationErrors": [
{
"Type": "DocumentIsADuplicate",
"ElementNumber": 67204,
"Field": "DocumentDetailExternalId",
"Detail": "Duplicate Document"
}
],
"IsSuccess": false,
"IsError": true
}
IPPN
If you are invoicing on behalf of your partners (other companies) through our IPPN service (Invoicing Platform for Partners Network) please, pay attention to the following information:
Type of documents allowed:
The default allowed document types on the API in the IPPN service are Invoice/Receipt (T) and Credit
Note (C). Other document types are disabled to prevent incorrect documents
creation that may cause issues to partner tax compliance. Although other
document types are restricted, they can be made available if needed.
How to access tokens to invoicing on behalf of partners:
An IPPN account is assigned with a unique identifier called the partnertoken, most
commonly assign with the company’s name. This partner token also specifies the
document series which is automatically set when creating a specific document
type. The default values of the document Type and Series for IPPN users are:
See more about IPPN in this section
FAQ
-
1. What is the Country Code field? What do I fill?
- A: The CountryCode field is a two-character ISO 3166-1 alpha-2 code corresponding to the country of the invoice customer. For example, the CountryCode of the country Portugal is "PT". From the country Germany is "DE", etc. To access the complete list, click here.
-
2. What is the use of the ExternalId field?
- A: It is used to prevent duplicate documents from being created. If a document have an ExternalId and you try to make the same request twice passing this ExternalId, we will be able to know whether or not this document is already registered on our platform, and we will return an error if the same already id exists.
-
3. Could you better explain the function of the TaxExemptionReasonCode field to me?
A: The TaxExemptionReasonCode field indicates the IVA exemption reason. If any document line has VAT 0 you should send this field in your request. Possible values are listed in our documentation, example: M01, M99, etc. To access the complete list, click here. Are the values of the column: code.
-
4. What value should I fill in the TaxValue field?
A: The TaxValue field indicates the IVA of each item or line. The values created by default correspond to those in force in Portugal: 6%, 13%, 21%, 23%.
-
5."I filled the email in the SendTo field, but I didn't receive the email after the document creation request".
A: Making sure you use the correct email, the PDF is only sent by email when the document is closed, make sure the "IsToClose" field passing as true.
-
6."Can I save a document as a draft to update later?".
A: To save a document as a draft without closing it, you can set the value of the "IsToClose" parameter to "false". After doing so, you will receive a document ID that you can use to update or close the document later. To update the draft document, simply call the "document create" method and pass the ID of the draft document as a parameter. Alternatively, you can close the document by passing the same ID and setting the "IsToClose" parameter to "true".
Do you still have any doubts? We are here to help, contact us via the link: Contato