NAV Navbar
shell
  • CodaBox API V2
  • Introduction
  • Support
  • Authentication
  • Data model
  • Get Documents
  • Sales Invoices - copy to accountant
  • Search endpoints
  • Changelog

    • CodaBox API V2

    Welcome to the documentation of CodaBox API V2.

    The Version 2.0 of the API is the current version. The Version 1.0 has been deprecated as of 1rst january 2017 and should not be used anymore.

    API urls

    URL prefixes by environments:

    Staging <api_prefix>
    Staging v2 https://sandbox-api.codabox.com/v2/
    Production <api_prefix>
    production v2 https://api.codabox.com/v2/

    Introduction

    CodaBox provides an JSON-based HTTP API that enables the integration of its services within your own software. Depending on the partnership you have with us, some features are available for you.

    This documentation will be updated as new features and/or modifications are added.

    How to read this documentation?

    Depending on the kind of service you provide, some features are available for you:

    1. An accountancy-software

      - Authentication

      - Bank account mandate order for a fiduciary's client

      - Get Documents: CODA, SODA, INVOICES (Sales and Purchases) and their PDF images. (Please note that the availability of those documents depends on the services your client has contracted with CodaBox)

    2. A sales-invoicing software

      - Authentication

      - Get Documents: CODAPlus (XML file with the positive transactions on your client’s bank account) (Please note that the availability of those documents depends on the services your client’s accountant has contracted with CodaBox)

      - Upload the sales invoices generated by your client through your own software (and then allow CodaBox to deliver it to your client’s accountant)

    Lexicon

    Support

    For technical questions you can contact api@codabox.com.

    When contacting our support team please mention following info:

    Please communicate in English.

    For the services related to e-invoicing, please note that the support team of Codabox considers that you have the necessary skills to create a correct UBL-invoice. Our support team will not handle basic questions on how to generate a correct UBL. Should you need information on UBL-generation, please consult the available documentation and possibly validation tools that are publicly available on the internet.

    Please find below the checklist with the requirements to be met before receiving the credentials for production:

    Authentication

    Introduction Authentication

    The authentication process associates 3 stakeholders:

    Third party which consumes CodaBox' API is authenticated with a key X-Software-Company that is given by CodaBox.

    The Fiduciary or the fiduciary's client (as the client of the third party) receives a TOKEN from CodaBox. The TOKEN will have to be filled in the third party software to get the credentials related to the TOKEN.

    get-credentials resource doesn't require any credentials and is usable only one time for a given TOKEN to retrieve credentials.

    Credentials must be stored by the third party software.

    From this point, depending on the user's permissions, several resources will be available.

    Data Model

    Env <api_prefix>
    Staging https://sandbox-api.codabox.com/v2/

    X-Software-Company

    Command :

     curl \
   -H "X-Software-Company: 08d09a20-1a94-4284-9305-375d46a02914"
   "api_endpoint_here"

    Each API call must include the X-Software-Company key in the header of every API request.

    X-Software-Company: 08d09a20-1a94-4284-9305-375d46a02914

    X-Software-Company key must be requested to Codabox for staging and production at api@codabox.com.

    Credentials

    Each API call is performed using basic authentication. The credentials are provided one time through a specific endpoint:

    GET <api_prefix>/get-credentials/<TOKEN>/

    Command :

    curl \
    -H "X-Software-Company: 08d09a20-1a94-4284-9305-375d46a02914" \
    "https://sandbox-api.codabox.com/v2/get-credentials/a19c62be748043449942c12712f42922/"

    The above command returns JSON structured like this:

    {
  "username": "foo",
  "password": "bar"
}
    Method HTTP request Note
    get GET <api_prefix>/get-credentials/<TOKEN>/ get user credentials

    For testing purpose, TOKEN for staging environment can be requested by third party software to Codabox at api@codabox.com

    Once the credentials have been retrieved, each API call must include both X-Software-Company (header) and the credentials:

    curl \
    -H "X-Software-Company: 08d09a20-1a94-4284-9305-375d46a02914"
    -sL -k -u foo:bar "https://sandbox-api.codabox.com/v2/<resource>/"

    Errors

    HTTP Status Code Reason
    401 Unauthorized
    403 Forbidden

    In case of HTTP errors, a verbose message is send back in the value field of a dictionary where the key is detail :

    {
  "detail": "Invalid username/password."
}
    HTTP 401 Unauthorized
    Invalid username/password.
    User inactive or deleted.
    HTTP 403 Forbidden
    This endpoint is accessible only to fiduciaries
    This endpoint is writable only to fiduciaries
    This endpoint is accessible only to fiduciary's clients
    This user does not have a pod-client
    This user does not have the mandate creation permission
    The software can not be found or is not active
    The software can not be found, is not active or is not the one registered for this user
    The software can not be found, is not active or does not have the permission to request credentials
    The software can not be found, is not active or does not have the permission to request access to the CODA+
    This user does not have the permission to upload sale invoices

    Notes

    If an url is not ending with a /, the request will be redirected to the same url with the / appended. Depending on the HTTP client used and the way it handles redirects, you may receive a 301 or a 401 or a 200 with a GET instead of a POST.

    Due to the numerous "wrong" behaviors that could happen, make sure you always append your urls with a /

    All json sent to CodaBox API must be encoded in UTF-8

    Data model

    Data Model

    fiduciary

    JSON Fiduciary

    {
  "id": "91f6fa60-23d6-48c0-b59f-5debf369dca0",
  "name": "fiduciary 2",
  "legal_entity": {
    "name": "fiduciary 1",
    "enterprise_num": "BE0010013269",
    "is_enterprise_num_validated": true,
    "representative_name": "Representative",
    "representative_function": "Director",
    "address": "fiduciary 1 address",
    "address2": "",
    "zip": "1000",
    "city": "Bruxelles"
  },
  "contact_name": "contact fiduciary 1",
  "contact_email": "contact@fiduciary1.com",
  "language": "fr",
  "website_url": "",
  "allows_doccle_delivery": true,
  "allows_client_delivery": true,
  "services": [],
  "delegates_mandate_delivery": true,
  "software": {
    "name": "software_name",
    "slug": "software_slug",
    "supported_services": ["soda-delivery"]
  }
}
    Field Type Values - format Note
    id string uuid fiduciary identifier
    name string ?{100} fiduciary's company name
    contact_name string ?{100} fiduciary's contact name
    contact_email string ?{75} fiduciary's contact name
    language string fr, nl fiduciary's language
    website_url string fiduciary's website url
    allows_doccle_delivery bool the fiduciary allows doccle delivery to its client
    allows_purchase_invoice_mandate bool the fiduciary has agreed with purchase mandate
    allows_client_delivery bool the fiduciary allows delivery to its client
    legal_entity JSON legal_entity
    delegates_mandate_delivery bool the fiduciary delegates the mandates delivery to CodaBox
    services JSON list NA services
    software JSON NA software 
    {
  "...": "...",
  "legal_entity": {
    "name": "fiduciary 1",
    "enterprise_num": "BE0010013269",
    "is_enterprise_num_validated": true,
    "representative_name": "Representative",
    "representative_function": "Director",
    "address": "fiduciary 1 address",
    "address2": "",
    "zip": "1000",
    "city": "Bruxelles"
  },
  "...": "..."
}
    Field Type Values - format Note
    name string ?{160} client's company name
    enterprise_num string BE[0-9]{10} enterprise number
    representative_name string ?{160} name of the client's representative
    representative_function string ?{128} function of the client's representative
    address string ?{100} first client address
    address2 string ?{100} second client address
    zip string ?{20} zip
    city string ?{50} city
    is_enterprise_num_validated bool NA

    services

    The services key has been deprecated and will show an empty list [ ]. Only relevant for internal use.

    software

    The software key is only relevant for internal use.

    The software key indicate the fiduciary software and its supported service

    Field Type Values - format Note
    name string name of the fiduciary's software
    slug string slug of the fiduciary's software
    supported_services string List of supported services by the software

    Internal keys/fields

    The following keys are currently not relevant for third party and only used for internal purpose:

    client

    JSON Client

    {
  "id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
  "fiduciary_id": "bfb564f3-dba8-4d90-b84d-335212ef5484",
  "legal_entity": {
    "name": "Client X",
    "enterprise_num": "BE0840559537",
    "is_enterprise_num_validated": false,
    "representative_name": "no name",
    "representative_function": "no function",
    "address": "no address",
    "address2": "no address",
    "zip": "no zip",
    "city": "no city"
  },
  "client_code": "CODABOX-01",
  "contact_name": "no name",
  "contact_email": "no email",
  "purchase_invoice_email": "no email",
  "language": "NA",
  "exact_email": "no email",
  "coda_mandates": [],
  "bank_accounts": [
    {
      "iban": "BE46977000017948",
      "coda_mandate_ids": [],
      "bank_id": "CDBXBE33",
      "client_id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
      "state": "draft",
      "state_modified_at": "",
      "type": "savings",
      "subaccounts": [
        {
          "currency": "USD",
          "extension": 234
        }
      ]
    }
  ],
  "social_mandates": [],
  "purchase_invoice_mandates": [],
  "state": "no state",
  "purchase_invoice_transmission_mandates": [],
  "services": [],
  "current_purchase_invoice_mandate_state": "no state",
  "delivery_mode": "no mode",
  "doccle_link_connect": "no link",
  "mycodabox_url": "no url",
  "state_modified_at": {},
  "zoomit_ibans": [],
  "mycodabox_access_state": "no state",
  "purchase_invoice_service": [],
  "is_purchase_invoice_delivery_via_push_blocked": false
}
    Field Type Values - format Note
    id string uuid client identifier
    fiduciary_id string uuid fiduciary identifier
    client_code string ?{50} client code
    contact_name string NA - (deprecated)
    contact_email string NA - (deprecated)
    language string NA - (deprecated)
    exact_email string NA - (deprecated)
    state string NA - (deprecated)
    state_modified_at string NA - (deprecated)
    delivery_mode string NA - (deprecated)
    legal_entity JSON legal_entity
    coda_mandates JSON NA - (deprecated)
    bank_accounts JSON bank accounts
    social_mandates JSON NA - (deprecated)
    doccle_link_connect string NA - (deprecated)
    mycodabox_url string NA - (deprecated)
    mycodabox_access_state string NA - (deprecated)
    purchase_invoice_service JSON NA - (deprecated)
    purchase_invoice_mandates JSON list NA - (deprecated)
    zoomit_ibans JSON list NA - (deprecated)
    services JSON list NA - (deprecated)
    purchase_invoice_transmission_mandates JSON list NA - (deprecated)
    current_purchase_invoice_mandate_state string NA - (deprecated)
    Field Type Values - format Note
    name string ?{160} client's company name
    enterprise_num string BE[0-9]{10} enterprise number
    representative_name string NA - (deprecated)
    representative_function string NA - (deprecated)
    address string NA - (deprecated)
    address2 string NA - (deprecated)
    zip string NA - (deprecated)
    city string NA - (deprecated)
    is_enterprise_num_validated bool NA - (deprecated)

    bank_accounts

    JSON bank_accounts

    {
  "...": "...",
  "bank_accounts": [
    {
      "iban": "BE20977000017931",
      "coda_mandate_ids": [],
      "bank_id": "CDBXBE33",
      "client_id": "f1147af5-de0a-4125-bb4d-c034b9cc31dc",
      "state": "draft",
      "state_modified_at": "",
      "type": "current",
      "subaccounts": []
    },
    {
      "iban": "BE46977000017948",
      "coda_mandate_ids": [],
      "bank_id": "CDBXBE33",
      "client_id": "f1147af5-de0a-4125-bb4d-c034b9cc31dc",
      "state": "draft",
      "state_modified_at": "",
      "type": "savings",
      "subaccounts": [
        {
          "currency": "EUR",
          "extension": "012"
        }
      ]
    },
    {
      "iban": "BE59974000031202",
      "coda_mandate_ids": [],
      "bank_id": "CDBXBE34",
      "client_id": "f1147af5-de0a-4125-bb4d-c034b9cc31dc",
      "state": "draft",
      "state_modified_at": "",
      "type": "current",
      "subaccounts": []
    },
    {
      "iban": "BE61977000033101",
      "coda_mandate_ids": [],
      "bank_id": "CDBXBE33",
      "client_id": "f1147af5-de0a-4125-bb4d-c034b9cc31dc",
      "state": "draft",
      "state_modified_at": "",
      "type": "current",
      "subaccounts": [
        {
          "currency": "USD",
          "extension": "234"
        }
      ]
    },
    {
      "iban": "BE76974000001893",
      "coda_mandate_ids": [],
      "bank_id": "CDBXBE34",
      "client_id": "f1147af5-de0a-4125-bb4d-c034b9cc31dc",
      "state": "draft",
      "state_modified_at": "",
      "type": "current",
      "subaccounts": []
    },
    {
      "iban": "BE86974000031201",
      "coda_mandate_ids": [],
      "bank_id": "CDBXBE34",
      "client_id": "f1147af5-de0a-4125-bb4d-c034b9cc31dc",
      "state": "draft",
      "state_modified_at": "",
      "type": "savings",
      "subaccounts": []
    }
  ],
  "...": "..."
}

    The client's bank account collection is exposed in the client and identified by the key bank_accounts.

    Field Type Values - format Comment
    iban string BE[0-9]{14} valid iban
    coda_mandate_ids list of string NA - (deprecated)
    bank_id string ?{20} BIC of the bank account
    client_id string uuid Client identifier
    state string see bank account states description below
    state_modified_at string NA - (deprecated)
    type string "savings", "current" see bank account types description below
    subaccounts list of Subaccounts see Subaccounts description below

    bank account states description:

    bank account types description:

    Subaccounts description

    Some bank accounts have different subaccounts for different currencies and other organisational purposes, those are listed in the subaccounts field and have the following format

    Field Type Values - format Comment
    currency string ?{3} Currency Symbol or empty string "EUR", "USD", ...
    extension string The extension for this subaccount if any, usually a 3 digit number.

    bank

    JSON bank

    {
  "bank_id": "CDBXBE34",
  "abbreviation": "CBX2",
  "name": "Coda bank 2",
  "twikey_supported": false
}
    Field Type Values - format Note
    bank_id string ?{20} Bank identifier (BIC)
    abbreviation string ?{4} Bank abbreviation
    name string ?{100} Name of the bank
    twikey_supported bool Indicates if the bank supports digital signature.
    In this case, the twikey_url is provided in the mandate

    Common endpoints

    fiduciaries

    Method HTTP request Note
    list GET <api_prefix>/fiduciaries/ Lists the fiduciaries related to the authenticated user
    get GET <api_prefix>/fiduciaries/<fiduciary_id>/ Gets a given fiduciary by id

    List all fiduciaries

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password>  "https://sandbox-api.codabox.com/v2/fiduciaries/"

    The above command returns JSON structured like this:

    [
  {
    "id": "91f6fa60-23d6-48c0-b59f-5debf369dca0",
    "name": "fiduciary 1",
    "legal_entity": {
      "name": "fiduciary 1",
      "enterprise_num": "BE0010013269",
      "is_enterprise_num_validated": true,
      "representative_name": "Representative",
      "representative_function": "Director",
      "address": "fiduciary 1 address",
      "address2": "",
      "zip": "1000",
      "city": "Bruxelles"
    },
    "contact_name": "contact fiduciary 1",
    "contact_email": "contact@fiduciary1.com",
    "language": "fr",
    "website_url": "",
    "allows_social_mandates": true,
    "allows_doccle_delivery": true,
    "allows_purchase_invoice_mandate": true,
    "allows_client_delivery": true,
    "services": [
      {
        "id": "cba943b4-4b44-4f3a-8cdf-02bac74fb876",
        "type": "soda-delivery",
        "fiduciary_id": "91f6fa60-23d6-48c0-b59f-5debf369dca0",
        "state": "invoiced"
      }
    ],
    "delegates_mandate_delivery": true,
    "software": {
      "name": "software_name",
      "slug": "software_slug",
      "supported_services": ["soda-delivery"]
    }
  },
  {
    "id": "2e200aea-2077-407d-820f-566de090c919",
    "name": "fiduciary 2",
    "legal_entity": {
      "name": "fiduciary 2",
      "enterprise_num": "BE0010020395",
      "is_enterprise_num_validated": true,
      "representative_name": "Representative",
      "representative_function": "Director",
      "address": "fiduciary 2 address",
      "address2": "",
      "zip": "1000",
      "city": "Bruxelles"
    },
    "contact_name": "contact fiduciary 2",
    "contact_email": "contact@fiduciary2.com",
    "language": "fr",
    "website_url": "",
    "allows_social_mandates": false,
    "allows_doccle_delivery": false,
    "allows_purchase_invoice_mandate": false,
    "allows_client_delivery": false,
    "services": [
      {
        "id": "cba943b4-4b44-4f3a-8cdf-02bac74fb876",
        "type": "soda-delivery",
        "fiduciary_id": "91f6fa60-23d6-48c0-b59f-5debf369dca0",
        "state": "invoiced"
      }
    ],
    "delegates_mandate_delivery": false,
    "software": {
      "name": "software_name",
      "slug": "software_slug",
      "supported_services": ["soda-delivery"]
    }
  }
]

    Lists the fiduciaries related to the authenticated user.

    GET <api_prefix>/fiduciaries/

    Get a fiduciary

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password>  "https://sandbox-api.codabox.com/v2/fiduciaries/91f6fa60-23d6-48c0-b59f-5debf369dca0/"

    The above command returns JSON structured like this:

    {
  "id": "91f6fa60-23d6-48c0-b59f-5debf369dca0",
  "name": "fiduciary 1",
  "legal_entity": {
    "name": "fiduciary 1",
    "enterprise_num": "BE0010013269",
    "is_enterprise_num_validated": true,
    "representative_name": "Representative",
    "representative_function": "Director",
    "address": "fiduciary 1 address",
    "address2": "",
    "zip": "1000",
    "city": "Bruxelles"
  },
  "contact_name": "contact fiduciary 1",
  "contact_email": "contact@fiduciary1.com",
  "language": "fr",
  "website_url": "",
  "allows_social_mandates": true,
  "allows_doccle_delivery": true,
  "allows_purchase_invoice_mandate": true,
  "allows_client_delivery": true,
  "services": [
    {
      "id": "cba943b4-4b44-4f3a-8cdf-02bac74fb876",
      "type": "soda-delivery",
      "fiduciary_id": "91f6fa60-23d6-48c0-b59f-5debf369dca0",
      "state": "invoiced"
    }
  ],
  "delegates_mandate_delivery": false,
  "software": {
    "name": "software_name",
    "slug": "software_slug",
    "supported_services": ["soda-delivery"]
  }
}

    GET <api_prefix>/fiduciaries/<fiduciary_id>/

    Gets a specific fiduciary by id.

    URL Parameters

    Field Type Values - format Required ? Comment
    fiduciary_id string uuid x id of the fiduciary

    clients

    Method HTTP request Note
    list GET <api_prefix>/clients/ Lists all clients of all fiduciaries
    get GET <api_prefix>/clients/<client_id>/ Gets the specified client by id

    List clients

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/clients/"

    The above command returns JSON structured like this:

    [
  {
  "id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
  "fiduciary_id": "bfb564f3-dba8-4d90-b84d-335212ef5484",
  "legal_entity": {
    "name": "Client X",
    "enterprise_num": "BE0840559537",
    "is_enterprise_num_validated": false,
    "representative_name": "no name",
    "representative_function": "no function",
    "address": "no address",
    "address2": "no address",
    "zip": "no zip",
    "city": "no city"
  },
  "client_code": "CODABOX-01",
  "contact_name": "no name",
  "contact_email": "no email",
  "purchase_invoice_email": "no email",
  "language": "NA",
  "exact_email": "no email",
  "coda_mandates": [ ],
  "bank_accounts": [
    {
      "iban": "BE46977000017948",
      "coda_mandate_ids": [ ],
      "bank_id": "CDBXBE33",
      "client_id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
      "state": "draft",
      "state_modified_at": "",
      "type": "savings",
      "subaccounts": [
        {
          "currency": "USD",
          "extension": 234
        }
      ]
    }
  ],
  "social_mandates": [],
  "purchase_invoice_mandates": [],
  "state": "no state",
  "purchase_invoice_transmission_mandates": [],
  "services": [],
  "current_purchase_invoice_mandate_state": "no state",
  "delivery_mode": "no mode",
  "doccle_link_connect": "no link",
  "mycodabox_url": "no url",
  "state_modified_at": {},
  "zoomit_ibans": [],
  "mycodabox_access_state": "no state",
  "purchase_invoice_service": [],
  "is_purchase_invoice_delivery_via_push_blocked": false
}
]

    GET <api_prefix>/clients/

    Lists the clients related to all fiduciaries linked the authenticated user.

    Get a client

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/clients/1a779bc4-d4ac-49eb-86d4-d105b94f6025/"

    The above command returns JSON structured like this:

    {
  "id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
  "fiduciary_id": "bfb564f3-dba8-4d90-b84d-335212ef5484",
  "legal_entity": {
    "name": "Client X",
    "enterprise_num": "BE0840559537",
    "is_enterprise_num_validated": false,
    "representative_name": "no name",
    "representative_function": "no function",
    "address": "no address",
    "address2": "no address",
    "zip": "no zip",
    "city": "no city"
  },
  "client_code": "CODABOX-01",
  "contact_name": "no name",
  "contact_email": "no email",
  "purchase_invoice_email": "no email",
  "language": "NA",
  "exact_email": "no email",
  "coda_mandates": [],
  "bank_accounts": [
    {
      "iban": "BE46977000017948",
      "coda_mandate_ids": [],
      "bank_id": "CDBXBE33",
      "client_id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
      "state": "draft",
      "state_modified_at": "",
      "type": "savings",
      "subaccounts": [
        {
          "currency": "USD",
          "extension": 234
        }
      ]
    }
  ],
  "social_mandates": [],
  "purchase_invoice_mandates": [],
  "state": "no state",
  "purchase_invoice_transmission_mandates": [],
  "services": [],
  "current_purchase_invoice_mandate_state": "no state",
  "delivery_mode": "no mode",
  "doccle_link_connect": "no link",
  "mycodabox_url": "no url",
  "state_modified_at": {},
  "zoomit_ibans": [],
  "mycodabox_access_state": "no state",
  "purchase_invoice_service": [],
  "is_purchase_invoice_delivery_via_push_blocked": false
}

    GET <api_prefix>/clients/<client_id>/

    Gets a specific client.

    URL Parameters

    Field Type Values - format Required ? Comment
    client_id string uuid x id of the client

    Banks

    Method HTTP request Note
    list GET <api_prefix>/banks/ Lists the CodaBox's supported banks
    get GET <api_prefix>/banks/<bank_id>/ Gets a bank (bank_id = BIC)

    List supported banks

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/banks/"

    The above command returns JSON structured like this:

    [
  {
    "bank_id": "CDBXBE33",
    "abbreviation": "",
    "name": "Coda bank 1",
    "twikey_supported": true
  },
  {
    "bank_id": "CDBXBE34",
    "abbreviation": "",
    "name": "Coda bank 2",
    "twikey_supported": false
  }
]

    GET <api_prefix>/banks/

    Lists all CodaBox's supported banks

    Note: to be able to order a bank account mandate, the bank account must belong to a supported bank.

    Get a bank

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/banks/CDBXBE33/"

    The above command returns JSON structured like this:

    {
  "bank_id": "CDBXBE33",
  "abbreviation": "",
  "name": "Coda bank 1",
  "twikey_supported": true
}

    GET <api_prefix>/banks/<bank_id>/

    Get a specific bank.

    URL Parameters

    Field Type Values - format Required ? Comment
    bank_id string x id of the bank (bic)

    social-welfare-offices

    Method HTTP request Note
    list GET <api_prefix>/social-welfare-offices/ Lists the CodaBox's supported social welfares
    get GET <api_prefix>/social-welfare-offices/<id>/ Gets a social welfare

    List supported social welfares

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/social-welfare-offices/"

    The above command returns JSON structured like this:

    [
  {
    "name": "Acerta",
    "abbreviation": "Acer",
    "social_welfare_id": "acerta"
  },
  {
    "name": "ADMB",
    "abbreviation": "ADMB",
    "social_welfare_id": "admb"
  },
  {
    "name": "Group S",
    "abbreviation": "Grou",
    "social_welfare_id": "group_s"
  }
]

    GET <api_prefix>/social-welfare-offices/

    Lists all CodaBox's supported social offices

    Get a social office

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/social-welfare-offices/acerta/"

    The above command returns JSON structured like this:

    {
  "name": "Acerta",
  "abbreviation": "Acer",
  "social_welfare_id": "acerta"
}

    GET <api_prefix>/social-welfare-offices/<social_welfare_id>/

    Get a specific social office.

    URL Parameters

    Field Type Values - format Required ? Comment
    social_welfare_id string uuid x id of the social office

    Get Documents

    Introduction Get Documents

    The following API resources allow to obtain documents from CodaBox on behalf of a fiduciary or a fiduciary's client.

    all available document models and their formats:

    document model formats Comment
    coda cod classic coda file
    coda xml xml format is only allowed for invoicing software (xml description)
    coda pdf
    soda xml xml format of the soda file
    soda pdf
    purchase_invoice xml xml is an UBL file of type invoice or credit-note
    purchase_invoice pdf
    sales_invoice xml xml is an UBL file of type invoice or credit-note
    sales_invoice pdf

    Each API call must follow the authentication specifications.

    Authorization to access the following resources depends on permissions related to the user's credentials used to perform the requests and related to the fiduciary or the fiduciary's client.

    In case of unauthorized error, please contact CodaBox to fix this issue at api@codabox.com.

    This part of the API allow to :

    Definitions:

    Flow:

    The typical flow to obtain all the documents for each feed_client listed in a pod-client is depicted below:

    Data Model

    Accessing get documents endpoints

    3 use cases leads to get access to get documents endpoints.

    Accounting softwares

    If the third party is an accounting software the accountant must request a TOKEN to the CodaBox support. The CodaBox support will manually provide the TOKEN to the accountant.

    In this case, the related credentials will give access to the documents of all fiduciary's clients.

    For integration tests, a fiduciary TOKEN can be requested to api@codabox.com. Several dummy clients with dummy documents will be accessible.

    Invoicing softwares

    If the third party is an invoicing software, the sales invoices flow allows the integrator to get the Coda files of a unique client.

    In this use case, requesting a TOKEN must be triggered by the client's invoicing software through a specific endpoint. If the request is successful, the TOKEN is sent to the email address of the client.

    See the following section.

    FiduciaryClient' softwares

    If the third party is a software dedicated to the fiduciary' client, a TOKEN can be requested by using a specific endpoint.

    In this use case, requesting a TOKEN must be triggered by the client's software through a specific endpoint. If the request is successful, the TOKEN is sent to the email address of the client.

    See the following section

    Available resources for get documents process

    Environment <api_prefix>
    Staging https://sandbox-api.codabox.com/v2

    pod-client

    Method HTTP request Note
    get GET <api_prefix>/delivery/pod-client/ Get the pod-client related to the authenticated user

    feed

    Method HTTP request Note
    get GET <api_prefix>/delivery/feed/<id>/ Get the feed_entries of a specified feed_client
    get GET <api_prefix>/delivery/redownload-feed/<id>/ Get the redownload feed of a specified feed_client
    put PUT <api_prefix>/delivery/feed/<id>/ Mark a document as downloaded in the download feed
    put PUT <api_prefix>/delivery/redownload-feed/<id>/ Mark a document as downloaded in the redownload feed

    download

    Method HTTP request Note
    get GET <api_prefix>/delivery/download/<feed_index>/<format>/ Download a document from the download feed
    get GET <api_prefix>/delivery/redownload/<feed_index>/<format>/ Download a document from the redownload feed

    Fiduciaries

    Method HTTP request Note
    list GET <api_prefix>/fiduciaries/ Lists the fiduciaries related to the authenticated user
    get GET <api_prefix>/fiduciaries/<fiduciary_id>/ Gets a given fiduciary by id

    fiduciary data model

    clients

    Method HTTP request Note
    list GET <api_prefix>/clients/ Lists all clients of all fiduciaries
    get GET <api_prefix>/clients/<client_id>/ Gets the specified client by id

    client data model

    JSON fields description

    pod-client

    pod-client

    {
  "id": 9,
  "fetch_delay": 120,
  "allowed_formats": {
    "coda": ["cod", "pdf", "xml"],
    "soda": ["pdf", "xml"],
    "purchase_invoice": ["pdf", "xml"],
    "sales_invoice": ["pdf", "xml"],
    "expense": []
  },
  "feed_clients": [
    {
      "id": 889,
      "client_id": "3fb18ad1-cb7e-4cc7-8ba1-ad1051ebeb42",
      "client_name": "Client 1",
      "client_code": "CLIENT1",
      "fiduciary_id": "e9ce180a-b35a-4bc8-a2b6-18ee23857b07",
      "target_root_state": "default",
      "delivery_config": null
    },
    {
      "id": 890,
      "client_id": "ac44f888-4aee-4471-aeaf-476d67c082e9",
      "client_name": "Client 2",
      "client_code": "CLIENT2",
      "fiduciary_id": "e9ce180a-b35a-4bc8-a2b6-18ee23857b07",
      "target_root_state": "default",
      "delivery_config": null
    },
    {
      "id": 891,
      "client_id": "02fdc400-6c93-4c9d-a3d5-f9ad7a10e2a9",
      "client_name": "Client 3",
      "client_code": "CLIENT3",
      "fiduciary_id": "21e3c8ba-7963-4dae-827f-17610eb24dc5",
      "target_root_state": "default",
      "delivery_config": null
    }
  ]
}

    Data Model

    Field Type Values - format Note
    id number pod-client identifier
    fetch_delay number Not applicable
    allowed_formats JSON dictionary key = document_model (coda,soda,invoice)
    feed_clients JSON list of fiduciary's client

    formats

    Field Type Values - format Note
    coda list of string cod, pdf, xml formats for CODA document
    soda list of string xml, pdf formats for SODA document
    purchase_invoice list of string xml, pdf formats for purchase invoice document
    sales_invoice list of string xml, pdf formats for sales invoice document

    feed_client

    feed_client

    {
  "id": 889,
  "client_id": "3fb18ad1-cb7e-4cc7-8ba1-ad1051ebeb42",
  "client_name": "Client 1",
  "client_code": "CLIENT1",
  "fiduciary_id": "e9ce180a-b35a-4bc8-a2b6-18ee23857b07",
  "target_root_state": "default",
  "delivery_config": null
}
    Field Type Values - format Note
    id number integer feed_client identifier (= id of the feed)
    client_id number uuid fiduciary's client
    client_name string ?{100} name of the client
    client_code string ?{50} client external identifier - external reference to used by third party
    fiduciary_id string uuid fiduciary identifier
    target_root_state string ?{50} Not applicable
    delivery_config JSON Not applicable

    feed

    feed

    {
  "id": 890,
  "type": "download",
  "feed_entries": [
    {
      "feed_index": "99cf252a-e4d3-40ab-9cc9-a0672c1512be",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 1,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE32974000031203",
        "first_statement_number": 1,
        "movement_count": 12,
        "extension_zone": "035"
      }
    },
    {
      "feed_index": "96c2655a-d02d-49de-a7e1-13b38f060665",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 1,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE13974000003415",
        "first_statement_number": 1,
        "movement_count": 1,
        "extension_zone": null
      }
    },
    {
      "feed_index": "062c3dfd-6ca9-4c9e-9302-8a237bbf244d",
      "document_model": "soda",
      "metadata": {
        "accounting_period": "201508",
        "vat_number": "BE0010021583",
        "file_counter": "0001",
        "social_welfare_id": "group_s",
        "creation_date": "2015-10-23"
      }
    },
    {
      "feed_index": "c4246d00-059b-4208-b6eb-dd0ebbc79a88",
      "document_model": "purchase_invoice",
      "metadata": {
        "file_counter": 3,
        "invoice_currency": "EUR",
        "invoice_date": "2015-10-29",
        "invoice_due_date": "2015-11-30",
        "bank_account_bic": "CDBXBE33",
        "invoice_amount": "299.60",
        "supplier": "tresfase",
        "payment_reference": "15700004",
        "bank_account_number": "BE03974000000103",
        "invoice_reference": "FACT20151029",
        "ubl_type": "invoice",
        "source_format": "ubl",
        "source_provider": "provider 1"
      }
    },
    {
      "feed_index": "47d4d96e-cd53-4133-9c92-a84b6042e17d",
      "document_model": "sales_invoice",
      "metadata": {
        "file_counter": 2,
        "invoice_currency": "EUR",
        "invoice_date": "2016-03-01",
        "invoice_folder": "folder2",
        "invoice_due_date": null,
        "invoice_reference": "CRED-1600002",
        "bank_account_bic": null,
        "invoice_amount": "200.00",
        "payment_reference": null,
        "bank_account_number": null,
        "ubl_type": "credit-note"
      }
    }
  ]
}
    Field Type Values - format Note
    id number feed_client identifier
    type string download, redownload Indicates de type of the feed
    feed_entries list of feed entry see below

    feed_entry

    Field Type Values - format Note
    feed_index string uuid4 feed_client identifier
    document_model string (*) See list of document_model below
    metadata JSON Meta data structure depends of the model of document

    List of available document_model:

    feed_entry metadata by document_model

    Metadata differs according to the document_model

    coda

    coda metadata

    {
  "feed_index": "99cf252a-e4d3-40ab-9cc9-a0672c1512be",
  "document_model": "coda",
  "metadata": {
    "last_statement_number": 1,
    "new_balance_date": "2016-03-10",
    "bank_id": "CDBXBE33",
    "currency": "EUR",
    "iban": "BE32974000031203",
    "first_statement_number": 1,
    "movement_count": 12,
    "extension_zone": "035"
  }
}
    Field Type Values - format Note
    first_statement_number number uuid4 first statement number
    last_statement_number number coda,soda,invoice last statement number - NB = first statement number if only one statement in the CODA file
    new_balance_date string yyyy-mm-dd date of the last statement
    iban string BE[0-9]14 bank account number (iban)
    bank_id string Bank identifier
    currency string Bank account currency
    movement_count number number of movements in the coda file
    extension_zone string ?{3} extension zone (*)

    extension_zone

    When a coda file contains an extension zone, the bank account + the extension zone must be considered as a distinct bank account regarding the old balance, the new balance, the coda paper sequence and the coda sequence. For more information about extension zone see: febelfin documentation

    Currently, only ING uses the extension_zone

    soda

    soda metadata

    {
  "feed_index": "062c3dfd-6ca9-4c9e-9302-8a237bbf244d",
  "document_model": "soda",
  "metadata": {
    "accounting_period": "201508",
    "vat_number": "BE0010021583",
    "file_counter": "0001",
    "social_welfare_id": "group_s",
    "creation_date": "2015-10-23"
  }
}
    Field Type Values - format Note
    vat_number string BE{2}[0-9]10 vat number
    social_welfare_id string securex, ... Social welfare identifier
    file_counter number auto incremented number
    accounting_period string yyyymm Accounting period
    creation_date string yyyy-mm-dd Original file creation date (by social welfare)

    purchase_invoice

    purchase_invoice metadata

    {
  "feed_index": "c4246d00-059b-4208-b6eb-dd0ebbc79a88",
  "document_model": "purchase_invoice",
  "metadata": {
    "file_counter": 3,
    "invoice_currency": "EUR",
    "invoice_date": "2015-10-29",
    "invoice_due_date": "2015-11-30",
    "bank_account_bic": "CDBXBE33",
    "invoice_amount": "299.60",
    "supplier": "tresfase",
    "payment_reference": "15700004",
    "bank_account_number": "BE03974000000103",
    "invoice_reference": "FACT20151029",
    "ubl_type": "invoice",
    "source_format": "ubl",
    "source_provider": "provider 1"
  }
}
    Field Type Values - format Note
    file_counter number auto incremented number
    invoice_date string yyyy-mm-dd date of the invoice
    supplier string supplier of the invoice
    invoice_currency string currency of the invoice
    invoice_due_date string yyyy-mm-dd invoice's due date
    invoice_amount string invoice's amount
    payment_reference string payment reference
    bank_account_number string bank account of the provider
    bank_account_bic string bic of the supplier's bank account
    invoice_reference string invoice reference (= invoice_number)
    ubl_type string invoice,credit-note type of ubl file
    source_format string pdf (*), ubl original format of the invoice
    source_provider string name of the provider of the invoice

    Note:

    If the source_format value is pdf, only the pdf format is available for this document.

    Trying to download the xml format (UBL) of the document will return an HTTP 404 (not found).

    sales_invoice

    sales_invoice metadata

    {
  "feed_index": "47d4d96e-cd53-4133-9c92-a84b6042e17d",
  "document_model": "sales_invoice",
  "metadata": {
    "file_counter": 2,
    "invoice_currency": "EUR",
    "invoice_date": "2016-03-01",
    "invoice_folder": "folder2",
    "invoice_due_date": null,
    "invoice_reference": "FACT-1600002",
    "bank_account_bic": null,
    "invoice_amount": "200.00",
    "payment_reference": null,
    "bank_account_number": null,
    "ubl_type": "credit-note"
  }
}
    Field Type Values - format Note
    file_counter number auto incremented number
    invoice_date string yyyy-mm-dd date of the invoice
    invoice_currency string currency of the invoice
    invoice_due_date string yyyy-mm-dd invoice's due date
    invoice_amount string invoice's amount
    payment_reference string payment reference
    bank_account_number string bank account of the provider
    bank_account_bic string bic of the supplier's bank account
    invoice_reference string invoice reference (= invoice_number)
    invoice_folder string folder of the invoice (accountant book)
    ubl_type string invoice,credit-note type of ubl file

    Get pod-client

    Command:

    curl \
  -H "X-Software-Company: <your_x_software_company>" \
  sL -u login:password "https://sandbox-api.codabox.com/v2/delivery/pod-client/"

    The above command returns JSON structured like this:

    {
  "id": 9,
  "fetch_delay": 120,
  "allowed_formats": {
    "coda": ["cod", "pdf", "xml"],
    "soda": ["pdf", "xml"],
    "purchase_invoice": ["pdf", "xml"],
    "sales_invoice": ["pdf", "xml"],
    "expense": []
  },
  "feed_clients": [
    {
      "id": 889,
      "client_id": "3fb18ad1-cb7e-4cc7-8ba1-ad1051ebeb42",
      "client_name": "Client 1",
      "client_code": "CLIENT1",
      "fiduciary_id": "e9ce180a-b35a-4bc8-a2b6-18ee23857b07",
      "target_root_state": "default",
      "delivery_config": null
    },
    {
      "id": 890,
      "client_id": "ac44f888-4aee-4471-aeaf-476d67c082e9",
      "client_name": "Client 2",
      "client_code": "CLIENT2",
      "fiduciary_id": "e9ce180a-b35a-4bc8-a2b6-18ee23857b07",
      "target_root_state": "default",
      "delivery_config": null
    },
    {
      "id": 891,
      "client_id": "02fdc400-6c93-4c9d-a3d5-f9ad7a10e2a9",
      "client_name": "Client 3",
      "client_code": "CLIENT3",
      "fiduciary_id": "21e3c8ba-7963-4dae-827f-17610eb24dc5",
      "target_root_state": "default",
      "delivery_config": null
    }
  ]
}

    GET <api_prefix>/delivery/pod-client/

    Get the feed

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>"
    -sL -u login:password "https://sandbox-api.codabox.com/v2/delivery/feed/93/"

    The above command returns JSON structured like this:

    {
  "id": 890,
  "type": "download",
  "feed_entries": [
    {
      "feed_index": "99cf252a-e4d3-40ab-9cc9-a0672c1512be",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 1,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE32974000031203",
        "first_statement_number": 1,
        "movement_count": 12,
        "extension_zone": "035"
      }
    },
    {
      "feed_index": "96c2655a-d02d-49de-a7e1-13b38f060665",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 1,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE13974000003415",
        "first_statement_number": 1,
        "movement_count": 1,
        "extension_zone": null
      }
    },
    {
      "feed_index": "062c3dfd-6ca9-4c9e-9302-8a237bbf244d",
      "document_model": "soda",
      "metadata": {
        "accounting_period": "201508",
        "vat_number": "BE0010021583",
        "file_counter": "0001",
        "social_welfare_id": "group_s",
        "creation_date": "2015-10-23"
      }
    },
    {
      "feed_index": "c4246d00-059b-4208-b6eb-dd0ebbc79a88",
      "document_model": "purchase_invoice",
      "metadata": {
        "file_counter": 3,
        "invoice_currency": "EUR",
        "invoice_date": "2015-10-29",
        "invoice_due_date": "2015-11-30",
        "bank_account_bic": "CDBXBE33",
        "invoice_amount": "299.60",
        "supplier": "tresfase",
        "payment_reference": "15700004",
        "bank_account_number": "BE03974000000103",
        "invoice_reference": "FACT20151029",
        "ubl_type": "invoice",
        "source_format": "ubl",
        "source_provider": "provider 1"
      }
    },
    {
      "feed_index": "47d4d96e-cd53-4133-9c92-a84b6042e17d",
      "document_model": "sales_invoice",
      "metadata": {
        "file_counter": 2,
        "invoice_currency": "EUR",
        "invoice_date": "2016-03-01",
        "invoice_folder": "folder2",
        "invoice_due_date": null,
        "invoice_reference": "FACT-1600002",
        "bank_account_bic": null,
        "invoice_amount": "200.00",
        "payment_reference": null,
        "bank_account_number": null,
        "ubl_type": "invoice"
      }
    }
  ]
}

    GET <api_prefix>/delivery/feed/<id>/

    URL Parameters

    Field Type Values - format Required ? Comment
    id number x id of the feed_client

    Get the redownload_feed

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>"
    -sL -u login:password "https://sandbox-api.codabox.com/v2/delivery/redownload-feed/93/"

    The above command returns JSON structured like this:

    {
  "id": 890,
  "type": "redownload",
  "feed_entries": [
    {
      "feed_index": "9939b0bb-c50c-4b78-94a7-e3a2448df5b4",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 2,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE32974000031203",
        "first_statement_number": 2,
        "movement_count": 10,
        "extension_zone": "035"
      }
    }
  ]
}

    GET <api_prefix>/delivery/redownload-feed/<id>/

    URL Parameters

    Field Type Values - format Required ? Comment
    id number x id of the feed_client

    Download a document in a given format

    Download a coda document from the download feed

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/download/ab021947-63aa-4fb4-8134-05b9384b9e71/cod/" -o "coda.cod"

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/download/ab021947-63aa-4fb4-8134-05b9384b9e71/pdf/" -o "coda.pdf"

    Download a coda document from the redownload-feed

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/redownload/02cb306f-d68f-4f61-97a5-40734e1b614d/cod/" -o "coda.cod"

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/redownload/02cb306f-d68f-4f61-97a5-40734e1b614d/pdf/" -o "coda1.pdf"

    Download other type of document

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/download/26d2ea6d-20db-4fe5-961f-0c62cfef1bfd/xml/" -o "soda2.xml"

     curl \
     -H "X-Software-Company:<your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/download/3ecd1940-db62-4bf1-a01b-1643d94d509c/xml/" -o "invoiceP.xml"

    Only for CODAPlus

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/download/ab021947-63aa-4fb4-8134-05b9384b9e71/xml/" -o "coda1.xml"

    GET <api_prefix>/delivery/<feed_type>/<feed_index>/<format>/

    URL Parameters

    Field Type Values - format Required ? Comment
    feed_type string download, redownload x indicates the feed from wich comes the document, the value is found in the type json field of the feed
    feed_index string uuid x feed_index of the feed_entry
    format string cod, pdf (*), xml x format are found in pod-client allowed_formats dictionary

    Note1: a join can be done between the document_model in the feed_entry and de key of allowed_formats dictionary in the pod-client in order to know which format are allowed.

    Note2: The allowed_formats dictionary at the pod-client level define the authorized format for a given document_model. If the format is not allowed, the response returns an HTTP 403 error.

    Note3 (): for document_model of type *purchase_invoice, if the source_format value is pdf, only the pdf format is available for this document: Trying to download the xml format (UBL) of the document will return an *HTTP 404* (not found).

    document_model allowed formats Comment
    coda cod, pdf, xml xml format is only allowed for invoicing software (xml description)
    soda xml, pdf
    purchase_invoice xml, pdf xml is an ubl file of type invoice or credit-note
    sales_invoice xml, pdf xml is an ubl file of type invoice or credit-note

    HTTP 200 :

    HTTP/1.1 200 OK
