Introduction

Welcome to the Dost API!

This document contains message contract details of Rest Api’s which will be used to fetch posted documents details from mydost.

For greater security, minimum Transport Layer Security (TLS) protocol version is enforced on API Gateway custom domain by setting a security policy.

API Access Key & Authentication

After creating a mydost account, the Integration dashboard will reveal the unique API access key, you can use to authenticate with the API. To do so, simply attach the Authorization header to the API's URL and set it to your API access key.

API https://api.mydost.ai

API Features

Use the API's base endpoint and append the URL you would like to call along with API key in authorization header. This documentation covers technical detail of our Rest API endpoints.

1. Search Documents

This endpoint is used to search documents with different filters, details of Rest Api contract can be found below

GET /api/v2/documents

Code sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
  'Authorization' => '{ACCESS_KEY}'
}

result = RestClient.get '/api/v2/documents',
  params: {
    'fromDate' => 'yyyy-mm-dd',
    'toDate' => 'yyyy-mm-dd'
  },
  headers: headers

p = JSON.parse(result)

Example response

{ 
 documents:[
 {
 "documentId": "",
 "userId": "",
 "fileName":"",
 "documentStatus": "",
 "approvalStatus": "",
 "url": "",
 "isCreatedInERP": true|false,
 "hasErrorInERP": true|false,
 "documentClass": ""
 }
]}

Parameters

Name	In	Type	Required	Description
page	query	number	mandatory	Page number. default is 1
record	query	number	mandatory	Number of record in payload. default is 10
fromDate	query	string(date)	optional	The date on which the range starts (yyyy-mm-dd)
toDate	query	string(date)	optional	The date on which the range ends (yyyy-mm-dd)
documentStatus	query	string	optional	e.g. Processed, Reviewed, NeedReview, Failed, Duplicate, Default
approvalStatus	query	string	optional	e.g. NoApprovalRequired, NeedApproval, Approved, Rejected
userId	query	string	optional	only apply if user is organization's admin
documentClass	query	string	optional	e.g. Invoice, DeliveryNote, PurchaseOrder, Unknown
hasErrorInERP	query	boolean	optional	e.g. true, false

Responses

Status	Meaning	Description	Schema
200	OK	Information about the document	Document
default	Default	Unexpected error	Error

2. Get Document Detail

This endpoint is used to get detail of document, details of Rest Api contract can be found below

Code sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
  'Authorization' => '{ACCESS_KEY}'
}

result = RestClient.get '/api/v2/documents/{documentId}',
  headers: headers

p = JSON.parse(result)

GET /api/v2/documents/{documentId}

Parameters

Name	In	Type	Required	Description
documentId	query	string	mandatory	Unique id of the document

Example Response

