NAV
Developer portal
shell

Introduction

Welcome to the NoviCap early payments API. You can use our API to receive automated quotes for invoices, synchronize invoices to our platform and communicate invoice status updates to our system.

There are two steps for integrating with us, the first is to use the light integration to enable customers to onboard and open a factoring facility with us (sign legal, upload docs,…).

After the initial onboarding is complete and a company is activated, you can trade invoices automatically through the API and there is no more need for the customer to login to novicap.

If you do not have access to the API yet, please sign up here and reach out to api@novicap.com to enable API access for your partner account.

Authentication

To authorize while using the endpoint line_quote:

curl "https://api.novicap.com/line_quote" --data api_key=abcd

where abcd should be replaced with your API key.

We use API keys to authenticate. You can generate a new API key by logging into your partner account at novicap.com

The API key should be included in all requests to the server as an HTTP request parameter named api_key.

Permissions

Not all API endpoints are available and you must have specific permission to use an endpoint. If you get receive an error while trying to access a specific endpoint, do not hesitate to contact our API team at api@novicap.com to request access.

NoviCap IDs

Our system has a unique ID for each legal entity (company or debtor) which will be referred to as the novicap_id. It is required to find financial information that we use for quotes.

In the United Kingdom, this is defined as the 8 digit company number prefixed with “GB”. For example, Tesco PLC has a novicap_id of GB00445790.

In Spain, this is defined as the CIF code prefixed with “ES”. For example, Mercadona SA has a novicap_id of ESA46103834.

To be certain you have generated the correct novicap_id, or if you cannot generate it with the information you have available, you can use the search API with the company name.

Light integration

In the simplest case, send your users to your partner quote page URL. It will look something like this

"https://ncp-123456.novicap.com/quote?quote_key=abcd"

We offer a lightweight integration for partners in the form of a customizable free quote page. The URL can be generated by logging into your partner account at novicap.com (Settings -> Free quote page).

Users should be redirected to the given URL.

In the simplest case, they will be asked to input their information manually before receiving a quote. You can provide the following information as additional parameters in the URL to skip these steps. If you provide all the information below, the user will see a quote without any manual input. If you also set the “direct_integration” param to “true”, the user will be automatically logged in and redirected to their account page.

If you are uncomfortable sharing the contact information in plaintext then you can base64 encode the contact details:

https://ncp-372814.novicap.com/quote?api_key=9dedd03c7e43072f52dd99439e04430a&company_novicap_id=ESB50460609&debtor_novicap_id=ESA08002883&details=eyJmaXJzdF9uYW1lIjoiTWFyYyIsImxhc3RfbmFtZSI6IkFudG9uaSBNYWNp\nYSIsInBob25lIjoiNzIyNzA4MDUzIiwiZW1haWwiOiJtYXJjQG5vdmljYXAu\nY29tIn0=

json hash:
{
  "first_name":"John",
  "last_name":"Snow",
  "phone":"724565898",
  "email":"snow@novicap.com"
}

json hash encoded in base64:

eyJmaXJzdF9uYW1lIjoiTWFyYyIsImxhc3RfbmFtZSI6IkFudG9uaSBNYWNp\nYSIsInBob25lIjoiNzIyNzA4MDUzIiwiZW1haWwiOiJtYXJjQG5vdmljYXAu\nY29tIn0=

Parameters

A URL with all parameters filled in would look something like this

"https://ncp-123456.novicap.com/quote?quote_key=abcd \
                                     &company_novicap_id=GB123456 \
                                     &debtor_novicap_ids[]=GB234567 \
                                     &debtor_novicap_ids[]=GB345678 \
                                     &first_name=John+Edward \
                                     &last_name=Smith \
                                     &email=john.edward.smith%40gmail.com \
                                     &phone=07854123123 \
                                     &language=en"