Server: nginx/1.1.19
Date: Tue, 13 Sept 2015 08:46:58 GMT
Content-Type: application/pdf
Content-Length: 156699
Last-Modified: Tue, 13 Oct 2015 08:45:57 GMT
Accept-Ranges: bytes
Strict-Transport-Security: max-age=15768000

    The Content-Length indicates the length (in Byte) of the downloaded file. It is recommended to check the file length to ensure that the downloaded file is not corrupted.

    CodaBox file naming convention.

    Update the feed_offset

    Update de feed_offset of the feed

    curl \
    -X PUT -H "X-Software-Company: <your_x_software_company>" \
    -H "Content-Type: application/json" -d \
    '
    {
        "feed_offset":"ab021947-63aa-4fb4-8134-05b9384b9e71"
    }' \
    -sL -u login:password "https://sandbox-api.codabox.com/v2/delivery/feed/4/"

    Update de feed_offset of the redownload-feed

    curl \
    -X PUT -H "X-Software-Company: <your_x_software_company>" \
    -H "Content-Type: application/json" -d \
    '
    {
        "feed_offset":"ab021947-63aa-4fb4-8134-05b9384b9e71"
    }' \
    -sL -u login:password "https://sandbox-api.codabox.com/v2/delivery/redownload-feed/4/"

    Request body :

    {
  "feed_offset": "ab021947-63aa-4fb4-8134-05b9384b9e71"
}

    The above command returns JSON structured like this:

    {
  "id": 4,
  "feed_offset": "ab021947-63aa-4fb4-8134-05b9384b9e71"
}

    Each time that all needed files have been successfully downloaded for a given document (feed_entry), it is requested to indicate that the document has been downloaded. By updating the feed_offset, the feed_entry will be permanently removed from the feed on the next feed request.

    Depending of the type of feed (download or redownload), the endpoint to update the feed is different:

    feed: PUT <api_prefix>/delivery/feed/<id>/

    redownload_feed: PUT <api_prefix>/delivery/redownload-feed/<id>/

    Note: All json sent to CodaBox API must be encoded in UTF-8

    URL Parameters

    Field Type Values - format Required ? Comment
    id number x id of the feed_client (cf pod-client)

    Body Fields description

    Field Type Values - format Required ? Comment
    feed_offset string uuid x feed_index of the downloaded documents

    Request an access TOKEN for a given client

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -H "Content-Type: application/json" -d \
    '{
        "vat":"BE0010015348"
    }' \
    -sL "https://sandbox-api.codabox.com/v2/request-access-token/get-document-software/"

    Request body:

    {
   "vat":"BE0010015348"
}

    return HTTP/1.1 201 CREATED

    {
  "vat": "BE0010015348",
  "email": "te...@...com"
}

    POST <api_prefix>/request-access-token/get-document-software/

    Third party may be authorized to get a TOKEN for a specific client.

    As for get-credential endpoint, request-access-token does not required to be authenticated.

    The third party must be authorized to request an access token otherwise the response returned the following message (HTTP 403): The software can not be found, is not active or does not have the permission to request access to get documents.

    Requesting an access token involves to provide the VAT number of the client and the X-Software-Company key provided by CodaBox to the third party. If the request is successful, the client will received a token by mail.

    The client must provide the token in its software. The software then call the get-credentials endpoint with the provided token as described here. Credentials must be stored and then used for each call together with the X-Software-Company key. From this point, the software is able to consume endpoints dedicated to the get documents process.

    Note1: although /request-access-token/get-document-software/ should be called only one time for a given VAT number (client), if the same call is performed, a new token is sent back to the client's email address. The get-credential endpoint can be used again to retrieve the new credentials.

    For testing purpose on sandbox environment, please send to CodaBox at api@codabox.com an email address where CodaBox will send the dummy client's TOKEN. Please mention the test client VAT numbers (x 2) provided for testing purpose and/or your X-Software-Company key provided by CodaBox.

    Body Fields description

    Field Type Values - format Required ? Comment
    vat string BE[0-9]{10} x VAT of the client

    Returned payload

    In case of success, the returned payload exposes the vat and a part of the email recipient where the token has been sent.

    The email address is obfuscated as follow:

    HTTP 400 errors

    Depending on several business object values, the /request-access-token/get-document-software/ could be rejected, find below HTTP 400 error messages.

    Validation errors: HTTP 400 key vat example for sandbox
    Object with vat=bad does not exist vat BE0123456789
    This field is required. vat
    This client has no Coda mandates. non_field_errors
    This client needs activation non_field_errors BE0010016140
    The client's fiduciary needs activation non_field_errors BE0010014952
    Client's email is missing non_field_errors BE0010014655
    Client's contact is missing non_field_errors BE0010014754
    Client's contact function is missing non_field_errors BE0010015546
    HTTP 403: Forbidden key
    The software can not be found, is not active or does not have the permission to request access to get documents detail

    Data Model

    Sales invoice process: particularities

    Get pod-client

    curl \
  -H "X-Software-Company: <your_x_software_company>" \
  sL -u login:password "https://sandbox-api.codabox.com/v2/delivery/pod-client/"

    feed_clients list contains only one item

    {
  "id": 1,
  "fetch_delay": 120,
  "allowed_formats": {
    "coda": ["cod", "pdf", "xml"],
    "soda": [],
    "purchase_invoice": [],
    "sales_invoice": [],
    "expense": []
  },
  "feed_clients": [
    {
      "id": 10,
      "client_id": "514d1235-58a7-4e73-863e-0c9b5156cc7a",
      "client_name": "client 1",
      "client_code": "CLIENT1",
      "fiduciary_id": "048c1f04-47e5-487d-9697-4b379140a4f3",
      "target_root_state": "default",
      "delivery_config": null
    }
  ]
}

    Get the feed of the fiduciary's client

    curl \
    -H "X-Software-Company: <your_x_software_company>"
    -sL -u login:password "https://sandbox-api.codabox.com/v2/delivery/feed/10/"

    Feed_entry only exposes coda document model

    {
  "id": 10,
  "type": "download",
  "feed_entries": [
    {
      "feed_index": "99cf252a-e4d3-40ab-9cc9-a0672c1512be",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 1,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE32974000031203",
        "first_statement_number": 1,
        "movement_count": 12,
        "extension_zone": "035"
      }
    },
    {
      "feed_index": "96c2655a-d02d-49de-a7e1-13b38f060665",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 1,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE13974000003415",
        "first_statement_number": 1,
        "movement_count": 1,
        "extension_zone": null
      }
    },
    {
      "feed_index": "885e6dbd-785a-42af-a348-816ba38c1cee",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 2,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE13974000003415",
        "first_statement_number": 2,
        "movement_count": 3,
        "extension_zone": null
      }
    },
    {
      "feed_index": "9939b0bb-c50c-4b78-94a7-e3a2448df5b4",
      "document_model": "coda",
      "metadata": {
        "last_statement_number": 2,
        "new_balance_date": "2016-03-10",
        "bank_id": "CDBXBE33",
        "currency": "EUR",
        "iban": "BE32974000031203",
        "first_statement_number": 2,
        "movement_count": 10,
        "extension_zone": "035"
      }
    }
  ]
}

    The allowed format are cod, xml and pdf

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/download/ab021947-63aa-4fb4-8134-05b9384b9e71/cod/" -o "coda.cod"

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/download/ab021947-63aa-4fb4-8134-05b9384b9e71/xml/" -o "coda.xml"

     curl \
     -H "X-Software-Company: <your_x_software_company>" \
     -sL -u <login:password> "https://sandbox-api.codabox.com/v2/delivery/download/ab021947-63aa-4fb4-8134-05b9384b9e71/pdf/" -o "coda.pdf"

    1. Get document is done on behalf of one fiduciary's client. The pod-client endpoint exposes as usual a feed_client list but it will contains only one feed_client item.

      Data Model

    2. In case of sales invoices process, Getting document is restricted to document of type coda (document_model) in any format.

    Sales invoice process is described here.

    File naming convention and folder hierarchy

    Based on metadata define for each document_model, find advised CodaBox file naming conventions and folder's hierarchy

    Document model ubl_type format Destination directory
    coda cod /<client_code>/<new_balance_date.Year>/<iban>/
    coda pdf /<client_code>/<new_balance_date.Year>/<iban>/pdf/
    soda xml /<client*code>/<creation_date.Year>/soda_from*<social_welfare>/
    soda pdf /<client*code>/<creation_date.Year>/soda_from*<social_welfare>/pdf/
    purchase_invoice invoice xml /<client_code>/<invoice_date.Year>/Invoices-IN-01/ (*)
    purchase_invoice invoice pdf /<client_code>/<invoice_date.Year>/Invoices-IN-01/pdf/ (*)
    purchase_invoice credit-note xml /<client_code>/<invoice_date.Year>/Credit-notes-IN-01/ (*)
    purchase_invoice credit-note pdf /<client_code>/<invoice_date.Year>/Credit-notes-IN-01/pdf/ (*)
    sales_invoice invoice xml /<client_code>/<invoice_date.Year>/Invoices-OUT-01/
    sales_invoice invoice pdf /<client_code>/<invoice_date.Year>/Invoices-OUT-01/pdf/
    sales_invoice invoice xml /<client_code>/<invoice_date.Year>/Invoices-OUT-01-<invoice_folder>/
    sales_invoice invoice pdf /<client_code>/<invoice_date.Year>/Invoices-OUT-01-<invoice_folder>/pdf/
    sales_invoice credit-note xml /<client_code>/<invoice_date.Year>/Credit-notes-OUT-01-<invoice_folder>/
    sales_invoice credit-note pdf /<client_code>/<invoice_date.Year>/Credit-notes-OUT-01-<invoice_folder>/pdf/

    Note: for document_model of type purchase_invoice, if the source_format value is pdf:

    Document model ubl_type format source_format Destination directory
    purchase_invoice invoice xml pdf no xml format available (HTTP 404)
    purchase_invoice invoice pdf pdf /<client_code>/<invoice_date.Year>/Invoices-IN-01/
    purchase_invoice credit-note xml pdf no xml format available (HTTP 404)
    purchase_invoice credit-note pdf pdf /<client_code>/<invoice_date.Year>/Credit-notes-IN-01/
    purchase_invoice invoice xml ubl /<client_code>/<invoice_date.Year>/Invoices-IN-01/
    purchase_invoice invoice pdf ubl /<client_code>/<invoice_date.Year>/Invoices-IN-01/
    purchase_invoice credit-note xml ubl /<client_code>/<invoice_date.Year>/Credit-notes-IN-01/
    purchase_invoice credit-note pdf ubl /<client_code>/<invoice_date.Year>/Credit-notes-IN-01/
    Document model ubl_type format Destination directory example
    coda cod /CLIENT4/2015/BE27974000004133/
    coda pdf /CLIENT4/2015/BE27974000004133/pdf/
    soda xml /CLIENT4/2015/soda_from_group_s/
    soda pdf /CLIENT4/2015/soda_from_group_s/pdf
    purchase_invoice invoice xml /CLIENT4/2015/Invoices-IN-01/
    purchase_invoice credit-note xml /CLIENT4/2015/Credit-notes-IN-01/
    sales_invoice invoice xml /CLIENT4/2015/Invoices-OUT-01/
    sales_invoice credit-note xml /CLIENT4/2015/Credit-notes-OUT-01/
    sales_invoice invoice xml /CLIENT4/2015/Invoices-OUT-01-folder1/
    sales_invoice credit-note xml /CLIENT4/2015/Credit-notes-OUT-01-folder1/
    Document model format Document name convention
    coda (*) cod,pdf,xml {0:yyyy}-{1:000}-{2}-{0:yymmdd} OR {0:yyyy}-{1:000}-{3:000}-{2}-{0:yymmdd}
    soda xml,pdf {0:0000}-soda-{1}-{2}-{3:yyyymm}-{4:yyyymmdd}
    purchase_invoice xml {0:yyyy}-{1:00000000}-{2}
    sales_invoice xml {0:yyyy}-{1:00000000}-{2}

    (*) coda xml format is only allowed for invoicing software (sales invoice process).

    Document model Ordered Parameters
    coda new_balance_date, first_statement_number,iban,[last_statement_number]
    soda file_counter, social_welfare_id, vat_number, accounting_period, creation_date
    invoice purchase invoice_date, file_counter, supplier
    invoice sale invoice_date, file_counter, invoice_reference
    Document model Document name examples
    coda 2015-001-BE27974000004133-151023.cod(.pdf)(.xml)
    coda 2015-002-003-BE27974000004133-151024.cod(.pdf)(.xml)
    soda 0001-soda-group_s-BE0010015348-201509-20151023.xml(.pdf)
    purchase_invoice 2015-00000001-proximus.xml(.pdf)
    sales_invoice 2015-00000001-FACT201501.xml(.pdf)

    Errors

    For general errors, for example a JSON parse error, a dictionary with the "detail" key is returned:

    {
  "detail": "Not found."
}
    HTTP Status Code Reason
    400 Bad request (see validation errors)
    401 Unauthorized
    403 Forbidden
    404 Object doesn't exist
    5xx Something is wrong on server side
    HTTP 403 Forbidden key
    This user does not have a pod-client detail
    The software can not be found or is not active detail
    The software can not be found, is not active or is not the one registered for this user detail
    The software can not be found, is not active or does not have the permission to request credentials detail
    The current user is not allowed to access this file detail
    Format "<format>" not allowed detail
    The software can not be found, is not active or does not have the permission to request access to get documents detail
    Transfer has been suspended detail

    feed_offset update

    validation errors: HTTP 400 key
    Offset should be part of the feed's feed entries feed_offset
    This field is required. feed_offset
    This field may not be null feed_offset

    Checklist Get Documents

    Sales Invoices - copy to accountant

    Introduction Sales invoices

    The CodaBox API offers resources to download the coda files of a fiduciary's client and upload the client's sales invoices to CodaBox in order to transfer those invoices in UBL format to the client's fiduciary.

    Each API call must follow the authentication specifications.

    Authorization to access the following resources depends on permissions related to the user credentials used to perform the request and related to the client's fiduciary.

    In case of unauthorized error, please contact CodaBox to fix this issue at api@codabox.com.

    Those API resources allow to:

    Depending on permissions defined for the third party, Coda files could be to downloaded in the following formats:

    Flow for sales invoices process

    Data Model

    Available resources for sales invoices process

    Env <api_prefix>
    Staging https://sandbox-api.codabox.com/v2/

    Request access token

    Method HTTP request Note
    create POST <api_prefix>/request-access-token/invoicing-software/ Request an access token to consume sales invoice endpoints.

    Clients

    Method HTTP request Note
    list GET <api_prefix>/clients/ list the client linked to the authenticated user (*)
    get GET <api_prefix>/clients/<client_id>/ Get the client linked to the authenticated user by id

    Note: in case of a sales invoice process, the list of client will always contain only one item.

    Fiduciaries

    Method HTTP request Note
    list GET <api_prefix>/fiduciaries/ Lists the fiduciaries related to the client
    get GET <api_prefix>/fiduciaries/<fiduciary_id>/ Gets a given fiduciary by id

    Note: in case of a sales invoice process, the list of fiduciary will always contain only one item: the current fiduciary of the client

    Data Model

    Get Coda files

    See Get Documents resources.

    See sales invoice process particularities

    Upload an ubl (xml) file

    Method HTTP request Note
    create POST <api_prefix>/ubl/sales-invoice/upload/ upload an ubl file

    An ubl file can be uploaded. Supported UBL types are restricted to invoice and credit-note

    Request access token

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -H "Content-Type: application/json" -d \
    '{
        "vat":"BE0010015348"
    }' \
    -sL "https://sandbox-api.codabox.com/v2/request-access-token/invoicing-software/"

    Request body:

    {
   "vat":"BE0010015348",
   "email": "je...@...com"
}

    return HTTP/1.1 201 CREATED

    {
  "vat": "BE0010015348",
  "email": "je...@...com"
}

    POST <api_prefix>/request-access-token/invoicing-software/

    As for the get-credentials endpoint, request-access-token does not required the user to be authenticated.

    The third party must be able to request an access token, otherwise the response returns the following message (HTTP 403): The software can not be found, is not active or does not have the permission to request access to sales invoices.

    Data Model

    Requesting an access token involves providing the VAT number of the client and the X-Software-Company key which was provided by CodaBox to the third party. If the request is successful, the client receive a token by mail.

    The client must provide the token in the invoicing software. The invoicing software then calls the get-credentials endpoint with the provided token as described here. Credentials must be stored and then used for each call together with the X-Software-Company key. From this point, invoicing software is able to consume endpoints dedicated to the sales invoices process.

    Note1: although request-access-token should be called only one time for a given VAT number (client), if the same call is performed, a new token is sent back to the client's email address. The get-credential endpoint should used again to retrieve the new credentials.

    For testing purpose on sandbox environment, please send to CodaBox at api@codabox.com an email address where CodaBox will send the dummy client's TOKEN. Please mention the test client VAT numbers (x 2) provided for testing purpose and/or your X-Software-Company key provided by CodaBox.

    Body Fields description

    Field Type Values - format Required ? Comment
    vat string BE[0-9]{10} x VAT of the client

    Returned payload

    In case of success, the returned payload exposes the vat and a part of the email recipient where the token has been sent.

    The email address is obfuscated as follow:

    HTTP 400 errors

    Depending on several business object values, the request-access-token could be rejected, find below HTTP 400 error messages.

    Validation errors: HTTP 400 key vat example for sandbox
    Object with vat=bad does not exist vat BE0123456789
    This field is required. vat
    This client needs activation non_field_errors BE0010016140
    The client's fiduciary needs activation non_field_errors BE0010014952
    Client's email is missing non_field_errors BE0010014655
    Client's contact is missing non_field_errors BE0010014754
    Client's contact function is missing non_field_errors BE0010015546

    Message to show in invoicing software in case of validation errors

    Language Object with vat=bad does not exist
    EN The VAT number you mentioned has not been found in the CodaBox database. Two cases:
    1. Your accountant already receives your CODA files via CodaBox. Please contact the CodaBox support for updating your legal information: support@codabox.com
    2. Your accountant office does not receive your CODA files yet. Please contact your fiduciary/accountant office for activation of your CODA delivery.
    FR Le numéro de TVA introduit n’a pas été trouvé dans la base de données de CodaBox. Deux cas :
    1. Votre comptable reçoit déjà vos CODA via CodaBox. Merci de contacter le support de CodaBox afin de mettre vos données légales à jour : support@codabox.com
    2. Votre comptable ne reçoit pas encore vos CODA via CodaBox. Merci de contacter votre bureau comptable afin d’activer le service de livraison de CODA.
    NL Het BTW nummer dat werd ingegeven werd niet in de database van CodaBox teruggevonden. Twee mogelijk oorzaken:
    1. Uw boekhouder ontvangt uw CODA bestanden al via CodaBox. Gelieve onze support dienst te contacteren om uw wettelijke gegevens te actualiseren: support@codabox.com
    2. Uw boekhouder ontvangt uw CODA bestanden nog niet via CodaBox. Gelieve uw boekhoudkantoor te contacteren om de levering van CODA bestanden te activeren.
    Language The client's fiduciary needs activation
    EN The VAT number you mentioned isn’t linked with an active fiduciary/accountant office in CodaBox database. Please contact your fiduciary/accountant office.
    FR Le numéro de TVA introduit ne correspond pas à un bureau comptable actif dans la base de données de CodaBox. Merci de contacter votre bureau comptable.
    NL Het opgegeven BTW-nummer komt niet overeen met een actief boekhoudkantoor in de CodaBox-databank. Gelieve uw boekhoudkantoor te contacteren.
    Language Client's email is missing
    EN This VAT number is not related to an active e-mail address in CodaBox database. Please contact the CodaBox support for updating your legal information: support@codabox.com
    FR Ce numéro de TVA n’est pas lié à une adresse e-mail active dans la base de données de CodaBox. Merci de contacter le support de CodaBox afin de mettre vos données légales à jour : support@codabox.com
    NL Dit BTW-nummer is niet verbonden met een actief e-mailadres in de CodaBox-databank. Bedankt om contact op te nemen met de support van CodaBox om uw legale gegevens bij te werken: support@codabox.com
    Language This client needs activation
    EN The VAT number mentioned corresponds to a company that has been archived in the CodaBox database (the CODA files are not transmitted to the accountant office anymore). Please contact your fiduciary/accountant office for re-activation.
    FR Le numéro de TVA introduit correspond à une entreprise qui est archivée dans la base de donnée de CodaBox (les fichiers CODA ne sont plus transmis au bureau comptable). Merci de contacter votre bureau comptable pour réactiver cette livraison.
    NL Het opgegeven BTW-nummer is verbonden met een bedrijf dat gearchiveerd is in de CodaBox-databank (de CODA-bestanden worden niet meer geleverd aan het boekhoudkantoor). Gelieve uw boekhoudkantoor te contacteren om de levering te reactiveren.
    Language Client's legal contact name is missing
    EN This VAT number is related to a company without legal representative name. Please contact the CodaBox support for updating your legal information: support@codabox.com
    FR Ce numéro de TVA est lié à une entreprise pour laquelle le nom du représentant légal n’est pas mentionné dans la base de données de CodaBox. Merci de contacter le support de CodaBox afin de mettre vos données légales à jour : support@codabox.com
    NL Dit BTW-nummer is verbonden met een met een bedrijf zonder rechtsgeldig vertegenwoordiger naam in de CodaBox-database. Bedankt om contact op te nemen met de support van CodaBox om uw legale gegevens bij te werken: support@codabox.com
    Language Client's legal contact function is missing
    EN This VAT number is related to a company without legal representative function in CodaBox database. Please contact the CodaBox support for updating your legal information: support@codabox.com
    FR Ce numéro de TVA est lié à une entreprise pour laquelle la fonction du représentant légal n’est pas mentionnée dans la base de données de CodaBox. Merci de contacter le support de CodaBox afin de mettre vos données légales à jour : support@codabox.com
    NL Dit BTW-nummer is verbonden met een met een bedrijf zonder rechtsgeldig vertegenwoordiger functie in de CodaBox-database. Bedankt om contact op te nemen met de support van CodaBox om uw legale gegevens bij te werken: support@codabox.com

    Get credentials

    GET <api_prefix>/get-credentials/<TOKEN>/

    Command :

    curl \
    -H "X-Software-Company: 08d09a20-1a94-4284-9305-375d46a02914" \
    "https://sandbox-api.codabox.com/v2/get-credentials/a19c62be748043449942c12712f42922/"

    The above command returns JSON structured like this:

    {
  "username": "foo",
  "password": "bar"
}

    Once the token has been sent to the client, client's credentials can be retrieved by consuming the get credentials endpoint with the client's TOKEN.

    For more information consult the following section: Authentication.

    Deactivation of the authenticated user

    The following use cases implies the deactivation of the sales invoices authenticated user :

    1. the client is archived by the fiduciary
    2. the fiduciary doesn't agreed anymore with sales invoice process
    3. another third party did performed an request-access-token and a subsequent get-credentials

    In this case, every calls will returned the following error message:

    HTTP 401: User inactive or deleted

    If a request-access-token is performed again for the client, depending on the use cases, the API will return:

    1. HTTP 400: This client needs activation
    2. HTTP 400: The fiduciary is not Sales Invoices compliant
    3. if all conditions are met, a new token is sent to the client and usable by the requesting third party.

    Get Client

    Command:

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/clients/"

    The above command returns JSON structured like this:

    {
  "id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
  "fiduciary_id": "bfb564f3-dba8-4d90-b84d-335212ef5484",
  "legal_entity": {
    "name": "Client X",
    "enterprise_num": "BE0840559537",
    "is_enterprise_num_validated": false,
    "representative_name": "no name",
    "representative_function": "no function",
    "address": "no address",
    "address2": "no address",
    "zip": "no zip",
    "city": "no city"
  },
  "client_code": "CODABOX-01",
  "contact_name": "no name",
  "contact_email": "no email",
  "purchase_invoice_email": "no email",
  "language": "NA",
  "exact_email": "no email",
  "coda_mandates": [],
  "bank_accounts": [
    {
      "iban": "BE46977000017948",
      "coda_mandate_ids": [ ],
      "bank_id": "CDBXBE33",
      "client_id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
      "state": "draft",
      "state_modified_at": "",
      "type": "savings",
      "subaccounts": [
        {
          "currency": "USD",
          "extension": 234
        }
      ]
    }
  ],
  "social_mandates": [],
  "purchase_invoice_mandates": [],
  "state": "no state",
  "purchase_invoice_transmission_mandates": [],
  "services": [],
  "current_purchase_invoice_mandate_state": "no state",
  "delivery_mode": "no mode",
  "doccle_link_connect": "no link",
  "mycodabox_url": "no url",
  "state_modified_at": {},
  "zoomit_ibans": [],
  "mycodabox_access_state": "no state",
  "purchase_invoice_service": [],
  "is_purchase_invoice_delivery_via_push_blocked": false
}

    Once credentials are retrieved, clients endpoint is accessible.

    Note: In case of the sales invoice process, the returned JSON is a list that contains only one item.

    GET <api_prefix>/clients/

    For a complete description of client JSON structure : client's data model.

    Get client's CODA files

    See Get Documents section.

    See sales invoice process particularities

    Upload an UBL file

    Step 1 : Upload an UBL file

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -F "file=@file.xml" \
    -u <login:password> "https://sandbox-api.codabox.com/v2/ubl/sales-invoice/upload/"

    POST <api_prefix>/ubl/sales-invoice/upload/

    Uploading an UBL file is done by a HTTP multipart request.

    UBL file must be encoded in UTF-8.

    Several checks are performed for an UBL file to be successfully uploaded. The table below lists message content by type of validation.

    Supported formats

    UBL type description supported_formats entries (service)
    invoice & creditnote UBL.BE urn:cen.eu:en16931:2017#conformant#urn:UBL.BE:1.0.0.20180214::2.1
    invoice & creditnote PEPPOL BIS 3 urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1

    1. UBL file size is limited to 1 MB

    2. UBL file extension must be xml

    3. UBL root tag must be <Invoice> or <CreditNote>

    4. UBL must be valid regarding invoice and creditNote XSD validation

    5. VAT of the supplier:

    UBL file must provide the VAT of the supplier. The VAT must be set in the following tag: <cac:AccountingSupplierParty><cac:Party><cac:PartyLegalEntity><cbc:CompanyID>

    The VAT must match the enterprise number of the client.

    1. Avoid uploading an UBL twice with the same invoice_number,invoice_date.year an invoice_folder (if set).

    In the UBL file, the invoice_number corresponds to the <ID> tag, the invoice_date corresponds to the <IssueDate> tag.

    The invoice_folder can be defined in an <cac:AdditionalDocumentReference>. See description here

    1. invoice_date validation:

    It is not allowed to upload an invoice for the previous year if an invoice for the current year has already been uploaded in a given folder.

    The year is taken from the date defined in the <IssueDate> tag.

    1. CodaBox recommends the third party to provide an UBL file that follows BIS 3.0 UBL rules : http://docs.peppol.eu/poacc/billing/3.0/

    Find some examples of expected UBL files:

    Invoice, CreditNote, Invoice with folder

    1. A base64 encoded pdf is mandatory as cac:AdditionalDocumentReference

    Mandatory cac:AdditionalDocumentReference

      <cac:AdditionalDocumentReference>
    <cbc:ID>test_case_1.pdf</cbc:ID>
    <cbc:DocumentType>CommercialInvoice</cbc:DocumentType>
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf">JVBERi0xLjMNCiWTjIueIFJlcG9ydExhYiBHZW5lcmF0ZWQgUERGIGRvY3VtZW50IGh0dHA6Ly93d3cucmVwb3J0bGFiLmNvbQ0KMSAwIG9iag0KPDwgL0YxIDIgMCBSIC9GMiAzIDAgUiA+Pg0KZW5kb2JqDQoyIDAgb2JqDQo8PCAvQmFzZUZvbnQgL0hlbHZldGljYSAvRW5jb2RpbmcgL1dpbkFuc2lFbmNvZGluZyAvTmFtZSAvRjEgL1N1YnR5cGUgL1R5cGUxIC9UeXBlIC9Gb250ID4+DQplbmRvYmoNCjMgMCBvYmoNCjw8IC9CYXNlRm9udCAvSGVsdmV0aWNhLUJvbGQgL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcgL05hbWUgL0YyIC9TdWJ0eXBlIC9UeXBlMSAvVHlwZSAvRm9udCA+Pg0KZW5kb2JqDQo0IDAgb2JqDQo8PCAvQ29udGVudHMgMTAgMCBSIC9NZWRpYUJveCBbIDAgMCA1OTUuMjc1NiA4NDEuODg5OCBdIC9QYXJlbnQgOSAwIFIgL1Jlc291cmNlcyA8PCAvRm9udCAxIDAgUiAvUHJvY1NldCBbIC9QREYgL1RleHQgL0ltYWdlQiAvSW1hZ2VDIC9JbWFnZUkgXSA+PiAvUm90YXRlIDAgL1RyYW5zIDw8ICA+PiANCiAgL1R5cGUgL1BhZ2UgPj4NCmVuZG9iag0KNSAwIG9iag0KPDwgL091dGxpbmVzIDcgMCBSIC9QYWdlTW9kZSAvVXNlTm9uZSAvUGFnZXMgOSAwIFIgL1R5cGUgL0NhdGFsb2cgPj4NCmVuZG9iag0KNiAwIG9iag0KPDwgL0F1dGhvciAoKSAvQ3JlYXRpb25EYXRlIChEOjIwMTYwODMwMTUzNzM1LTAxJzAwJykgL0NyZWF0b3IgKFwodW5zcGVjaWZpZWRcKSkgL0tleXdvcmRzICgpIC9Qcm9kdWNlciAocGlzYSBIVE1MIHRvIFBERiA8aHR0cDovL3d3dy5odG1sdG9wZGYub3JnPikgL1N1YmplY3QgKCkgDQogIC9UaXRsZSAoKSA+Pg0KZW5kb2JqDQo3IDAgb2JqDQo8PCAvQ291bnQgMSAvRmlyc3QgOCAwIFIgL0xhc3QgOCAwIFIgL1R5cGUgL091dGxpbmVzID4+DQplbmRvYmoNCjggMCBvYmoNCjw8IC9EZXN0IFsgNCAwIFIgL0ZpdCBdIC9QYXJlbnQgNyAwIFIgL1RpdGxlIChEdW1teSBpbnZvaWNlIHBkZikgPj4NCmVuZG9iag0KOSAwIG9iag0KPDwgL0NvdW50IDEgL0tpZHMgWyA0IDAgUiBdIC9UeXBlIC9QYWdlcyA+Pg0KZW5kb2JqDQoxMCAwIG9iag0KPDwgL0ZpbHRlciBbIC9BU0NJSTg1RGVjb2RlIC9GbGF0ZURlY29kZSBdIC9MZW5ndGggMTk5ID4+DQpzdHJlYW0NCkdhcWNvYm1NPEEmOzlNJ11ZYl5oMFs4YWBrdUcpPDA4NGgsQzhGOHAhdTlfTTJKUE1eTDFQUmFEWzpZI0FUJjZkQE1DXE4lKEhDImpoUCk6PUdqLW45bTZAWzlOOVJIKEpuLj08UGQlRHMqR2s+VmsnaFspYm43TE1MZSMrUGREV0VbMDdxPj0kRGY7LEkrMmxHZEZbSUBoRzhTNCgsTTJWdDw8KkhDWGtVTzM9XHFLOStxWm1iJUZ1SUtpQDUiczBCZzNXfj5lbmRzdHJlYW0NCmVuZG9iag0KeHJlZg0KMCAxMQ0KMDAwMDAwMDAwMCA2NTUzNSBmDQowMDAwMDAwMDc1IDAwMDAwIG4NCjAwMDAwMDAxMTkgMDAwMDAgbg0KMDAwMDAwMDIyOSAwMDAwMCBuDQowMDAwMDAwMzQ0IDAwMDAwIG4NCjAwMDAwMDA1NTIgMDAwMDAgbg0KMDAwMDAwMDYzOSAwMDAwMCBuDQowMDAwMDAwODM2IDAwMDAwIG4NCjAwMDAwMDA5MTAgMDAwMDAgbg0KMDAwMDAwMDk5NiAwMDAwMCBuDQowMDAwMDAxMDU4IDAwMDAwIG4NCnRyYWlsZXINCjw8IC9JRCANCiAlIFJlcG9ydExhYiBnZW5lcmF0ZWQgUERGIGRvY3VtZW50IC0tIGRpZ2VzdCAoaHR0cDovL3d3dy5yZXBvcnRsYWIuY29tKQ0KIFsoXDI0N1wzNTNcMjM0XDM1MVwzNzFPMzxcMjA1XDIzMlwwMjFcMjU1c01cMjcwXDE3NykgKFwyNDdcMzUzXDIzNFwzNTFcMzcxTzM8XDIwNVwyMzJcMDIxXDI1NXNNXDI3MFwxNzcpXQ0KIC9JbmZvIDYgMCBSIC9Sb290IDUgMCBSIC9TaXplIDExID4+DQpzdGFydHhyZWYNCjEzNTMNCiUlRU9GDQo=</cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>

    List of returned error message by type of validation

    returned error example 1

    {
  "file": ["File too big max 1 Mb"]
}

    returned error example 2

    {
  "file": ["Invalid file type, only XMLs are allowed"]
}

    returned error example 3

    {
  "file": ["The supplier VAT doesn't match the currently logged in user's VAT."]
}

    Validation: VAT of the supplier

      <cac:AccountingSupplierParty>
    <cac:Party>
      <cac:PartyLegalEntity>
        <cbc:CompanyID schemeID="9925">BE0840559537</cbc:CompanyID>
      </cac:PartyLegalEntity>
    </cac:Party>
  </cac:AccountingSupplierParty>

    Validation: CBE of the supplier

      <cac:AccountingSupplierParty>
    <cac:Party>
      <cac:PartyLegalEntity>
        <cbc:CompanyID schemeID="9956">0840559537</cbc:CompanyID>
      </cac:PartyLegalEntity>
    </cac:Party>
  </cac:AccountingSupplierParty>
    Validation errors: HTTP 400 key
    No file was submitted. file
    1 File too big max 1 Mb
    2 Invalid file type, only XMLs are allowed.
    3 Invalid XML root tag: only or are allowed.
    4 Invalid XML document: syntax error or XSD validation failed.
    5 The supplier VAT doesn't match the currently logged in user's VAT.
    6 An invoice with the same year and number exists already in the given folder.
    7 It is not allowed to upload an invoice for the previous year.
    9 Ubl file doesn't contain invoice pdf in embeddedDocumentBinaryObject tag
    10 Format is not supported.

    Providing an invoice_folder in the ubl file

    <cac:AdditionalDocumentReference>
    <cbc:ID>book1</cbc:ID>
    <cbc:DocumentType>codabox-folder</cbc:DocumentType>
