NAV
ruby python javascript csharp

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',
    'fields[0].fieldName' => '{extracted field name i.e. documentNumber}',
    'fields[0].value' => 'xyz'
  },
  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
hasErrorInERP query boolean optional e.g. true, false
includeDocumentDetailsInResponse query boolean optional if true, response will have detial of document
fields[0].fieldName query string optional filter on extracted field of a document e.g. DocumentNumber
fields[0].value query string optional value of extracted field filter e.g. XYZ1234

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. Sync 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. Sync Purchase-Order

This endpoint is used to save puchase-orders 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​/PurchaseOrder',
  headers: headers

p = JSON.parse(result)

POST /api/v2/PurchaseOrder

Parameters

Name In Type Required Description
PONumber body string mandatory pruchase order number
Customerd body string optional customer's id
CustomerName body string optional customer's name
VendorId body string mandatory vendor's id
VendorName body string mandatory vendor's name
IssueDate body date mandatory date in yyyy-mm-dd format
TotalAmount body string mandatory total amount
CreatedBy body string optional user who initiated this in ERP
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

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

Example Response

HTTP STATUS 200

Responses

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

7. 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

8. 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.
ruby python javascript csharp