Parameter Default Required Description
company_novicap_id The novicap_id of the company that should be quoted (see NoviCap IDs)
debtor_novicap_ids[] [] An array of novicap_ids of the debtors that should be quoted.
details Base64 encoded details. If you are uncomfortable sharing the contact information in plaintext then you can use this param to pass the base64 encoded version of the params hash.
direct_integration no If you provide all the requested parameters (novicap ids, email, first_name, last_name and phone), set this one to “yes” to log the user in automatically and redirect them to the application page.
email The email address of the user.
first_name The first name(s) of the user.
language Browser default An ISO 639-1 code (e.g. ‘en’) of the quote page display language.
last_name The surname(s) of the user.
phone The phone number of the user.
quote_key Your quote key for authentication. You can find it in your settings page.

API

Search for a company by name or CIF

curl "https://api.novicap.com/v1/search?api_key=abcd&query=PREPARTS+SL&country=ES"

The above command returns JSON structured like this:

{
  "name": "PRECISSION PARTS PREPARTS SL.",
  "location": "Barcelona",
  "is_public_entity": false,
  "registration_number": "B65354490",
  "country": "ES",
  "size": "unknown",
  "novicap_id": "ESB65354490"
}

Searches for a company in our database. Returns a unique novicap_id which is used to represent that company in all other requests.

HTTP Request

GET http://api.novicap.com/v1/search

Query Parameters

Parameter Default Required Description
api_key Your api key for authentication.
query The search query. Can be a company name, e.g. “PREPARTS SL” or a CIF/VAT number, e.g. “B65354490”
country “ES” An ISO Alpha-2 country code. The company should be incorporated in this country.

Response

A successful response is a JSON compatible with this schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Search result representation in json schema",
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "is_public_entity": { "type": "boolean" },
    "location": { "type": "string" },
    "name": { "type": "string" },
    "novicap_id": { "type": "string" },
    "registration_number": { "type": "string" },
    "size": { "type": "string" }
  }
}

A successful response is a JSON payload with these fields:

Variable Type Description
country String An ISO Alpha-2 country code matching the location.
is_public_entity Boolean Whether the company is listed as a public administration.
location String The location of incorporation of the company.
name String The official name of the company.
novicap_id String The novicap_id of the company. This will not change and can be used in subsequent requests.
registration_number String A legal identifier of the company. In Spain, this is the CIF code.
size String The approximate size of the company (revenue). One of: very_large, large, medium, small, very_small, unknown.

Request a line quote

curl "https://api.novicap.com/line_quote" --data api_key=abcd \
                                                 &company_novicap_id=ES123456 \
                                                 &debtor_novicap_ids[]=ES234567 \
                                                 &debtor_novicap_ids[]=ES345678

The above command returns JSON structured like this:

{
  "quote_id": "wxyz"
}

Submit a company and an optional list of debtors for an automatic price quote. Returns a quote ID that can be used to poll for the quote.

HTTP Request

POST http://api.novicap.com/v1/line_quote

Query Parameters

Parameter Default Required Description
api_key Your api key for authentication.
company_novicap_id The novicap_id of the company you want a quote for.
debtor_novicap_ids[] [] An array of novicap_ids of debtors you want quotes for.

Retrieve a line quote

curl "https://api.novicap.com/line_quote?api_key=abcd&quote_id=wxyz"

The above command returns JSON structured like this:

{
  "status": "ok",
  "credit_limit": 200000,
  "opening_fee": 2.25,
  "commission": 900
}

Exchange a quote ID for a quote.

The response has a status parameter. If this is ok, the quote is ready to use. Any other status means that the quote is not available or may be incomplete:

Status Explanation
ok Quote successful, included in the response.
processing The quote is still processing. Try again in a few seconds.
review NoviCap could not provide an automatic price quote. The quote may be provided at a later date, or the team may be in contact.
rejected NoviCap cannot provide a quote because the company does not pass financing requirements.
taken The company already has an account with NoviCap, or a different partner is already associated with the company.

HTTP Request

GET http://api.novicap.com/v1/line_quote

URL Parameters

Parameter Default Required Description
api_key Your api key for authentication.
quote_id The quote ID retrieved from the previous step.

Response