</cac:AdditionalDocumentReference>

    It is possible to provide an invoice folder in the UBL itself. The invoice folder can be assimilated to an accountant book. If an invoice folder has been provided, the CodaBox fiduciary delivery process will create a folder where the invoice will be placed in.

    To specify a invoice folder, a specific AdditionalDocumentReference tag must be used as follow in the UBL file:

    CODAPlus file description

    xsd

    <?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="Statement">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Version" type="xs:double"></xs:element>
        <xs:element name="Fiduciary" type="xs:string"></xs:element>
        <xs:element name="FiduciaryClient" type="xs:string"></xs:element>
        <xs:element name="ClientAccount" type="xs:string"></xs:element>
        <xs:element name="OldBalance">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Value" type="xs:double"></xs:element>
              <xs:element name="Date" type="xs:date"></xs:element>
              <xs:element name="StatementNumber" type="xs:int"></xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="NewBalance">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Value" type="xs:double"></xs:element>
              <xs:element name="Date" type="xs:date"></xs:element>
              <xs:element name="StatementNumber" type="xs:int"></xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="PaymentList">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Payment" minOccurs="0" maxOccurs="unbounded">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="StatementNumber" type="xs:int"></xs:element>
                    <xs:element name="MovSeqNum" type="xs:int"></xs:element>
                    <xs:element name="DetailNum" type="xs:int"></xs:element>
                    <xs:element name="Counterparty">
                      <xs:complexType>
                        <xs:sequence>
                          <xs:element name="Name" type="xs:string"></xs:element>
                          <xs:element name="BankAccount" type="xs:string"></xs:element>
                        </xs:sequence>
                      </xs:complexType>
                    </xs:element>
                    <xs:element name="Amount" type="xs:double"></xs:element>
                    <xs:element name="Currency" type="xs:string"></xs:element>
                    <xs:element name="ValueDate" type="xs:date"></xs:element>
                    <xs:element name="Communication" type="xs:string"></xs:element>
                    <xs:element name="TransactionCode">
                      <xs:complexType>
                        <xs:sequence>
                          <xs:element name="Code" type="xs:int"></xs:element>
                          <xs:element name="Description" type="xs:string"></xs:element>
                          <xs:element name="TransactionFamilyCode" type="xs:int"></xs:element>
                          <xs:element name="TransactionFamilyDescription" type="xs:string"></xs:element>
                        </xs:sequence>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

    Example 1 : CODAPlus contains with multiple payments

    <?xml version='1.0' encoding='utf-8'?>
