API 2.0 | Go to the latest documentation arrow_forward
Create a Document
Create a document according to the input parameters. This method supports all invoice group type documents (invoice, invoice/receipt, simplefied invoice, credit note, debit note). After successful processing, the DocumentId is returned in the result.
POST https://bo.magnifinance.com/MagniAPI/Invoicing.asmx
Is it IPPN?
Sample Body
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://MagniAPI/Invoicing/" >
<soapenv:Header / >
<soapenv:Body >
<inv:DocumentCreate>
<inv:Authentication>
<inv:Email> </inv:Email>
<inv:Token> </inv:Token>
</inv:Authentication>
<inv:Client>
<inv:NIF> </inv:NIF>
<inv:Name> </inv:Name>
<inv:Address> </inv:Address>
<inv:City> </inv:City>
<inv:PostCode> </inv:PostCode>
<inv:CountryCode> </inv:CountryCode>
<inv:PhoneNumber> </inv:PhoneNumber>
<inv:CountryName> </inv:CountryName>
<inv:LegalName> </inv:LegalName>
<inv:Email> </inv:Email>
<inv:IBAN> </inv:IBAN>
</inv:Client>
<inv:Document>
<inv:Date> </inv:Date>
<inv:DueDate> </inv:DueDate>
<inv:Description> </inv:Description>
<inv:Type> </inv:Type>
<inv:Serie> </inv:Serie>
<inv:Id> </inv:Id>
<inv:TaxExemptionReasonCode> </inv:TaxExemptionReasonCode>
<inv:DocumentReference> </inv:DocumentReference>
<inv:Currency> </inv:Currency>
<inv:Retention> </inv:Retention>
<inv:EuroRate> </inv:EuroRate>
<inv:ExternalId> </inv:ExternalId>
<inv:PurchaseOrder> </inv:PurchaseOrder>
<inv:Lines>
<inv:APIInvoicingProduct>
<inv:Code> </inv:Code>
<inv:Description> </inv:Description>
<inv:UnitPrice> </inv:UnitPrice>
<inv:Quantity> </inv:Quantity>
<inv:Unit> </inv:Unit>
<inv:Type> </inv:Type>
<inv:TaxValue> </inv:TaxValue>
<inv:ProductDiscount> </inv:ProductDiscount>
<inv:CostCenter> </inv:CostCenter>
</inv:APIInvoicingProduct>
<inv:APIInvoicingProduct>
<inv:Code> </inv:Code>
<inv:Description> </inv:Description>
<inv:UnitPrice> </inv:UnitPrice>
<inv:Quantity> </inv:Quantity>
<inv:Unit> </inv:Unit>
<inv:Type> </inv:Type>
<inv:TaxValue> </inv:TaxValue>
<inv:ProductDiscount> </inv:ProductDiscount>
<inv:CostCenter> </inv:CostCenter>
</inv:APIInvoicingProduct>
</inv:Lines>
</inv:Document>
<inv:IsToClose> </inv:IsToClose>
<inv:SendTo> </inv:SendTo>
</inv:DocumentCreate>
</soapenv:Body>
</soapenv:Envelope>
Request
Header
| Parameter | Required | value |
|---|---|---|
| Content-Type | required | text/xml |
Body
Authentication
| Parameter | Required | Description |
|---|---|---|
| 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. |
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" |
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" | |||||||||||||||||||||||||||
| 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 Example value: "Here you put the description" | |||||||||||||||||||||||||||
| Serie | optional | string(30) Document series (sequence) in which the document will be created. 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" | |||||||||||||||||||||||||||
| 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" | |||||||||||||||||||||||||||
| 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. | |||||||||||||||||||||||||||
|
| 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" |
Response
| Parameter | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Type | string Description to inform if the request was a success or error. Example value: "Success" | ||||||||
| Object | DocumentCreateOut | ||||||||
|
|||||||||
| ErrorValue | MagniEnum | ||||||||
|
|||||||||
| string Text that explains the error found. Example value: "ValidationError" | |||||||||
| ValidationErrors | List of ValidationError | ||||||||
|
Request Sample
Below you can see a few examples of the SOAP request in some technologies.
curl --location --request POST 'https://bo.magnifinance.com/MagniAPI/Invoicing.asmx' \
--header 'Content-Type: application/soap+xml; charset=utf-8' \
--data-raw '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://MagniAPI/Invoicing/">
<soapenv:Header/>
<soapenv:Body>
<inv:DocumentCreate>
<inv:Authentication>
<inv:Email></inv:Email>
<inv:Token></inv:Token>
</inv:Authentication>
<inv:Client>
<inv:NIF></inv:NIF>
<inv:Name></inv:Name>
<inv:Address></inv:Address>
<inv:City></inv:City>
<inv:PostCode></inv:PostCode>
<inv:CountryCode></inv:CountryCode>
<inv:PhoneNumber></inv:PhoneNumber>
<inv:CountryName></inv:CountryName>
<inv:LegalName></inv:LegalName>
<inv:Email></inv:Email>
<inv:IBAN></inv:IBAN>
</inv:Client>
<inv:Document>
<inv:Date></inv:Date>
<inv:DueDate></inv:DueDate>
<inv:Description></inv:Description>
<inv:Type></inv:Type>
<inv:Serie></inv:Serie>
<inv:TaxExemptionReasonCode></inv:TaxExemptionReasonCode>
<inv:DocumentReference></inv:DocumentReference>
<inv:Currency></inv:Currency>
<inv:Retention></inv:Retention>
<inv:EuroRate></inv:EuroRate>
<inv:ExternalId></inv:ExternalId>
<inv:Lines>
<inv:APIInvoicingProduct>
<inv:Code></inv:Code>
<inv:Description></inv:Description>
<inv:UnitPrice></inv:UnitPrice>
<inv:Quantity></inv:Quantity>
<inv:Unit></inv:Unit>
<inv:Type></inv:Type>
<inv:TaxValue></inv:TaxValue>
<inv:ProductDiscount></inv:ProductDiscount>
<inv:CostCenter></inv:CostCenter>
</inv:APIInvoicingProduct>
<inv:APIInvoicingProduct>
<inv:Code></inv:Code>
<inv:Description></inv:Description>
<inv:UnitPrice></inv:UnitPrice>
<inv:Quantity></inv:Quantity>
<inv:Unit></inv:Unit>
<inv:Type></inv:Type>
<inv:TaxValue></inv:TaxValue>
<inv:ProductDiscount></inv:ProductDiscount>
<inv:CostCenter></inv:CostCenter>
</inv:APIInvoicingProduct>
</inv:Lines>
</inv:Document>
<inv:IsToClose></inv:IsToClose>
<inv:SendTo></inv:SendTo>
</inv:DocumentCreate>
</soapenv:Body>
</soapenv:Envelope>'
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/soap+xml; charset=utf-8");
var raw = "<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:inv=\"http://MagniAPI/Invoicing/\">\r\n <soapenv:Header/>\r\n <soapenv:Body>\r\n <inv:DocumentCreate>\r\n <inv:Authentication>\r\n <inv:Email></inv:Email>\r\n <inv:Token></inv:Token>\r\n </inv:Authentication>\r\n <inv:Client>\r\n <inv:NIF></inv:NIF>\r\n <inv:Name></inv:Name>\r\n <inv:Address></inv:Address>\r\n <inv:City></inv:City>\r\n <inv:PostCode></inv:PostCode>\r\n <inv:CountryCode></inv:CountryCode>\r\n <inv:PhoneNumber></inv:PhoneNumber>\r\n <inv:CountryName></inv:CountryName>\r\n <inv:LegalName></inv:LegalName>\r\n <inv:Email></inv:Email>\r\n <inv:IBAN></inv:IBAN>\r\n </inv:Client>\r\n <inv:Document>\r\n <inv:Date></inv:Date>\r\n <inv:DueDate></inv:DueDate>\r\n <inv:Description></inv:Description>\r\n <inv:Type></inv:Type>\r\n <inv:Serie></inv:Serie> \r\n <inv:TaxExemptionReasonCode></inv:TaxExemptionReasonCode>\r\n <inv:DocumentReference></inv:DocumentReference>\r\n <inv:Currency></inv:Currency>\r\n <inv:Retention></inv:Retention>\r\n <inv:EuroRate></inv:EuroRate>\r\n <inv:ExternalId></inv:ExternalId> \r\n <inv:Lines>\r\n <inv:APIInvoicingProduct>\r\n <inv:Code></inv:Code>\r\n <inv:Description></inv:Description>\r\n <inv:UnitPrice></inv:UnitPrice>\r\n <inv:Quantity></inv:Quantity>\r\n <inv:Unit></inv:Unit>\r\n <inv:Type></inv:Type>\r\n <inv:TaxValue></inv:TaxValue>\r\n <inv:ProductDiscount></inv:ProductDiscount>\r\n <inv:CostCenter></inv:CostCenter>\r\n </inv:APIInvoicingProduct>\r\n <inv:APIInvoicingProduct>\r\n <inv:Code></inv:Code>\r\n <inv:Description></inv:Description>\r\n <inv:UnitPrice></inv:UnitPrice>\r\n <inv:Quantity></inv:Quantity>\r\n <inv:Unit></inv:Unit>\r\n <inv:Type></inv:Type>\r\n <inv:TaxValue></inv:TaxValue>\r\n <inv:ProductDiscount></inv:ProductDiscount>\r\n <inv:CostCenter></inv:CostCenter>\r\n </inv:APIInvoicingProduct>\r\n </inv:Lines>\r\n </inv:Document>\r\n <inv:IsToClose></inv:IsToClose>\r\n <inv:SendTo></inv:SendTo>\r\n </inv:DocumentCreate>\r\n </soapenv:Body>\r\n</soapenv:Envelope>";
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("https://bo.magnifinance.com/MagniAPI/Invoicing.asmx", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
var axios = require('axios');
var data = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://MagniAPI/Invoicing/">\r\n <soapenv:Header/>\r\n <soapenv:Body>\r\n <inv:DocumentCreate>\r\n <inv:Authentication>\r\n <inv:Email></inv:Email>\r\n <inv:Token></inv:Token>\r\n </inv:Authentication>\r\n <inv:Client>\r\n <inv:NIF></inv:NIF>\r\n <inv:Name></inv:Name>\r\n <inv:Address></inv:Address>\r\n <inv:City></inv:City>\r\n <inv:PostCode></inv:PostCode>\r\n <inv:CountryCode></inv:CountryCode>\r\n <inv:PhoneNumber></inv:PhoneNumber>\r\n <inv:CountryName></inv:CountryName>\r\n <inv:LegalName></inv:LegalName>\r\n <inv:Email></inv:Email>\r\n <inv:IBAN></inv:IBAN>\r\n </inv:Client>\r\n <inv:Document>\r\n <inv:Date></inv:Date>\r\n <inv:DueDate></inv:DueDate>\r\n <inv:Description></inv:Description>\r\n <inv:Type></inv:Type>\r\n <inv:Serie></inv:Serie> \r\n <inv:TaxExemptionReasonCode></inv:TaxExemptionReasonCode>\r\n <inv:DocumentReference></inv:DocumentReference>\r\n <inv:Currency></inv:Currency>\r\n <inv:Retention></inv:Retention>\r\n <inv:EuroRate></inv:EuroRate>\r\n <inv:ExternalId></inv:ExternalId> \r\n <inv:Lines>\r\n <inv:APIInvoicingProduct>\r\n <inv:Code></inv:Code>\r\n <inv:Description></inv:Description>\r\n <inv:UnitPrice></inv:UnitPrice>\r\n <inv:Quantity></inv:Quantity>\r\n <inv:Unit></inv:Unit>\r\n <inv:Type></inv:Type>\r\n <inv:TaxValue></inv:TaxValue>\r\n <inv:ProductDiscount></inv:ProductDiscount>\r\n <inv:CostCenter></inv:CostCenter>\r\n </inv:APIInvoicingProduct>\r\n <inv:APIInvoicingProduct>\r\n <inv:Code></inv:Code>\r\n <inv:Description></inv:Description>\r\n <inv:UnitPrice></inv:UnitPrice>\r\n <inv:Quantity></inv:Quantity>\r\n <inv:Unit></inv:Unit>\r\n <inv:Type></inv:Type>\r\n <inv:TaxValue></inv:TaxValue>\r\n <inv:ProductDiscount></inv:ProductDiscount>\r\n <inv:CostCenter></inv:CostCenter>\r\n </inv:APIInvoicingProduct>\r\n </inv:Lines>\r\n </inv:Document>\r\n <inv:IsToClose></inv:IsToClose>\r\n <inv:SendTo></inv:SendTo>\r\n </inv:DocumentCreate>\r\n </soapenv:Body>\r\n</soapenv:Envelope>';
var config = {
method: 'post',
url: 'https://bo.magnifinance.com/MagniAPI/Invoicing.asmx',
headers: {
'Content-Type': 'application/soap+xml; charset=utf-8'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Example Response
Success
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<DocumentCreateResponse xmlns="http://MagniAPI/Invoicing/">
<Response>
<RequestId>a004f883-f2a3-4af6-810a-6b28bde12503 </RequestId>
<Type>Success </Type>
<Object>
<DocumentId>67220 </DocumentId>
</Object>
</Response>
</DocumentCreateResponse>
</soap:Body>
</soap:Envelope>
Error
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<DocumentCreateResponse xmlns="http://MagniAPI/Invoicing/">
<Response>
<RequestId>45bb3204-4a4d-4e06-9f91-f4b6d4bcf1a0</RequestId>
<Type>Error</Type>
<ErrorValue>
<Value>14</Value>
<Name>SaveFailed</Name>
</ErrorValue>
<ErrorHumanReadable>ValidationError</ErrorHumanReadable>
<ValidationErrors>
<ValidationError>
<Type>MustBePosteriorToMostCurrentClosedDocument</Type>
<ElementNumber>0</ElementNumber>
<Field>DocumentDetailDate</Field>
<Detail>A closed document already exists with a date after this with this Series. You must change series or enter a date equal or after to 2022-04-04</Detail>
</ValidationError>
</ValidationErrors>
</Response>
</DocumentCreateResponse>
</soap:Body>
</soap:Envelope>
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:
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 Id field for?
- A: It serves to indicate the id of a document that you want to edit. They can only edit documents that are not in the closed state. For document creation, you do not need to fill in the id.
-
3. What is the use of the ExternalId field?
- A: It is used to prevent duplicate documents from being created, if they try to make the same request twice, 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 id exists.
-
4. 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. 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.
-
5. 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, they are 6%, 13% and 21%.
-
6.Put the email in the SendTo field and I still don't receive the email after the document creation request.
A: Making sure you put the correct email, the PDF is only sent by email when it's closed, make sure the IsToClose field is true.
-
7."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