A successful response is a JSON compatible with this schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "This is the definition for a line_quote",
  "type": "object",
  "properties": {
    "commissions": { "type": "number" },
    "credit_limit": { "type": "number" },
    "debtors": {
      "type": "array,null",
      "items": {
        "type": "object",
        "required": ["debtor_novicap_id", "status"],
        "properties": {
          "advance_rate": { "type": "number" },
          "debtor_novicap_id": { "type": "string" },
          "interest_rate": { "type": "number" },
          "invoice_handling_fee": { "type": "number" },
          "status": { "type": "string" }
        }
      }
    },
    "opening_fee": { "type": "number" }
  }
}

A successful response is a JSON payload with these fields:

Variable Type Unit Description
status String One of “ok”, “review”, or “rejected”.
credit_limit Number The size of the credit line NoviCap can provide to the company.
opening_fee Number % The fee NoviCap will charge to open the credit line as a percentage of the credit limit.
commission Number The commission the partner will make if the company opens the line.
debtors Array A list of debtors that were priced as part of the quote.

Each debtor in debtors has these fields:

Variable Type Unit Description
advance_rate Number % The percentage of the total value of the invoice NoviCap will advance.
interest_rate Number % The annual interest rate NoviCap will charge as a percentage of the amount advanced.
invoice_handling_fee Number % The fee NoviCap will charge as a percentage of the amount advanced.
status String One of “ok”, “review”, or “rejected”.

Retrieve companies

curl "https://api.novicap.com/companies?api_key=abcd"

The above command returns the following JSON:

[
  {
    "name": "Company 937",
    "novicap_id": "ESA32340135",
    "status": "approved_for_trading",
    "line_limit": 1000000,
    "line_usage": 0,
    "line_remainder": 1000000,
    "debtors": [
      {
        "novicap_id": "ESA33218306",
        "name": "Debtor 1744",
        "max_allowed_limit": 10000,
        "status": "draft"
      }
    ]
  }
]

Returns an array with your associated companies.

HTTP Request

GET http://api.novicap.com/v1/companies?api_key=abcd&status=pending

URL Parameters

Parameter Default Required Description
api_key Your api key for authentication.
status Filter companies by current status. It maybe one of “rejected”, “not_registered”, “activated” or “onboarding”

Response

A successful response is a JSON compatible with this schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Companies endpoint json schema. It contains data about partner's companies and debtors",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "novicap_id": { "type": "string" },
      "status": {
        "type": "string",
        "description": "One of 'not_registered', 'onboarding', 'activated' and 'rejected'"
      },
      "name": { "type": "string" },
      "line_limit": { "type": "number" },
      "line_usage": { "type": "number" },
      "line_remainder": { "type": "number" },
      "debtors": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "novicap_id": { "type": "string" },
            "status": {
              "type": "string",
              "description": "One of 'new', 'trading' and 'rejected'"
            },
            "name": { "type": "string" },
            "max_allowed_limit": { "type": "number,null"}
          }
        }
      }
    }
  }
}

A successful response is a JSON payload with these fields:

Variable Type Unit Description
currency String The currency of the credit line. It may be “EUR” or “GBP”.
debtors Array The companies’ debtors.
line_limit Number cents The size of the credit line NoviCap can provide to the company.
line_remainder Number cents The amount currently available for the company.
line_usage Number cents The amount currently used by the company.
name String The name of the company.
novicap_id String The novicap_id of the company.
status String One of ‘not_registered’, 'onboarding’, 'activated’ and 'rejected’.

Each debtor in debtors has these fields:

Variable Type Unit Description
novicap_id String The novicap_id of the company.
status String One of “new”, “trading”, or “rejected”.
name String The name of the debtor.
max_allowed_limit Number cents The max allowed limit for this debtor.

Create an invoice

This endoint allows you to create invoices automatically.

Note that you should have at least one sold invoice in NoviCap before create new ones using this endpoint.

curl -H "Content-Type: application/json" \
-X POST -d '{
  "api_key": ":your_api_key",
  "invoice": {
    "company_novicap_id": "ESX7895123H",
    "debtor_novicap_id": "ESX7895123H",
    "due_at": "2017-04-15",
    "issued_at": "2017-03-15",
    "reference": "201702"
  }
}' \
"https://api.novicap.com/v1/invoices"