<Statement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="codaPLUS_V1.0.xsd">
  <Version>1.0</Version>
  <Fiduciary>BE0010012774</Fiduciary>
  <FiduciaryClient>BE0010015348</FiduciaryClient>
  <ClientAccount>BE27974000004133</ClientAccount>
  <OldBalance>
    <Value>7574.22</Value>
    <Date>2015-10-16</Date>
    <StatementNumber>201</StatementNumber>
  </OldBalance>
  <NewBalance>
    <Value>7002.42</Value>
    <Date>2015-10-19</Date>
    <StatementNumber>203</StatementNumber>
  </NewBalance>
  <PaymentList>
    <Payment>
      <StatementNumber>201</StatementNumber>
      <MovSeqNum>1</MovSeqNum>
      <DetailNum>0</DetailNum>
      <Counterparty>
        <Name>François l'embrouille</Name>
        <BankAccount>BE05977000008210</BankAccount>
      </Counterparty>
      <Amount>99.99</Amount>
      <Currency>EUR</Currency>
      <ValueDate>2015-10-17</ValueDate>
      <Communication>Facture20151010</Communication>
      <TransactionCode>
        <Code>50</Code>
        <Description>Transfer in your favour</Description>
        <TransactionFamilyCode>01</TransactionFamilyCode>
        <TransactionFamilyDescription>Domestic or local SEPA credit transfers</TransactionFamilyDescription>
      </TransactionCode>
    </Payment>
    <Payment>
      <StatementNumber>201</StatementNumber>
      <MovSeqNum>2</MovSeqNum>
      <DetailNum>0</DetailNum>
      <Counterparty>
        <Name>My company SA</Name>
        <BankAccount>BE05977000008210</BankAccount>
      </Counterparty>
      <Amount>2377.65</Amount>
      <Currency>EUR</Currency>
      <ValueDate>2015-10-17</ValueDate>
      <Communication>Facture20151012</Communication>
      <TransactionCode>
        <Code>50</Code>
        <Description>Transfer in your favour</Description>
        <TransactionFamilyCode>01</TransactionFamilyCode>
        <TransactionFamilyDescription>Domestic or local SEPA credit transfers</TransactionFamilyDescription>
      </TransactionCode>
    </Payment>
    <Payment>
      <StatementNumber>202</StatementNumber>
      <MovSeqNum>1</MovSeqNum>
      <DetailNum>0</DetailNum>
      <Counterparty>
        <Name>Codabox SA</Name>
        <BankAccount>BE80977000008218</BankAccount>
      </Counterparty>
      <Amount>1349.15</Amount>
      <Currency>EUR</Currency>
      <ValueDate>2015-10-18</ValueDate>
      <Communication>Facture20151013</Communication>
      <TransactionCode>
        <Code>50</Code>
        <Description>Transfer in your favour</Description>
        <TransactionFamilyCode>01</TransactionFamilyCode>
        <TransactionFamilyDescription>Domestic or local SEPA credit transfers</TransactionFamilyDescription>
      </TransactionCode>
    </Payment>
    <Payment>
      <StatementNumber>203</StatementNumber>
      <MovSeqNum>1</MovSeqNum>
      <DetailNum>0</DetailNum>
      <Counterparty>
        <Name>Codabox SA</Name>
        <BankAccount>BE80977000008218</BankAccount>
      </Counterparty>
      <Amount>13.34</Amount>
      <Currency>EUR</Currency>
      <ValueDate>2015-10-19</ValueDate>
      <Communication>Facture20151014</Communication>
      <TransactionCode>
        <Code>50</Code>
        <Description>Transfer in your favour</Description>
        <TransactionFamilyCode>01</TransactionFamilyCode>
        <TransactionFamilyDescription>Domestic or local SEPA credit transfers</TransactionFamilyDescription>
      </TransactionCode>
    </Payment>
  </PaymentList>
