Skip to main content

Create a Document

Creates an invoice, invoice-receipt, simplified invoice, credit note or debit note. On success the response returns the new document's DocumentId; use it with DocumentGet to get the document number and PDF.

POST https://bo.magnifinance.com/MagniAPI/Invoicing.asmx

Invoicing on behalf of other companies? See IPPN below.

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>api@yourcompany.pt</inv:Email>
<inv:Token>your-subscription-token</inv:Token>
</inv:Authentication>
<inv:Client>
<inv:NIF>166737755</inv:NIF>
<inv:Name>MagniFinance</inv:Name>
<inv:Address>Av. Sidónio Pais, n.º 2, 2.º Esq. A</inv:Address>
<inv:City>Lisboa</inv:City>
<inv:PostCode>1050-215</inv:PostCode>
<inv:CountryCode>PT</inv:CountryCode>
<inv:Email>info@magnifinance.com</inv:Email>
</inv:Client>
<inv:Document>
<inv:Date>2026-10-08</inv:Date>
<inv:DueDate>2026-11-07</inv:DueDate>
<inv:Description>Consulting services, October</inv:Description>
<inv:Type>T</inv:Type>
<inv:ExternalId>order-10045</inv:ExternalId>
<inv:Lines>
<inv:APIInvoicingProduct>
<inv:Code>CONSULT-H</inv:Code>
<inv:Description>Consulting hour</inv:Description>
<inv:UnitPrice>45.00</inv:UnitPrice>
<inv:Quantity>2</inv:Quantity>
<inv:Unit>Hour</inv:Unit>
<inv:Type>S</inv:Type>
<inv:TaxValue>23</inv:TaxValue>
<inv:ProductDiscount>0</inv:ProductDiscount>
</inv:APIInvoicingProduct>
</inv:Lines>
</inv:Document>
<inv:IsToClose>true</inv:IsToClose>
<inv:SendTo>info@magnifinance.com</inv:SendTo>
</inv:DocumentCreate>
</soapenv:Body>
</soapenv:Envelope>
tip

Leave out the optional fields you don't use. Don't send them empty: an empty number or date makes the whole request fail (see Sending values).

Request​

ParameterRequiredValue
Content-Typerequiredtext/xml; charset=utf-8
SOAPActionoptional"http://MagniAPI/Invoicing/DocumentCreate"

Body​

Authentication​

ParameterRequiredDescription
Emailrequiredstring(50) The email of an API user of your company with permission to create documents. Example: api@yourcompany.pt
Tokenrequiredstring(50) The token of the company (subscription) in which the document is created.

Client​

The customer the document is issued to.

ParameterRequiredDescription
NIFrequiredstring(20) The customer's tax id (NIF). It must be valid for the customer's country. Example: "166737755"
Namerequiredstring(75) The customer's usual (trade) name. Example: "MagniFinance"
Addressoptionalstring(200) The customer's address. Example: "Av. Sidónio Pais, n.º 2, 2.º Esq. A"
Cityoptionalstring(50) The customer's city. Example: "Lisboa"
PostCodeoptionalstring(50) The customer's postal code. It must be valid for the country. Example: "1050-215"
CountryCoderequiredstring(2) The customer's country, as an ISO 3166-1 alpha-2 code. Example: "PT"
PhoneNumberoptionalstring(50) The customer's phone number. Example: "912345678"
CountryNameoptionalstring The country's name. Example: "Portugal"
LegalNameoptionalstring(500) The customer's legal name, as printed on the document. If you leave it out, Name is used. Example: "MagniFin, Lda."
Emailoptionalstring(255) The customer's email address. Example: "info@magnifinance.com"
IBANoptionalstring(300) The customer's bank account (IBAN). Example: "PT50002700000001234567833"

Document​