The above command returns the following response:


{
  "advance_amount":            0,
  "company_name":              "Company 73",
  "company_novicap_id":        "ESX7895123H",
  "cost":                      100,
  "debtor_name":               "Debtor Inc.",
  "debtor_novicap_id":         "ESX8445123H",
  "due_date":                  "2017-04-15",
  "grace_period_cost_per_day": 16.25,
  "grace_period_end_date":     "2017-03-15",
  "interest_rate":             650,
  "investment_period":         30,
  "invoice_amount":            10000,
  "overdue_cost_per_day":      30,
  "receive_on_due_date":       7713,
  "status":                    "approved",
  "transaction_number":        "IG-001333"
}

Possible returned status codes:

HTTP Request

POST https://api.novicap.com/v1/invoices

The params for this endpoint should match this json schema:

{
  "type": "object",
  "properties": {
    "invoice": {
      "type": "object",
      "properties": {
        "amount": { "type": "integer" },
        "reference": { "type": "string,number" },
        "due_at": { "type": "string" },
        "issued_at": { "type": "string" },
        "debtor_novicap_id": { "type": "string" },
        "company_novicap_id": { "type": "string" }
      }
    }
  }
}

Data

Parameter Unit Description
api_key Your api key for authentication.
invoice The invoice you want to create, in json format (see the following table)

The invoice object should have the following fields:

Parameter Unit Description
amount cents The face value of the invoice
company_novicap_id The NoviCap ID of the company.
debtor_novicap_id The NoviCap ID of the debtor associated with the invoice.
due_at Date in iso3601 format The invoice due date.
issued_at Date in iso3601 format The invoice issue date.
reference The invoice reference.

Response

A successful response is a JSON compatible with the following schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Invoice representation in json schema",
  "type": "object",
  "properties": {
    "advance_amount":            { "type": "integer" },
    "advanced_date": {
      "type": "string,null",
      "description": "Formatted in iso 8601"
    },
    "company_name":              { "type": "string" },
    "company_novicap_id":        { "type": "string" },
    "cost":                      { "type": "integer,null" },
    "debtor_name":               { "type": "string" },
    "debtor_novicap_id":         { "type": "string" },
    "due_date":                  {
      "type": "string",
      "description": "Formatted in iso 8601"
    },
    "grace_period_cost_per_day": { "type": "number" },
    "grace_period_end_date":     {
      "type": "string",
      "description": "Formatted in iso 8601"
    },
    "initial_expected_payment_date": {
      "type": "string",
      "description": "Formatted in iso 8601"
    },
    "interest_rate":             { "type": "number" },
    "invoice_amount":            { "type": "integer" },
    "overdue_cost_per_day":      { "type": "number" },
    "payment_date": {
      "type": "string,null",
      "description": "Formatted in iso 8601"
    },
    "receive_on_due_date":       { "type": "string,null" },
    "status":                    { "type": "string" },
    "transaction_number":        { "type": "string" }
  }
}

A successful response is a JSON payload with the following fields:

Variable Type Unit Description
advance_amount Integer cents The amount advanced to the company.
advanced_date String Iso 8601 format The date when NoviCap advanced the funds to the company.
company_name String The name of the company.
company_novicap_id String The NoviCap ID of the company.
cost Integer cents The invoice amount.
currency String The currency of invoice. It may be “EUR” or “GBP”.
debtor_name String The name of the debtor.
debtor_novicap_id String The NoviCap ID of the debtor associated with the invoice.
due_date String ISO 8601 format The invoice due date
grace_period_cost_per_day Number The cost for every day in the grace period.
grace_period_end_date String Iso 8601 format The date at which the grace period ends and the penalty period begins.
initial_expected_payment_date String Iso 8601 format The date on which the company expects the debtor to pay.
interest_rate Number The annual interest rate that the company has to pay on the advanced amount.
invoice_amount Integer The face value of the invoice
overdue_cost_per_day Number The cost for every day overdue.
payment_date String Iso 8601 format The date on which the invoice was paid in full by the debtor (to NoviCap).
receive_on_due_date String cents The difference between what the debtor paid to NoviCap and what the company has to pay back to NoviCap. When the invoice is paid, NoviCap deducts the owed amount and then gives any remaining amount back to the company.
status String The status of the invoice. May be one of: “accepted”, “defaulted”, “financed”, “paid”, “rejected” ore “submitted”.
transaction_number String The Novicap ID of the transaction.