</Statement>

    Example 2 : CODAPlus doesn't contains any positive movement : PaymentList is empty

    <?xml version='1.0' encoding='utf-8'?>
<Statement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="codaPLUS_V1.0.xsd">
  <Version>1.0</Version>
  <Fiduciary>BE0010012774</Fiduciary>
  <FiduciaryClient>BE0010015348</FiduciaryClient>
  <ClientAccount>BE27974000004133</ClientAccount>
  <OldBalance>
    <Value>7002.42</Value>
    <Date>2015-10-19</Date>
    <StatementNumber>204</StatementNumber>
  </OldBalance>
  <NewBalance>
    <Value>1001.34</Value>
    <Date>2015-10-20</Date>
    <StatementNumber>204</StatementNumber>
  </NewBalance>
  <PaymentList>
  </PaymentList>
</Statement>

    Example 3

    <?xml version="1.0" encoding="utf-8"?>
<Statement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="codaPLUS_V1.0.xsd">
  <Version>1.0</Version>
  <Fiduciary>BE0010012774</Fiduciary>
  <FiduciaryClient>BE0010015348</FiduciaryClient>
  <ClientAccount>BE27974000004133</ClientAccount>
  <OldBalance>
    <Value>1001.34</Value>
    <Date>2015-10-20</Date>
    <StatementNumber>205</StatementNumber>
  </OldBalance>
  <NewBalance>
    <Value>2001.34</Value>
    <Date>2015-10-20</Date>
    <StatementNumber>205</StatementNumber>
  </NewBalance>
  <PaymentList>
      <Payment>
      <StatementNumber>205</StatementNumber>
      <MovSeqNum>1</MovSeqNum>
      <DetailNum>0</DetailNum>
      <Counterparty>
        <Name>Codabox SA</Name>
        <BankAccount>BE80977000008218</BankAccount>
      </Counterparty>
      <Amount>1000.00</Amount>
      <Currency>EUR</Currency>
      <ValueDate>2015-10-20</ValueDate>
      <Communication>Facture20151018</Communication>
      <TransactionCode>
        <Code>50</Code>
        <Description>Transfer in your favour</Description>
        <TransactionFamilyCode>01</TransactionFamilyCode>
        <TransactionFamilyDescription>Domestic or local SEPA credit transfers</TransactionFamilyDescription>
      </TransactionCode>
    </Payment>
  </PaymentList>