"Document": {
  "documentId": "",
  "fileName": "",
  "documentHash": "",
  "documentURL": "",
  "userId": "",
  "customerCompanyName": "",
  "customerCompanyID": "",
  "customerCompanyAddress": "",
  "vendorCompanyName": "",
  "vendorCompanyID": "",
  "vendorCompanyAddress": "",
  "shipmentAddress": "",
  "billingCustomerCompanyName": "",
  "billingCustomerCompanyID": "",
  "billingCustomerAddress": "",
  "poNumber": "",
  "invoiceDate": "",
  "dueDate": "",
  "currentDate": "",
  "totalWithoutTax": "",
  "totalTax": "",
  "totalAmount": "",
  "customerEmail": "",
  "vendorEmail": "",
  "phoneNumber": "",
  "contactPerson": "",
  "deliveryNote": "",
  "constructionCode": "",
  "providerCode": "",
  "items": [
    {
    "referenceCode": "",
    "description": "",
    "unit": "",
    "unitPrice": "",
    "quantity": "",
    "valueAddedTaxPercentage": "",
    "valueAddedTax": "",
    "dtoPercentage": "",
    "dto": "",
    "discountPercentage": "",
    "discount": "",
    "commissionPercentage": "",
    "commission": "",
    "deliveryNote": "",
    "poNumber": "",
    "subTotalAmount": ""
    }
  ],
  "taxes": [
    {
    "baseAmount": "",
    "taxType": "",
    "valueAddedTaxPercentage": "",
    "valueAddedTax": "",
    "totalAfterTax": ""
  }
  ],
  "shipments": [
    {
    "containerInfo": "",
    "tariffNumber": "",
    "lotNumber": "",
    "casNumber": "",
    "manifestNumber": "",
    "sealNumber": "",
    "dua": "",
    "pallets": "",
    "grossWeight": "",
    "netWeight": "",
    "countryOfOrigin": "",
    "countryOfDestination": "",
    "mediumOfTransport": "",
    "currency": "",
    "deliveryTerms": "",
    "paymentTerms": "",
    "paymentMethod": "",
    "loadingPort": "",
    "destinationPort": ""
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Details about the document	Document
default	Default	Unexpected error	Error

3. Get Formatted Detail of Document

This is used to get detail of document in different format like SAP, Facturae 3.2.2, etc., details of Rest Api contract can be found below

Code sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
  'Authorization' => '{ACCESS_KEY}'
}

result = RestClient.get '/api/v2/documents/{documentId}/format/{outputType}',
  headers: headers

p = JSON.parse(result)

GET /api/v2/documents/{documentId}/format/{outputType}

Parameters

Name	In	Type	Required	Description
documentId	query	string	mandatory	Unique id of the document
outputType	query	string	mandatory	1=SAP, 2=Facturae_3.2.2

Example Response - SAP

{
    "ZMM_INOVICE": [
        {
            "BUDAT": "",
            "BUKRS": "",
            "DIFFERENZ": "",
            "STCD1": "",
            "WMWST": "",
            "WRBTR": "5",
            "XBLNR": "",
            "URL": "",
            "INVOICEGUID": "",
            "USERGUID": "",
            "EBELP": "1",
            "EBELN": "",
            "LFSNR": "",
            "TXZ01": "",
            "MENGE": "",
            "WRBTR1": "",
            "DIFFERENZ1": "",
            "LIFNR": "",
            "MWSKZ1": "",
            "MWSKZ": "",
            "MEINS": "",
            "IDNLF": "",
            "WMWST1": "",
            "MATNR": ""
        }
    ]
}

Example Response - Facturae 3.2.2

<facturae:Facturae xmlns:facturae="http://www.facturae.gob.es/formato/Versiones/Facturaev3_2_2.xml" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <FileHeader>
        <SchemaVersion></SchemaVersion>
        <Modality></Modality>
        <InvoiceIssuerType></InvoiceIssuerType>
        <ThirdParty>
            <TaxIdentification>
                <PersonTypeCode></PersonTypeCode>
                <ResidenceTypeCode></ResidenceTypeCode>
                <TaxIdentificationNumber></TaxIdentificationNumber>
            </TaxIdentification>
            <LegalEntity>
                <CorporateName></CorporateName>
                <AddressInSpain>
                    <Address></Address>
                    <CountryCode></CountryCode>
                </AddressInSpain>
            </LegalEntity>
        </ThirdParty>
        <Batch>
            <BatchIdentifier></BatchIdentifier>
            <InvoicesCount></InvoicesCount>
            <TotalInvoicesAmount>
                <TotalAmount></TotalAmount>
            </TotalInvoicesAmount>
            <TotalOutstandingAmount>
                <TotalAmount></TotalAmount>
            </TotalOutstandingAmount>
            <TotalExecutableAmount>
                <TotalAmount></TotalAmount>
            </TotalExecutableAmount>
            <InvoiceCurrencyCode></InvoiceCurrencyCode>
        </Batch>
    </FileHeader>
    <Parties>
        <SellerParty>
            <TaxIdentification>
                <PersonTypeCode></PersonTypeCode>
                <ResidenceTypeCode></ResidenceTypeCode>
                <TaxIdentificationNumber></TaxIdentificationNumber>
            </TaxIdentification>
            <LegalEntity>
                <CorporateName></CorporateName>
                <AddressInSpain>
                    <Address></Address>
                    <CountryCode></CountryCode>
                </AddressInSpain>
            </LegalEntity>
        </SellerParty>
        <BuyerParty>
            <TaxIdentification>
                <PersonTypeCode></PersonTypeCode>
                <ResidenceTypeCode></ResidenceTypeCode>
                <TaxIdentificationNumber></TaxIdentificationNumber>
            </TaxIdentification>
            <AdministrativeCentres>
                <CentreCode></CentreCode>
                <RoleTypeCode></RoleTypeCode>
                <Name></Name>
                <AddressInSpain>
                    <Address></Address>
                    <CountryCode></CountryCode>
                </AddressInSpain>
            </AdministrativeCentres>
            <LegalEntity>
                <CorporateName></CorporateName>
                <AddressInSpain>
                    <Address></Address>
                    <CountryCode></CountryCode>
                </AddressInSpain>
            </LegalEntity>
        </BuyerParty>
    </Parties>
    <Invoices>
        <Invoice>
            <InvoiceHeader>
                <InvoiceNumber></InvoiceNumber>
                <InvoiceDocumentType></InvoiceDocumentType>
                <InvoiceClass></InvoiceClass>
            </InvoiceHeader>
            <InvoiceIssueData>
                <IssueDate></IssueDate>
                <InvoicingPeriod>
                    <StartDate></StartDate>
                    <EndDate></EndDate>
                </InvoicingPeriod>
                <InvoiceCurrencyCode></InvoiceCurrencyCode>
                <TaxCurrencyCode></TaxCurrencyCode>
                <LanguageName></LanguageName>
            </InvoiceIssueData>
            <TaxesOutputs>
                <Tax>
                    <TaxTypeCode></TaxTypeCode>
                    <TaxableBase>
                        <TotalAmount></TotalAmount>
                    </TaxableBase>
                    <TaxAmount>
                        <TotalAmount>2</TotalAmount>
                    </TaxAmount>
                </Tax>
            </TaxesOutputs>
            <InvoiceTotals>
                <TotalGrossAmount></TotalGrossAmount>
                <TotalGeneralDiscounts></TotalGeneralDiscounts>
                <TotalGeneralSurcharges></TotalGeneralSurcharges>
                <TotalGrossAmountBeforeTaxes></TotalGrossAmountBeforeTaxes>
                <InvoiceTotal></InvoiceTotal>
                <TotalFinancialExpenses></TotalFinancialExpenses>
                <TotalOutstandingAmount></TotalOutstandingAmount>
                <TotalPaymentsOnAccount></TotalPaymentsOnAccount>
                <TotalExecutableAmount></TotalExecutableAmount>
            </InvoiceTotals>
            <Items>
                <InvoiceLine>
                    <SequenceNumber></SequenceNumber>
                    <ItemDescription></ItemDescription>
                    <Quantity></Quantity>
                    <UnitOfMeasure></UnitOfMeasure>
                    <UnitPriceWithoutTax></UnitPriceWithoutTax>
                    <TaxesOutputs>
                        <Tax>
                            <TaxTypeCode></TaxTypeCode>
                            <TaxableBase>
                                <TotalAmount></TotalAmount>
                            </TaxableBase>
                        </Tax>
                    </TaxesOutputs>
                    <AdditionalLineItemInformation></AdditionalLineItemInformation>
                </InvoiceLine>
                <InvoiceLine>
                    <SequenceNumber></SequenceNumber>
                    <ItemDescription></ItemDescription>
                    <Quantity></Quantity>
                    <UnitOfMeasure></UnitOfMeasure>
                    <UnitPriceWithoutTax></UnitPriceWithoutTax>
                    <TaxesOutputs>
                        <Tax>
                            <TaxTypeCode></TaxTypeCode>
                            <TaxableBase>
                                <TotalAmount></TotalAmount>
                            </TaxableBase>
                        </Tax>
                    </TaxesOutputs>
                    <AdditionalLineItemInformation></AdditionalLineItemInformation>
                </InvoiceLine>
            </Items>
            <PaymentDetails>
                <Installment>
                    <InstallmentDueDate></InstallmentDueDate>
                    <InstallmentAmount></InstallmentAmount>
                    <PaymentMeans></PaymentMeans>
                </Installment>
            </PaymentDetails>
        </Invoice>
    </Invoices>
</facturae:Facturae>

Responses

Status	Meaning	Description	Schema
200	OK	Details about the document	Document
default	Default	Unexpected error	Error

4. Update Document ERP Status

This endpoint is used to update ERP status of documents, details of Rest Api contract can be found below.

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
  'Authorization' => '{ACCESS_KEY}'
}

result = RestClient.put '/api/v2/documents/ERPStatus',
  headers: headers

p = JSON.parse(result)

PUT /api/v2/documents/ERPStatus

Parameters

Name	In	Type	Required	Description
DocumentId	body	integer(int32)	mandatory	ID of the document
Status	body	integer	mandatory	0=UnProcessed, 1=Processed
Message	body	string	mandatory	Messsage what cause failure and will appear in portal

Example Request

{
    "ERPStatusUpdateRequest":[
        {
            "DocumentId": "",
            "Status": 1,
            "Message":"Created"
        },
        {
            "DocumentId": "",
            "Status": 0,
            "Message":"Unknow Error"
        }
    ]
}

Example Response

HTTP STATUS 200

Responses

Status	Meaning	Description	Schema
200	OK	-	-
default	Default	Unexpected error	Error

5. Save Delivery-Note

This endpoint is used to save delivey-notes information which is then used to detect discrepancy in an invoice , details of Rest Api contract can be found below.

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
  'Authorization' => '{ACCESS_KEY}'
}