ParameterRequiredDescription
Daterequireddate The document date, YYYY-MM-DD. It can't be earlier than the date of the last closed document in the same series. Example: "2026-10-08"
DueDaterequireddate The payment due date, YYYY-MM-DD. It can't be earlier than Date. Example: "2026-11-07"
Descriptionoptionalstring(300) A description printed on the document. At least 3 characters. Example: "Consulting services, October"
Typerequiredstring(1) The kind of document, in upper case: T invoice-receipt (fatura-recibo), I invoice (fatura), S simplified invoice (fatura simplificada), C credit note, D debit note, B quote (orçamento), P pro-forma invoice, Z purchase order (nota de encomenda). Your account needs an active series for the type. Waybills and delivery notes go through WaybillCreate. See the document types. Example: "T"
Serieoptionalstring(30) The series (numbering sequence) to use. Series names are unique per document type. If you leave it out, the company's default series for that type is used. You can see the series in MagniFinance under Settings → General → Document series. Example: "FR"
Idoptionalint Only to update or close a draft you created earlier: the DocumentId of that draft. Leave it out to create a new document. Example: 56232
TaxExemptionReasonCodeoptionalstring(3) Required when at least one line has 0% VAT: the legal reason for the exemption. Use a code from the Code column of the exemption reasons list. Example: "M01"
DocumentReferenceoptionalstring(100) The number of the document this one corrects. Required for credit and debit notes. See which types can reference which. Example: "FT FT/40420"
Currencyoptionalstring(3) A second currency for the document, as an ISO 4217 code. Amounts are always in EUR; this adds the equivalent in that currency. Example: "BRL"
Retentionoptionaldecimal Withholding tax (retenção na fonte), as a percentage of the document total. Example: 8
EuroRateoptionaldecimal The exchange rate for Currency: how much 1 EUR is worth in that currency. The EUR amounts are multiplied by it. Example: 5.85
ExternalIdoptionalstring(50) Your own id for this document, such as your order number. It prevents duplicates: a second document of the same type with the same ExternalId, sent by the same API user, is refused while the first one isn't cancelled. Documents can't be looked up by it; see FAQ 3. Example: "order-10045"
LinesrequiredList of APIInvoicingProduct The products or services on the document (see below).
PurchaseOrderoptionalstring(50) The customer's purchase order number, printed on the document. Example: "PO-2026-118"

Lines (APIInvoicingProduct)​

ParameterRequiredDescription
Coderequiredstring(60) Your code for the product or service. Example: "CONSULT-H"
Descriptionrequiredstring(200) The product or service description. Example: "Consulting hour"
UnitPricerequireddecimal Price per unit. Example: 45.00
Quantityrequireddecimal Number of units. Example: 2
Unitrequiredstring(50) The unit of measure. Example: "Hour", "KG"
Typerequiredstring(1) S for a service, P for a product. A product's type can't be changed after it was first used. Example: "S"
TaxValuerequireddecimal The VAT rate, in percent. It must be a rate in force for the company's tax region; in mainland Portugal: 23, 13, 6 or 0. Example: 23
TaxValueCountryoptionalstring(2) The country whose VAT rate applies to this line, as an ISO 3166-1 alpha-2 code — for example when you charge another EU country's VAT (OSS). TaxValue must then be a valid rate in that country. If you leave it out, your company's country is used. Example: "ES"
ProductDiscountrequireddecimal Discount on this line, in percent. Use 0 for none. Example: 0
CostCenteroptionalstring(50) A cost center for the line. Example: "Espanha"

Other Parameters​

ParameterRequiredDescription
IsToCloserequiredboolean true closes the document: it gets its number and PDF and can no longer be changed. false saves it as a draft, without number or PDF, which you can update or close later by sending its Id. Example: true
SendTooptionalstring An email address to send the document to once it is closed. Nothing is sent for drafts. Example: "info@magnifinance.com"

Response​

The result is in <Response>; see Response Format for the fields every response has. Object holds:

ParameterDescription
DocumentIdint The id of the created (or updated) document. Keep it to get the document later. Example: 67220
ErrorMessagestring Extra detail on some errors, such as why the email to SendTo failed. Empty on success.
Email errors

If the document was closed but the email to SendTo could not be sent, the response is an error (ErrorSendingEmail) and Object.DocumentId is filled in. The document exists: don't create it again.

Request Sample​

Save the Sample Body as request.xml, then:

cURL​