Retrieve all invoices

curl "https://api.novicap.com/invoices?api_key=abcd"

The above command returns the following JSON:

[
  {
    "advance_amount":            90000,
    "company_name":              "Company 73",
    "company_novicap_id":        "ESA62511076",
    "cost":                      2287,
    "debtor_name":               "Debtor 87",
    "debtor_novicap_id":         "ESA21532825",
    "due_date":                  "2017-03-20",
    "grace_period_cost_per_day": 16.25,
    "grace_period_end_date":     "2017-03-25",
    "interest_rate":             650,
    "investment_period":         30,
    "invoice_amount":            100000,
    "overdue_cost_per_day":      30,
    "receive_on_due_date":       7713,
    "status":                    "accepted",
    "transaction_number":        "IG-001333"
  }
]

Returns an array with your associated companies’ invoices.

HTTP Request

GET https://api.novicap.com/v1/invoices?api_key=abcd

URL Parameters

Parameter Default Required Description
api_key Your api key for authentication.
status Filter invoices by current status. It may be one of “accepted”, “defaulted”, “financed”, “paid”, “rejected” or “submitted”.
company_novicap_id Return only invoices related to the given company.
debtor_novicap_id Return only invoices related to the given debtor.

Response

A successful response is a JSON compatible with this schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Array of invoices representation in json schema",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "advance_amount":            { "type": "integer" },
      "advanced_date": {
        "type": "string,null",
        "description": "Formatted in iso 8601"
      },
      "company_name":              { "type": "string" },
      "company_novicap_id":        { "type": "string" },
      "cost":                      { "type": "integer,null" },
      "debtor_name":               { "type": "string" },
      "debtor_novicap_id":         { "type": "string" },
      "due_date":                  {
        "type": "string",
        "description": "Formatted in iso 8601"
      },
      "grace_period_cost_per_day": { "type": "number" },
      "grace_period_end_date":     {
        "type": "string",
        "description": "Formatted in iso 8601"
      },
      "initial_expected_payment_date": {
        "type": "string",
        "description": "Formatted in iso 8601"
      },
      "interest_rate":             { "type": "number" },
      "invoice_amount":            { "type": "integer" },
      "overdue_cost_per_day":      { "type": "number" },
      "payment_date": {
        "type": "string,null",
        "description": "Formatted in iso 8601"
      },
      "receive_on_due_date":       { "type": "string,null" },
      "status":                    { "type": "string" },
      "transaction_number":        { "type": "string" }
    }
  }
}

A successful response is a JSON payload with the following fields for each item:

Variable Type Unit Description
advance_amount Integer cents The amount advanced to the company.
advanced_date String Iso 8601 format The date when NoviCap advanced the funds to the company.
company_name String The name of the company.
company_novicap_id String The NoviCap ID of the company.
cost Integer cents The invoice amount.
currency String The currency of invoice. It may be “EUR” or “GBP”.
debtor_name String The name of the debtor.
debtor_novicap_id String The NoviCap ID of the debtor associated with the invoice.
due_date String ISO 8601 format The invoice due date
grace_period_cost_per_day Number The cost for every day in the grace period.
grace_period_end_date String Iso 8601 format The date at which the grace period ends and the penalty period begins.
initial_expected_payment_date String Iso 8601 format The date on which the company expects the debtor to pay.
interest_rate Number The annual interest rate that the company has to pay on the advanced amount.
invoice_amount Integer The face value of the invoice
overdue_cost_per_day Number The cost for every day overdue.
payment_date String Iso 8601 format The date on which the invoice was paid in full by the debtor (to NoviCap).
receive_on_due_date String cents The difference between what the debtor paid to NoviCap and what the company has to pay back to NoviCap. When the invoice is paid, NoviCap deducts the owed amount and then gives any remaining amount back to the company.
status String The status of the invoice. May be one of: “accepted”, “defaulted”, “financed”, “paid”, “rejected” ore “submitted”.
transaction_number String The Novicap ID of the transaction.

