Skip to main content

SOAP API for Invoicing & Waybills

The SOAP API exchanges XML messages. It is kept for existing integrations.

Note

For new integrations, we recommend the REST API instead.

TL;DR - Quick Start
POST https://bo.magnifinance.com/MagniAPI/Invoicing.asmx
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://MagniAPI/Invoicing/DocumentGet"

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://MagniAPI/Invoicing/">
<soapenv:Body>
<inv:DocumentGet>
<inv:Authentication>
<inv:Email>api@yourcompany.pt</inv:Email>
<inv:Token>your-subscription-token</inv:Token>
</inv:Authentication>
<inv:DocumentId>67220</inv:DocumentId>
</inv:DocumentGet>
</soapenv:Body>
</soapenv:Envelope>
PostmanTry it in Postman

Every operation on this page is in the Invoicing & Waybills SOAP Postman collection, with the envelope, Content-Type and SOAPAction already set. Import it, set email and token in its Variables tab and press Send. How to use it.

Or paste this URL in Postman's Import:

https://developer.magnifinance.com/finance/postman/invoicing-waybills-soap.json

WSDL​

https://bo.magnifinance.com/MagniAPI/Invoicing.asmx?WSDL

Most SOAP tools (SoapUI, .NET "Add Service Reference", wsimport, zeep, PHP SoapClient) can generate a client from this URL.

Endpoint​

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

SOAP version and headers​

Both SOAP 1.1 and SOAP 1.2 are supported. The Content-Type must match the envelope you send:

SOAP versionEnvelope namespaceContent-TypeSOAPAction
1.1 (used in all examples)http://schemas.xmlsoap.org/soap/envelope/text/xml; charset=utf-8Optional header, e.g. SOAPAction: "http://MagniAPI/Invoicing/DocumentCreate"
1.2http://www.w3.org/2003/05/soap-envelopeapplication/soap+xml; charset=utf-8Not needed
Common mistake

Sending a SOAP 1.1 envelope with Content-Type: application/soap+xml is rejected with HTTP 415 Unsupported Media Type.

Authentication​

Send your credentials in the body of every request:

<inv:Authentication>
<inv:Email>api@yourcompany.pt</inv:Email>
<inv:Token>your-subscription-token</inv:Token>
</inv:Authentication>
FieldDescription
Emailstring(50) The email of an API user of your company. The user needs permission for the operations you call.
Tokenstring(50) The token of the company (subscription) you are working in. The document is created in, or read from, this company.

Sending values​

  • Leave out the optional fields you don't use. Don't send them empty: an empty number or date (for example <inv:Retention></inv:Retention>) can't be read and the whole request fails with a SOAP fault (Server was unable to read request … Input string was not in a correct format).
  • Dates use the XML format YYYY-MM-DD (or YYYY-MM-DDThh:mm:ss for a date and time).
  • Decimals use a dot: 2.45, not 2,45.
  • Booleans are true or false.

Available Operations​

OperationDescription
DocumentCreateCreate invoices, invoice-receipts, simplified invoices, credit notes and debit notes
DocumentGetGet a document's number, PDF link and details
DocumentCancelCancel a closed document
WaybillCreateCreate waybills and delivery notes
DocumentGetPropertyGet a document's payment status
ClientGetGet a company registered in your subscription by its tax id

The same endpoint also has the operations for partners invoicing on behalf of other companies (IPPN): AddPartner and GetPartnerAccessTokens.

Response Format​

Every operation answers with the same structure. Only the name of the wrapping element and the content of Object change.

FieldDescription
RequestIdstring Unique id of this request. Quote it when you contact support. Example: "a004f883-f2a3-4af6-810a-6b28bde12503"
Typestring Success or Error. Always check it before reading Object.
ObjectThe result of the operation. Its fields are listed on each operation's page. Some errors also return an Object (for example the DocumentId of a document that was created but could not be emailed).
ErrorValueOnly on errors. Value (int) and Name (string) identify the error, e.g. 14 / SaveFailed. See Error Codes.
ErrorHumanReadablestring Only on some errors. A short description of the error. When it only repeats the error name (e.g. ValidationError), the details are in ValidationErrors.
ValidationErrorsOnly when fields failed validation. A list of ValidationError (below).

ValidationError​

FieldDescription
Typestring What is wrong. Example: "MustBePosteriorToMostCurrentClosedDocument"
ElementNumberint Which element failed, when the field repeats (e.g. the line number in Lines). 0 otherwise.
Fieldstring The field that failed validation. Example: "DocumentDetailDate"
Detailstring An explanation of the problem. Example: "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 2021-11-10"

Name of the response element​

OperationResponse element
DocumentCreate, DocumentGet, DocumentCancel<Response>
WaybillCreate<ResponseWaybillCreate>
DocumentGetProperty<ResponseDocumentGetProperty>
ClientGet<ResponseClientGet>
AddPartner, GetPartnerAccessTokens (IPPN)<ResponseAddPartner>, <ResponseGetPartnerAccessTokens>

Success Response​

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<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 Response​

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<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>

A request that can't be read (not valid XML, or a value in the wrong format) is answered with a standard SOAP Fault (HTTP 500) instead.

Namespaces​

PrefixNamespace URI
soapenvhttp://schemas.xmlsoap.org/soap/envelope/ (SOAP 1.1)
invhttp://MagniAPI/Invoicing/

See Error Codes for a complete list of error types.