result = RestClient.post '/api/v2/DeliveryNote',
  headers: headers

p = JSON.parse(result)

POST /api/v2/DeliveryNote

Parameters

Name	In	Type	Required	Description
DeliveryNoteNumber	body	string	mandatory	delivery note number
PONumber	body	string	optional	pruchase order number
VendorId	body	string	mandatory	vendor's id
VendorName	body	string	mandatory	vendor's name
IssueDate	body	date	mandatory	date in yyyy-mm-dd format
Items	body	array	mandatory	array of items
Items.ReferenceCode	body	string	mandatory	item's reference code
Items.Name	body	string	mandatory	item's name
Items.Quantity	body	int	mandatory	item's quantity

Example Request

{
  "deliveryNoteNumber": "",
  "poNumber": "",
  "vendorId": "",
  "vendorName": "",
  "issueDate": "",
  "items": [
    {
      "referenceCode": "",
      "name": "",
      "quantity": 0
    }
  ]
}

Example Response

HTTP STATUS 200

Responses

Status	Meaning	Description	Schema
200	OK	-	-
default	Default	Unexpected error	Error

6. Update Connected-ERP Status

This endpoint is used to update status of connected ERP if the document has been approved or rejected.

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
  'Authorization' => '{ACCESS_KEY}'
}