</Statement>

    (*) For information about TransactionCode and TransactionFamilyCode see febelfin documentation

    Checklist Sales invoices - copy to accountant

    Search endpoints

    Search endpoints allows to search for specific data objects:

    The search endpoint returns a lighter json representation of the business objects.

    Search endpoint allows to:

    Search endpoints list

    Method HTTP request Note
    GET GET <api_prefix>/search/clients/ Search clients
    GET GET <api_prefix>/search/coda-mandates/ Search coda mandates
    GET GET <api_prefix>/search/social-mandates/ Search social mandates

    Global returned json structure

    example: client

    {
  "count": 1,
  "next": 0,
  "previous": 0,
  "results": [
    {
      "id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
      "name": "Accountant X",
      "client_code": "f54cb91f-1295-4c64-ac4e-7a13bc510b15",
      "enterprise_num": "BE0840559537",
      "contact_email": "no email",
      "representative_name": "no name",
      "state_modified_at": {},
      "state": "active",
      "services": [],
      "language": "NA",
      "exact_email": "no email",
      "purchase_invoice_service_state": "no state",
      "contact_email_verification_state": "no state"
    }
  ]
}

    Whatever are the queried objects, the returned json structure of each search endpoint exposes the following keys:

    Field Type Values - format Note
    count number integer total of items returned by the query
    next string url url to get the next result page
    previous string url url to get the previous result page
    results JSON collection results of the current page

    Filtering

    Filtering keys are specific to business objects. The fields that can be used are listed for each business object in its dedicated section.

    As usual, the query string begins by ?

    The query string must not end with /

    Some special characters used in the query string must be escaped by following HTML URL encoding: https://en.wikipedia.org/wiki/Percent-encoding

    Filtering on string type

    By default filtering is case sensitive and the lookup value must match the exact word.

    To perform a full-text search, the keyword icontains can be used: /search/clients/?name__icontains=a

    To perform a starts-with search the keyword startswith can be used: /search/clients/?name__startswith=Jea

    To perform a ends-with search the keyword endswith can be used: /search/clients/?enterprise_num__endswith=504

    Note: the keywords must follow the key field and are prefixed by two underscore : __. icontains is not case sensitive but startswith and endswith are case sensitive.

    Beside specific keys, the search key which is defined for each search endpoint, aggregates the search on several fields (see filtering section of each search). Also, the search field executes a full-text search and is not case-sensitive.

    It is possible to combine multiple search criteria by using the &:

    Filtering on datetime

    For dateTime fields, some keywords can be used to improve the search :

    Note: the keywords must follow the key field and are prefixed by two underscore : __.

    Examples:

    Date format: YYYY-MM-DDThh:mm:ss: 2016-08-30T00:00:00

    Ordering

    The results can be sorted on one or multiple fields. Again the list of sortable fields is describe in each dedicated section.

    By default, fields are sorted in ascending order.

    Sorting in descending order is doable by using -:

    It is possible to sort on multiple criteria:

    Note: Sorting is not case sensitive.

    Paging

    Get client list ordering by name and limit the result to 5 items

     curl -v \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&ordering=name"

    The results collection contains the first 5 items (page 1), next key expose the url to get the next 5 items (page 2)

    {
  "count": 16,
  "next": "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&offset=5&ordering=name",
  "previous": null,
  "results": [{}, {}, {}, {}, {}]
}

    Get the second page of the query set

     curl -v \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&offset=5&ordering=name"

    second page: next expose the url to get the next 5 items (page 3), previous expose the url to get the first page

    {
  "count": 16,
  "next": "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&offset=10&ordering=name",
  "previous": "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&ordering=name",
  "results": [{}, {}, {}, {}, {}]
}

    Get third page of the query set

     curl -v \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&offset=10&ordering=name"

    third page: next expose the url to get the next 5 items (page 4), previous expose the url to get the second page

    {
  "count": 16,
  "next": "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&offset=15&ordering=name",
  "previous": "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&offset=5&ordering=name",
  "results": [{}, {}, {}, {}, {}]
}

    Get fourth page of the query set

     curl -v \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&offset=15&ordering=name"

    fourth page: next is null, previous expose the url to get the third page

    {
  "count": 16,
  "next": null,
  "previous": "https://sandbox-api.codabox.com/v2/search/clients/?limit=5&offset=10&ordering=name",
  "results": [{}]
}

    A search endpoint allows to specify the number of item to be returned by the request and the position in the query set.

    By default,a page will return a maximum of 50 items. The number of returned items can be overridden by using the limit key, the position in the result is defined by the offset key. The maximum of returned items is 150.

    Note:

    The combination of the limit and the offset keys allows to perform paging.

    Example 1:

    Example 2:

    The next key provides the url to the next page.

    The previous key provides the url to previous page.

    On the first page, the value of the previous key is null.

    On the last page, the value of next key is null.

    Combine filtering, sorting and paging

    Filtering, sorting and paging can be mixed.

    Also, the next and the previous url keys provides the filtering and the sorting criteria together with the limit and the offset keys.

    Example:

    Url request: /search/clients/?limit=50&search=abcd&state=active&ordering=state,name

    Assuming that the request returns a results of 81 items, the value of the next key in the json response will be: /search/clients/?limit=50&offset=50&search=abcd&state=active&ordering=state,name. The value of the previous key is null.

    After requesting the second page, the value of the previous url in the json response will be: /search/clients/?limit=50&offset=0&search=abcd&state=active&ordering=state,name. The value of the next key will be null.

    Search clients

    Structure of a client result item

    client item

        {
      "id": "a2cdc1bc-0d9d-430e-b226-338d31906d1f",
      "name": "Accountant X",
      "client_code": "f54cb91f-1295-4c64-ac4e-7a13bc510b15",
      "enterprise_num": "BE0840559537",
      "contact_email": "no email",
      "representative_name": "no name",
      "state_modified_at": {},
      "state": "active",
      "services": [],
      "language": "NA",
      "exact_email": "no email",
      "purchase_invoice_service_state": "no state",
      "contact_email_verification_state": "no state"
    }
    Field Type Values - format Note
    id string uuid client identifier
    name string ?{160} client's company name
    client_code string ?{50} client code
    contact_email string NA - deprecated
    enterprise_num string BE[0-9]{10} enterprise number
    representative_name string NA - deprecated
    state_modified_at string NA - deprecated
    state string NA - deprecated
    language string NA - deprecated
    exact_email string NA - deprecated
    purchase_invoice_service_state string NA - deprecated
    services JSON list NA - deprecated

    Filtering keys

    Field Type JSON field
    search string name, client_code, enterprise_num
    id string id
    name string name
    client_code string client_code
    contact_email NA - deprecated
    enterprise_num string enterprise_num
    state_modified_at NA - deprecated
    state NA - deprecated
    language NA - deprecated
    purchase_invoice_service_state string NA - deprecated

    Using the search field allows to perform a lookup on the name or the client_code or enterprise_num fields in the same request.

    Contrary to a specific field, search field is not case sensitive (like icontains)

    Ordering keys

    Field Type
    name string
    client_code string
    enterprise_num string

    Ordering fields are not case sensitive.

    Search client Endpoint

    get clients order by name, enterprise_num limited to 4 items

     curl -v \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/search/clients/?limit=4&ordering=name,enterprise_num&search=cli"

    example of search client results (page 1, 4 items in result collection)

    {
  "count": 41,
  "next": "https://sandbox-api.codabox.com/v2/search/clients/?limit=4&offset=4&ordering=name%2Centerprise_num&search=cli",
  "previous": null,
  "results": [
    {
      "id": "bae44409-966d-4878-8a9c-46a12cc402ef",
      "name": "Bamvolice",
      "client_code": "CLI22",
      "enterprise_num": "BE0010021979",
      "contact_email": "no email",
      "representative_name": "no name",
      "state_modified_at": {},
      "state": "active",
      "services": [],
      "language": "NA",
      "exact_email": "no email",
      "purchase_invoice_service_state": "no state",
    },
    {
      "id": "ac134356-abe8-4661-913c-edae43338bab",
      "name": "Bigplanet",
      "client_code": "CLI7",
      "enterprise_num": "BE001341979",
      "contact_email": "no email",
      "representative_name": "no name",
      "state_modified_at": {},
      "state": "active",
      "services": [],
      "language": "NA",
      "exact_email": "no email",
      "purchase_invoice_service_state": "no state",
    },
    {
      "id": "8152b9ff-4b59-4d30-8001-81e0aaf32fd6",
      "name": "Cityfind",
      "client_code": "CLI4",
      "enterprise_num": "BE0010023479",
      "contact_email": "no email",
      "representative_name": "no name",
      "state_modified_at": {},
      "state": "active",
      "services": [],
      "language": "NA",
      "exact_email": "no email",
      "purchase_invoice_service_state": "no state",
    },
    {
      "id": "d36eeb86-e074-4aab-aba1-48d7dd7202fd",
      "name": "client",
      "client_code": "CLIENT_2",
      "contact_email": null,
      "enterprise_num": "BE0010021449",
      "contact_email": "no email",
      "representative_name": "no name",
      "state_modified_at": {},
      "state": "active",
      "services": [],
      "language": "NA",
      "exact_email": "no email",
      "purchase_invoice_service_state": "no state",
    }
  ]
}

    GET <api_prefix>/v2/search/clients/

    Query examples:

    Search coda mandates

    Structure of a coda-mandate result item

    coda-mandate item

    {
  "id": "446aa886-c99b-4a0e-8fea-ff959fd71d3f",
  "validity_start": "2011-01-20",
  "state": "active",
  "reason": null,
  "twikey_url": "http://langoshconsidine.com/",
  "state_modified_at": "2015-12-07T13:54:27.659244",
  "has_teletransmission_pdf": true,
  "bank_accounts": [
    {
      "iban": "BE40977000050163",
      "state": "active",
      "state_modified_at": "2015-12-07T13:54:27.652974",
      "type": "current",
      "subaccounts": []
    }
  ],
  "client": {
    "id": "25aa8291-0caf-4028-9184-f5dfb0946cc5",
    "name": "Powlowski, Christiansen and Wuckert",
    "client_code": "culpa-voluptas-quis",
    "enterprise_num": "BE0010060482"
  },
  "fiduciary": {
    "id": "8fd17a20-a7a4-4dda-9846-4a604289e488",
    "name": "Reinger, Hand and Reinger",
    "enterprise_num": "BE001005845"
  },
  "bank": {
    "name": "Coda bank 2",
    "bank_id": "CDBXBE34"
  }
}

    coda-mandate

    Field Type Values - format Note
    id string id mandate identifier
    validity_start string yyyy-mm-dd creation date of the mandate
    state string state list
    reason string explanation of the current state
    twikey_url string url to twikey digital signature (*)
    state_modified_at string ISO 8601 timestamp of the last state modification
    has_teletransmission_pdf boolean is the teletransmission pdf available for download
    bank_accounts JSON List List of bank accounts ordered in the mandate
    client JSON Client linked to the mandate
    fiduciary JSON Fiduciary linked to the mandate
    bank JSON Bank linked to the mandate

    coda-mandate.bank_accounts

    Field Type Values - format Comment
    iban string BE[0-9]{14} valid iban
    state string state of the bank account
    state_modified_at string ISO 8601 timestamp of the last state modification
    type string "current", "savings" type of the bank account
    subaccounts JSON List list of Subaccounts

    coda-mandate.bank*accounts[*].subaccounts

    Field Type Values - format Comment
    currency string ?{3} Currency Symbol or empty string "EUR", "USD", ...
    extension string The extension for this subaccount if any, usually a 3 digit number.

    coda-mandate.client

    Field Type Values - format Note
    id string uuid client identifier
    name string ?{160} client's company name
    client_code string ?{50} client code
    contact_email string email client's email
    enterprise_num string BE[0-9]{10} enterprise number

    coda-mandate.fiduciary

    Field Type Values - format Note
    id string uuid client identifier
    name string ?{160} client's company name
    enterprise_num string BE[0-9]{10} enterprise number

    coda-mandate.bank

    Field Type Values - format Note
    bank_id string ?{20} Bank identifier (BIC)
    name string ?{100} Name of the bank

    Filtering keys

    Field Type JSON field
    search string client.name, client.client_code, client.enterprise_num, bank_accounts.iban
    id string id
    state_modified_at DateTime state_modified_at
    state string state
    client__name string client.name
    client__client_code string client.client_code
    client__contact_email string client.contact_email
    client__enterprise_num string client.enterprise_num
    bank__bank_id string bank.bank_id
    bank__name string bank.name
    bank_accounts__iban string bank_accounts.iban

    Using the search field allows to perform a lookup on the client__name or the client__client_code or client__enterprise_num or the bank_accounts__iban fields in the same request.

    Contrary to a specific field, search field is not case sensitive (like icontains)

    Ordering keys

    Field Type JSON field
    state_modified_at DateTime state_modified_at
    validity_start datetime validity_start
    state string state
    client__name string client.name
    client__client_code string client.client_code
    client__contact_email string client.contact_email
    client__enterprise_num string client.enterprise_num
    bank__bank_id string bank.bank_id
    bank__name string bank.name

    Ordering fields are not case sensitive.

    Search coda-mandates Endpoint

    get coda-mandates order by client.name limited to 5 items

     curl -v \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/search/coda-mandates/?ordering=client__name&limit=5"

    example of search coda-mandates results (5 items by results, second page)

    {
  "count": 182,
  "next": "https://sandbox-api.codabox.com/v2/search/coda-mandates/?limit=5&offset=5&ordering=client_name",
  "previous": null,
  "results": [
    {
      "id": "b5de04f6-70d8-48cc-ab4b-7c8ee746502f",
      "validity_start": "2015-10-20",
      "state": "pre-treatment",
      "reason_code": "R-0",
      "reason": null,
      "twikey_url": "",
      "state_modified_at": "2015-10-20T20:45:50.614117",
      "has_teletransmission_pdf": true,
      "bank_accounts": [
        {
          "iban": "BE34750650300690",
          "state": "active",
          "state_modified_at": "2015-10-30T15:52:34.784733",
          "type": "current",
          "subaccounts": []
        }
      ],
      "client": {
        "id": "92160c82-589a-459d-a3a2-707235fcdf68",
        "name": "client",
        "client_code": "CLIENT_1",
        "contact_email": "joe.bar@mail.com",
        "enterprise_num": "BE0010018813"
      },
      "fiduciary": {
        "id": "0bef0e63-7331-4047-a328-dbbdfb093c4e",
        "name": "fiduciary 1",
        "enterprise_num": "BE0010012675"
      },
      "bank": {
        "name": "Coda bank 1",
        "bank_id": "CDBXBE33"
      }
    },
    {
      "id": "71fb7bf3-3bef-4cb6-aebf-7092e008ffe5",
      "validity_start": "2016-01-08",
      "state": "pre-treatment",
      "reason_code": "R-0",
      "reason": null,
      "twikey_url": "",
      "state_modified_at": "2016-01-08T11:36:33.319320",
      "has_teletransmission_pdf": true,
      "bank_accounts": [
        {
          "iban": "BE58974000001344",
          "state": "active",
          "state_modified_at": "2016-01-09T02:00:33.149491",
          "type": "current",
          "subaccounts": []
        }
      ],
      "client": {
        "id": "d36eeb86-e074-4aab-aba1-48d7dd7202fd",
        "name": "client",
        "client_code": "CLIENT_2",
        "contact_email": "client2@test.com",
        "enterprise_num": "BE0000278528"
      },
      "fiduciary": {
        "id": "0bef0e63-7331-4047-a328-dbbdfb093c4e",
        "name": "fiduciary 1",
        "enterprise_num": "BE0010012675"
      },
      "bank": {
        "name": "Coda bank 1",
        "bank_id": "CDBXBE33"
      }
    },
    {
      "id": "95ad1aa6-6087-4477-a101-da50eade489d",
      "validity_start": "2015-10-20",
      "state": "active",
      "reason": null,
      "twikey_url": null,
      "state_modified_at": "2015-10-29T10:37:40.794358",
      "has_teletransmission_pdf": true,
      "bank_accounts": [
        {
          "iban": "BE17974000003925",
          "state": "active",
          "state_modified_at": "2015-10-30T15:52:39.635309",
          "type": "current",
          "subaccounts": []
        }
      ],
      "client": {
        "id": "92160c82-589a-459d-a3a2-707235fcdf68",
        "name": "client",
        "client_code": "CLIENT_1",
        "contact_email": null,
        "enterprise_num": "BE0010018813"
      },
      "fiduciary": {
        "id": "0bef0e63-7331-4047-a328-dbbdfb093c4e",
        "name": "fiduciary 1",
        "enterprise_num": "BE0010012675"
      },
      "bank": {
        "name": "Coda bank 1",
        "bank_id": "CDBXBE33"
      }
    },
    {
      "id": "229320a5-a310-46b9-8a57-ec1e58cd11d9",
      "validity_start": "2015-10-15",
      "state": "active",
      "reason_code": "R-0",
      "reason": null,
      "twikey_url": "",
      "state_modified_at": "2015-10-29T10:37:41.041261",
      "has_teletransmission_pdf": true,
      "bank_accounts": [
        {
          "iban": "BE30974000000005",
          "state": "active",
          "state_modified_at": "2015-10-30T15:52:39.860167",
          "type": "current",
          "subaccounts": []
        },
        {
          "iban": "BE78974000000014",
          "state": "active",
          "state_modified_at": "2015-10-30T15:52:31.123903",
          "type": "current",
          "subaccounts": []
        }
      ],
      "client": {
        "id": "78194f59-c6bb-48f4-a04e-c68ac3590328",
        "name": "Finplanet",
        "client_code": "CL1",
        "contact_email": "cl1@test.com",
        "enterprise_num": "BE0010022573"
      },
      "fiduciary": {
        "id": "0bef0e63-7331-4047-a328-dbbdfb093c4e",
        "name": "fiduciary 1",
        "enterprise_num": "BE0010012675"
      },
      "bank": {
        "name": "Coda bank 1",
        "bank_id": "CDBXBE33"
      }
    },
    {
      "id": "aa241fc8-e752-4209-9597-4b7c259db95e",
      "validity_start": "2015-10-20",
      "state": "active",
      "reason_code": "R-0",
      "reason": null,
      "twikey_url": "",
      "state_modified_at": "2015-10-29T10:37:40.785398",
      "has_teletransmission_pdf": true,
      "bank_accounts": [
        {
          "iban": "BE25977000015125",
          "state": "active",
          "state_modified_at": "2015-10-30T15:52:46.851016",
          "type": "current",
          "subaccounts": []
        },
        {
          "iban": "BE74977000015116",
          "state": "active",
          "state_modified_at": "2015-10-30T15:52:40.991001",
          "type": "current",
          "subaccounts": []
        }
      ],
      "client": {
        "id": "92160c82-589a-459d-a3a2-707235fcdf68",
        "name": "client",
        "client_code": "CLIENT_1",
        "contact_email": null,
        "enterprise_num": "BE0010018813"
      },
      "fiduciary": {
        "id": "0bef0e63-7331-4047-a328-dbbdfb093c4e",
        "name": "fiduciary 1",
        "enterprise_num": "BE0010012675"
      },
      "bank": {
        "name": "Coda bank 2",
        "bank_id": "CDBXBE34"
      }
    }
  ]
}

    GET <api_prefix>/v2/search/coda-mandates/

    Query examples:

    Search social mandates

    Structure of a social-mandate result item

    social-mandate item

    {
  "id": "a214a43d-549f-40c4-bd77-a72116824f8a",
  "validity_start": "2015-11-13",
  "state": "active",
  "state_modified_at": "2015-11-13T10:32:14.625980",
  "client": {
    "id": "75d9b817-9e1b-4ffe-bb89-bd7f6443b440",
    "name": "Unidom",
    "client_code": "CLI5",
    "contact_email": "admin@undiom.com",
    "enterprise_num": "BE0010021880"
  },
  "fiduciary": {
    "id": "274118e4-6c28-4f3e-9d68-704ad7ca7830",
    "name": "fiduciary 3",
    "enterprise_num": "BE0010012873"
  },
  "social_welfare": {
    "name": "Group S",
    "social_welfare_id": "group_s"
  }
}

    social-mandate

    Field Type Values - format Note
    id string uuid mandate identifier
    validity_start string yyyy-mm-dd creation date of the mandate
    state string [state list](#social-mandate-states-description]
    state_modified_at string ISO 8601 timestamp of the last state modification
    client JSON Client linked to the mandate
    fiduciary JSON Fiduciary linked to the mandate
    social_welfare JSON social welfare linked to the mandate

    social-mandate.client

    Field Type Values - format Note
    id string uuid client identifier
    name string ?{160} client's company name
    client_code string ?{50} client code
    contact_email string email client's email
    enterprise_num string BE[0-9]{10} enterprise number

    social-mandate.fiduciary

    Field Type Values - format Note
    id string uuid client identifier
    name string ?{160} client's company name
    enterprise_num string BE[0-9]{10} enterprise number

    social-mandate.social_welfare

    Field Type Values - format Note
    social_welfare_id string ?{20} social welfare identifier
    name string ?{100} Name of the social welfare

    Filtering keys

    Field Type JSON field
    search string client.name, client.client_code, client.enterprise_num
    id string id
    state_modified_at DateTime state_modified_at
    state string state
    client__name string client.name
    client__client_code string client.client_code
    client__contact_email string client.contact_email
    client__enterprise_num string client.enterprise_num
    social_welfare__social_welfare_id string social_welfare.social_welfare_id
    social_welfare__name string social_welfare.name

    Search social-mandates Endpoint

    coda mandates order by client.name, limit to 5 items

    curl \
    -H "X-Software-Company: <your_x_software_company>" \
    -sL -u <login:password> "https://sandbox-api.codabox.com/v2/search/social-mandates/?ordering=client__name&limit=5"

    example of search social-mandates results (5 items by results, first page)

    {
  "count": 8,
  "next": "https://sandbox-api.codabox.com/v2/search/soda-mandates/?limit=5&offset=5&ordering=client__name",
  "previous": null,
  "results": [
    {
      "id": "db79898f-cd58-44c4-b913-19f228590bb6",
      "validity_start": "2016-02-18",
      "state": "waiting",
      "state_modified_at": "2016-02-18T12:27:31.571272",
      "client": {
        "id": "cbf5ca63-f43b-4a1d-9602-c499e2bb37c1",
        "name": "Client 39",
        "client_code": "CL39",
        "contact_email": "cl39@test.com",
        "enterprise_num": "BE0000299314"
      },
      "fiduciary": {
        "id": "6e4ba955-7fb9-4a05-94a1-ce3181dae6e6",
        "name": "fiduciaire 17",
        "enterprise_num": "BE0000299908"
      },
      "social_welfare": {
        "name": "Group S",
        "social_welfare_id": "group_s"
      }
    },
    {
      "id": "ab6dfec4-c725-4af4-81f0-84ff76906722",
      "validity_start": "2015-11-13",
      "state": "active",
      "state_modified_at": "2015-11-13T10:32:14.599128",
      "client": {
        "id": "f450271b-b1e5-43b7-beb9-07c9c4d4c347",
        "name": "Domholdings",
        "client_code": "CLI11",
        "contact_email": "info@domholdings.com",
        "enterprise_num": "BE0010016041"
      },
      "fiduciary": {
        "id": "65d297e6-5f71-4214-9caa-7aaf4404fb1d",
        "name": "fiduciary 6",
        "enterprise_num": "BE0010013170"
      },
      "social_welfare": {
        "name": "Group S",
        "social_welfare_id": "group_s"
      }
    },
    {
      "id": "3ea64dc3-fe75-4aa7-b21b-2ff66c33a197",
      "validity_start": "2015-11-13",
      "state": "active",
      "state_modified_at": "2015-11-13T10:07:24.121182",
      "client": {
        "id": "78194f59-c6bb-48f4-a04e-c68ac3590328",
        "name": "Finplanet",
        "client_code": "CL1",
        "contact_email": "admin@finplanet.com",
        "enterprise_num": "BE0010022573"
      },
      "fiduciary": {
        "id": "0bef0e63-7331-4047-a328-dbbdfb093c4e",
        "name": "fiduciary 1",
        "enterprise_num": "BE0010012675"
      },
      "social_welfare": {
        "name": "Group S",
        "social_welfare_id": "group_s"
      }
    },
    {
      "id": "801b1ec9-9a02-4f6c-8ea6-e60884b11a79",
      "validity_start": "2015-11-13",
      "state": "active",
      "state_modified_at": "2015-11-13T10:32:14.577470",
      "client": {
        "id": "df1a26b7-a95d-42c0-b193-f1e8a14b25b6",
        "name": "Inchhouse",
        "client_code": "CLI20",
        "contact_email": null,
        "enterprise_num": "BE0000210727"
      },
      "fiduciary": {
        "id": "0a8dda00-ef52-4657-a603-3a49221b1043",
        "name": "fiduciary 12",
        "enterprise_num": "BE0000210331"
      },
      "social_welfare": {
        "name": "Group S",
        "social_welfare_id": "group_s"
      }
    },
    {
      "id": "9b5b1190-2c3f-4ccd-b2d9-0ee54ad595ac",
      "validity_start": "2015-11-13",
      "state": "active",
      "state_modified_at": "2015-11-13T10:32:14.590301",
      "client": {
        "id": "fbbcfec8-d3d4-45b6-89fd-d28c88b57bc5",
        "name": "Trust-street",
        "client_code": "CLI19",
        "contact_email": null,
        "enterprise_num": "BE0000210628"
      },
      "fiduciary": {
        "id": "e71cc246-58f2-4ef0-9d11-8c813f49789a",
        "name": "fiduciary 11",
        "enterprise_num": "BE0000210232"
      },
      "social_welfare": {
        "name": "Group S",
        "social_welfare_id": "group_s"
      }
    }
  ]
}

    GET <api_prefix>/v2/search/social-mandates/

    Query examples:

    Changelog

    February 2021

    Copy to accountant BIS2 deprecation

    We have deprecated the BIS 2 format for upload to our API. From now on only PEPPOL BIS 3 formats are supported.

    You will get a HTTP 400 error format not supported when trying to upload a BIS 2 format.

    More on the formats is available on

    January 2021

    PEPPOL BIS 2.0 format deprecation

    BIS 2.0 formats (Peppol 4a, 5a, E-FFF) are no longer supported by CodaBox. Therefore, test receivers are updated to reflect the changes. From the end of January, we will only accept BIS 3.0 formats (PEPPOL BIS 3.0 & UBL.BE) on the API.

    Info on the new formats:

    December 2020

    Deprecated expense notes

    Expense notes have been deprecated. The pod-client will now always return an empty list on the key expense and the feed will no longer contain entries for that document_model.

    September 2020

    API changes

    The API has been updated. More specifically, some data fields are no longer be present in the API.

    You can download an example of the responses here.

    The documentation has been updated to reflect these changes.

    April 2019

    Peppol BIS 3.0

    As of 18th of April 2019 Codabox will support the new CENBII format.

    2019-03-07 New dummy receivers for Peppol BIS 3.0 & UBLBE

    New receivers for testing the two new formats were added. See 'Dummy receivers' in Send to Customer Peppol.

    2019-01-31 Update on schemeID use for Belgium

    The use of the 9925 and 9956 as we used to do is problematic at the moment as the Belgian replacements for these two numbers is not known yet.

    Proposal:

    The proposed solution is compliant with the schematron of Peppol BIS3 and UBL.BE documents.

    The schemeID in EndpointID is mandatory. The use of the old numbers is TEMPORARY allowed until the new numbers are known. In practical, you can temporary continue using 9925 and 9956 (until the new numbers are known).

    The schemeID in PartyIdentification is optional. The use of the old numbers is NOT allowed. In practical, you do not include the schemeID and use the CBE number (10 digits).

    The schemeID in PartyTaxScheme is NOT foreseen in the EN. In practical, you do not include a schemeID and always use the VAT number (“BE” + 10 digits)

    The schemeID in PartyLegalEntity is optional. The use of the old numbers is NOT allowed. In practical, you do not include the schemeID and use the CBE number (10 digits).

    2019-01-25 Announcement

    Sales invoices - Send to customer on Peppol API

    Sales invoices - Copy to accountant API

    Get Documents API

    Resources

    Online resources

    The main changes compared to the current formats are:

    The following documents contain the differences between the new format and PEPPOL 4a & 5a:

    March 2019

    Sales Invoices - Send to Customer Peppol

    It is now possible to view why the sent_state of a document is failed.

    Documents which could not be sent will have the field sent_reason_state filled in with a possible reason.

    shell