curl https://bo.magnifinance.com/MagniAPI/Invoicing.asmx \
--header 'Content-Type: text/xml; charset=utf-8' \
--header 'SOAPAction: "http://MagniAPI/Invoicing/DocumentCreate"' \
--data-binary @request.xml

JavaScript (Node.js 18+)​

const fs = require('fs');

const body = fs.readFileSync('request.xml', 'utf8');

fetch('https://bo.magnifinance.com/MagniAPI/Invoicing.asmx', {
method: 'POST',
headers: {
'Content-Type': 'text/xml; charset=utf-8',
SOAPAction: '"http://MagniAPI/Invoicing/DocumentCreate"',
},
body,
})
.then((response) => response.text())
.then((xml) => console.log(xml))
.catch((error) => console.error(error));

Node.js (axios)​

const fs = require('fs');
const axios = require('axios');

const body = fs.readFileSync('request.xml', 'utf8');

axios
.post('https://bo.magnifinance.com/MagniAPI/Invoicing.asmx', body, {
headers: {
'Content-Type': 'text/xml; charset=utf-8',
SOAPAction: '"http://MagniAPI/Invoicing/DocumentCreate"',
},
})
.then((response) => console.log(response.data))
.catch((error) => console.error(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 invoice on behalf of other companies (your partners) through IPPN, the Invoicing Platform for Partners Network:

Document types: by default, IPPN partners can only issue invoice-receipts (T) and credit notes (C) through the API. This protects the partners' tax compliance. Other types can be enabled on request.

Tokens: each partner company has its own token. Get them with GetPartnerAccessTokens and send the partner's token in Authentication to issue the document in that partner's name. The partner's token also determines which series is used for each document type, so you don't need to send Serie.

Series: MagniFinance creates the partner's series when the partnership is granted, named after your partnership's code (<CODE> for invoice-receipts, <CODE>NC for credit notes). Communicate them to the Tax Authority with Communicate Partner Series before the first document.

FAQ​

1. What do I put in CountryCode?

The customer's country as a two-letter ISO 3166-1 alpha-2 code: PT for Portugal, ES for Spain, DE for Germany, and so on.

2. What is the Id field for?

To update or close a draft (a document you created with IsToClose set to false). Send the draft's DocumentId as Id. Closed documents can't be changed. To create a new document, leave Id out.

3. What is ExternalId for?

To avoid creating the same document twice, for example when you retry after a timeout. Put your own reference in it, such as your order number.

  • When a document counts as a duplicate: it has the same ExternalId, the same document type, was sent by the same API user, and the first document isn't cancelled. A cancelled document frees its ExternalId. Another API user of the same company can reuse it.
  • What you get back: a ValidationError with Type DocumentIsADuplicate (or DocumentIsADuplicateDraft while the first document is still a draft) and Field DocumentDetailExternalId. ElementNumber usually contains the id of an existing document with the same ExternalId; verify it with DocumentGet.
  • Looking documents up: DocumentGet, DocumentCancel and DocumentGetProperty take the DocumentId only. You can't look a document up by its ExternalId, so store the DocumentId that DocumentCreate returns.

4. When do I need TaxExemptionReasonCode?

When at least one line has 0% VAT. Portuguese law requires the document to state why no VAT is charged, for example M07 (exempt under article 9 of the VAT code). Pick the code from the exemption reasons list.

5. What do I put in TaxValue?

The line's VAT rate in percent. It must be a rate in force in the company's tax region. In mainland Portugal the rates are 23% (standard), 13% (intermediate), 6% (reduced) and 0% (exempt, with a TaxExemptionReasonCode). Madeira and the Azores have their own rates.

6. I filled in SendTo but no email arrived.

Check the address first. The email is only sent when the document is closed, so IsToClose must be true. If sending fails, the response says so with the error ErrorSendingEmail (the document is still created).

7. Can I save a document as a draft and finish it later?

Yes. Send IsToClose as false; the response gives you the draft's DocumentId. To change the draft, call DocumentCreate again with that id in Id and the updated document. To close it, do the same with IsToClose set to true.

Still have questions? We're here to help: contact us.