result = RestClient.put '/api/v2/ERPDetails',
  headers: headers

p = JSON.parse(result)

PUT /api/v2/ERPDetails

Parameters

Name	In	Type	Required	Description
DocumentId	body	string	mandatory	unique id of a document
Status	body	string	mandatory	approved, rejected
Date	body	string	mandatory	date when status was actually approved/rejected. format yyyy-mm-dd
Message	body	string	optional	approved or rejected reason

Example Request

{
  "documentId": "",
  "status": "",
  "date": "",
  "message": ""
}

Example Response

HTTP STATUS 200

Responses

Status	Meaning	Description	Schema
200	OK	-	-
default	Default	Unexpected error	Error

7. Update Payment Detail

This endpoint is used to update payment details of a document.

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
  'Authorization' => '{ACCESS_KEY}'
}

result = RestClient.put '/api/v2/Payments',
  headers: headers

p = JSON.parse(result)

PUT /api/v2/Payments

Parameters

Name	In	Type	Required	Description
DocumentId	body	string	mandatory	unique id of a document
Status	body	string	mandatory	paid, unpaid
TransactionMethod	body	string	mandatory	any payment method i.e. cash, cheque, creditcard, online, etc
TransactionDate	body	string	mandatory	payement date in format yyyy-mm-dd
customProperties.prop1	body	string	optional	attach custom properties. prop1 here become a key. 'N' number of custom properties

Example Request

{
  "documentId": "",
  "status": "",
  "transactionMethod": "",
  "transactionDate": "",
  "customProperties": [
    {
      "prop1": "val1",
      "prop2": "val2",
      ...
    }
  ]
}

Example Response

HTTP STATUS 200

Responses

Status	Meaning	Description	Schema
200	OK	-	-
default	Default	Unexpected error	Error

Schemas

Error Response

Name	Type	Description
title	string	Error message type
status	number	http status
detail	string	error message detail
errors	string	multiple validation failure messages

Example Error Response

{
    "title": "Not Found",
    "status": 404,
    "detail": "document '{documentId}' not found",
    "errors": {}
}

API Error Codes

If your request fails, the mydost API will return an error in JSON format. Find below an example error that occurs when the API failed scraping the requested URL.

Code	Type	Info
400	Bad Request	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401	Unauthorized	The client must authenticate itself with valid access key to get the requested response. In case of invalid access key or missing access key generate Unauthorized.
404	Not Found	The server can not find the requested resource. This means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist.
416	Range Not Satisfiable	The range specified by the Range header field in the request cannot be fulfilled. It's possible that the range is outside the size of the target URI's data.
422	Unprocessable Entity	The request was well-formed but was unable to be followed due to semantic errors.
429	Too Many Requests	The user has sent too many requests in a given amount of time ("rate limiting").
500	Internal Server Error	The server has encountered a situation it does not know how to handle.
501	Not Implemented	The request method is not supported by the server and cannot be handled. The only methods that servers are required to support (and therefore that must not return this code) are GET and HEAD.
502	Bad Gateway	This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response.
503	Service Unavailable	The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.