SOAP API for Invoicing & Waybills
The SOAP API exchanges XML messages. It is kept for existing integrations.
For new integrations, we recommend the REST API instead.
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>
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 version | Envelope namespace | Content-Type | SOAPAction |
|---|---|---|---|
| 1.1 (used in all examples) | http://schemas.xmlsoap.org/soap/envelope/ | text/xml; charset=utf-8 | Optional header, e.g. SOAPAction: "http://MagniAPI/Invoicing/DocumentCreate" |
| 1.2 | http://www.w3.org/2003/05/soap-envelope | application/soap+xml; charset=utf-8 | Not needed |
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>
| Field | Description |
|---|---|
| string(50) The email of an API user of your company. The user needs permission for the operations you call. | |
| Token | string(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(orYYYY-MM-DDThh:mm:ssfor a date and time). - Decimals use a dot:
2.45, not2,45. - Booleans are
trueorfalse.
Available Operations
| Operation | Description |
|---|---|
| DocumentCreate | Create invoices, invoice-receipts, simplified invoices, credit notes and debit notes |
| DocumentGet | Get a document's number, PDF link and details |
| DocumentCancel | Cancel a closed document |
| WaybillCreate | Create waybills and delivery notes |
| DocumentGetProperty | Get a document's payment status |
| ClientGet | Get 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.
| Field | Description |
|---|---|
| RequestId | string Unique id of this request. Quote it when you contact support. Example: "a004f883-f2a3-4af6-810a-6b28bde12503" |
| Type | string Success or Error. Always check it before reading Object. |
| Object | The 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). |
| ErrorValue | Only on errors. Value (int) and Name (string) identify the error, e.g. 14 / SaveFailed. See Error Codes. |
| ErrorHumanReadable | string 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. |
| ValidationErrors | Only when fields failed validation. A list of ValidationError (below). |
ValidationError
| Field | Description |
|---|---|
| Type | string What is wrong. Example: "MustBePosteriorToMostCurrentClosedDocument" |
| ElementNumber | int Which element failed, when the field repeats (e.g. the line number in Lines). 0 otherwise. |
| Field | string The field that failed validation. Example: "DocumentDetailDate" |
| Detail | string 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
| Operation | Response 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
| Prefix | Namespace URI |
|---|---|
soapenv | http://schemas.xmlsoap.org/soap/envelope/ (SOAP 1.1) |
inv | http://MagniAPI/Invoicing/ |
See Error Codes for a complete list of error types.