Retrieve a single invoice

curl "https://api.novicap.com/invoices/:transaction_number?api_key=abcd"

The above command returns the following JSON:


{
  "advance_amount":            90000,
  "company_name":              "Company 73",
  "company_novicap_id":        "ESA62511076",
  "cost":                      2287,
  "debtor_name":               "Debtor 87",
  "debtor_novicap_id":         "ESA21532825",
  "due_date":                  "2017-03-20",
  "grace_period_cost_per_day": 16.25,
  "grace_period_end_date":     "2017-03-25",
  "interest_rate":             650,
  "investment_period":         30,
  "invoice_amount":            100000,
  "overdue_cost_per_day":      30,
  "receive_on_due_date":       7713,
  "status":                    "accepted",
  "transaction_number":        "IG-001333"
}

Returns one invoice using the transaction_number. Note that this invoice should belong to your company, otherwise you’ll get an error.

HTTP Request

GET https://api.novicap.com/v1/invoices/:transaction_number?api_key=abcd

URL Parameters

Parameter Default Required Description
api_key Your api key for authentication.

Response

A successful response is a JSON compatible with this schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Invoice representation in json schema",
  "type": "object",
  "properties": {
    "advance_amount":            { "type": "integer" },
    "advanced_date": {
      "type": "string,null",
      "description": "Formatted in iso 8601"
    },
    "company_name":              { "type": "string" },
    "company_novicap_id":        { "type": "string" },
    "cost":                      { "type": "integer,null" },
    "debtor_name":               { "type": "string" },
    "debtor_novicap_id":         { "type": "string" },
    "due_date":                  {
      "type": "string",
      "description": "Formatted in iso 8601"
    },
    "grace_period_cost_per_day": { "type": "number" },
    "grace_period_due_date":     {
      "type": "string",
      "description": "Formatted in iso 8601"
    },
    "initial_expected_payment_date": {
      "type": "string",
      "description": "Formatted in iso 8601"
    },
    "interest_rate":             { "type": "number" },
    "invoice_amount":            { "type": "integer" },
    "overdue_cost_per_day":      { "type": "number" },
    "payment_date": {
      "type": "string,null",
      "description": "Formatted in iso 8601"
    },
    "receive_on_due_date":       { "type": "string,null" },
    "status":                    { "type": "string" },
    "transaction_number":        { "type": "string" }
  }
}

A successful response is a JSON payload with the following fields:

Variable Type Unit Description
advance_amount Integer cents The amount advanced to the company.
advanced_date String Iso 8601 format The date when NoviCap advanced the funds to the company.
company_name String The name of the company.
company_novicap_id String The NoviCap ID of the company.
cost Integer cents The invoice amount.
currency String The currency of invoice. It may be “EUR” or “GBP”.
debtor_name String The name of the debtor.
debtor_novicap_id String The NoviCap ID of the debtor associated with the invoice.
due_date String ISO 8601 format The invoice due date
grace_period_cost_per_day Number The cost for every day in the grace period.
grace_period_end_date String Iso 8601 format The date at which the grace period ends and the penalty period begins.
initial_expected_payment_date String Iso 8601 format The date on which the company expects the debtor to pay.
interest_rate Number The annual interest rate that the company has to pay on the advanced amount.
invoice_amount Integer The face value of the invoice
overdue_cost_per_day Number The cost for every day overdue.
payment_date String Iso 8601 format The date on which the invoice was paid in full by the debtor (to NoviCap).
receive_on_due_date String cents The difference between what the debtor paid to NoviCap and what the company has to pay back to NoviCap. When the invoice is paid, NoviCap deducts the owed amount and then gives any remaining amount back to the company.
status String The status of the invoice. May be one of: “accepted”, “defaulted”, “financed”, “paid”, “rejected” ore “submitted”.
transaction_number String The Novicap ID of the transaction.

Accept an invoice

This endpoint allows you to accept an existing invoice.

Note that you can only accept invoices for trade relationships that already have at least one invoice sold.

curl "https://api.novicap.com/v1/invoices/:transaction_number/acceptance" --data "api_key=abcd"

The above command returns a empty JSON with the 201 CREATE status.

Possible returned status codes:

HTTP Request

POST https://api.novicap.com/v1/invoices/:transaction_number/acceptance

Data

Parameter Type Description
api_key String Your api key for authentication.
transaction_number String The Novicap ID of the transaction

Response

A successful response is an empty JSON with a proper HTTP status code.

Mark an invoice as approved by debtor

This endpoint allows you to mark an existing invoice as approved by debtor.

Note that you can only approve invoices for trade relationships that already have at least one invoice sold.

curl "https://api.novicap.com/v1/invoices/:transaction_number/approved_by_debtor" --data "api_key=abcd"

The above command returns a empty JSON with the 201 CREATE status.

Possible returned status codes:

HTTP Request

POST https://api.novicap.com/v1/invoices/:transaction_number/approved_by_debtor

Data

Parameter Type Description
api_key String Your api key for authentication.
transaction_number String The Novicap ID of the transaction

Response

A successful response is an empty JSON with a proper HTTP status code.

Mark an invoice as paid by debtor

This endpoint allows you to mark an existing invoice as paid by debtor.

Note that you can only update invoices for trade relationships that already have at least one invoice sold.

curl "https://api.novicap.com/v1/invoices/:transaction_number/paid_by_debtor" --data "api_key=abcd"

The above command returns a empty JSON with the 201 CREATE status.

Possible returned status codes:

HTTP Request

POST https://api.novicap.com/v1/invoices/:transaction_number/paid_by_debtor

Data

Parameter Type Description
api_key String Your api key for authentication.
transaction_number String The Novicap ID of the transaction

Response

A successful response is an empty JSON with a proper HTTP status code.

Add a comment to an invoice

This endpoint allows you to attach a comment to an existing invoice. This comment will be reviewed by our operations team and is free text.

Example uses would be notifications of delays in payment, reduction of the invoice amount, status changes in the debtor ERP, …

curl -H "Content-Type: application/json" \
-X POST -d '{"api_key":":api_key", "comment": "Test comment"}' \
"https://api.novicap.com/v1/invoices/:transaction_number/comments"

The above command returns a empty JSON with the 201 CREATE status.

Possible returned status codes:

HTTP Request

POST https://api.novicap.com/v1/invoices/:transaction_number/comments

Data

Parameter Type Description
api_key String Your api key for authentication.
comment String The body of the comment.
transaction_number String The Novicap ID of the transaction

Response

A successful response is an empty JSON with a proper HTTP status code.

Retrieve invoice comments

This endpoint allows you to retrieve your comments for a specific invoice.

curl "https://api.novicap.com/v1/invoices/:transaction_number/comments?api_key=your_api_key"

The above command returns a JSON with a list of comments:

[
  {
    "comment": "An invoice comment",
    "created_at": "2017-03-06T00:00:00Z",
    "author_name": "Author Name"
  }
]

HTTP Request

GET https://api.novicap.com/v1/invoices/:transaction_number/comments

URL Parameters

Parameter Type Description
api_key String Your api key for authentication.
transaction_number String The Novicap ID of the transaction

Response

A successful response is a JSON compatible with this schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Comment representation in json schema",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "author_name": { "type": "string" },
      "comment": { "type": "string" },
      "created_at": { "type": "string" }
    }
  }
}

A successful response is a JSON payload with the following fields for each item:

Variable Type Unit Description
author_name String The name of the author.
comment String The body of the comment.
create_at String Iso 8601 format A timestamp with the comment creation time.

Errors

Error Code Meaning
400 Bad Request – The formatting of the request is wrong
401 Unauthorized – Your API key is wrong
403 Forbidden – You do not have permission to perform that action
404 Not Found – The specified quote ID could not be found
500 Internal Server Error – We had a problem with our server - contact support or try again later
503 Service Unavailable – We’re temporarily offline for maintenance - try again later