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, there are two ways:

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

curl -H "Authorization: Bearer abcd" https://api.novicap.com/v1/line_quote

where abcd should be replaced with your API key.

We use an API key to authenticate which can be found in your partner portal > settings under API key section at novicap.com. It is possible to refresh the API key automatically by enabling this in your partner portal > settings > activate at novicap.com

The API key should be included in all requests to the server either as a HTTP request parameter named api_key or inside an Authorization: Bearer HTTP request header.

Refresh Token Authentication

To refresh the API key, there are three ways:

curl -X POST https://api.novicap.com/v1/token?api_key=abcd&refresh_token=wxyz

curl -X POST -H 'Authorization: Basic abcd' https://api.novicap.com/v1/token \
     --data '{ "refresh_token": "wxyz" }'

curl -X POST https://api.novicap.com/v1/token \
     --data '{ "client_secret": "abcd", "refresh_token": "wxyz" }'

where abcd should be replaced with your current API key and wxyz with your current Refresh Token.

The format of the response is as follows:

{
  "token_type": "bearer",
  "access_token": "new_access_token",
  "refresh_token": "new_refresh_token",
  "expires_in": 86400 (in seconds)
}

By default the API key does not expire, although is possible to make them expire after 1 day. You can enable this option by logging into your partner account at novicap.com

When enabled, you are no longer able to generate new API keys in the partner account and you will be required to refresh your api key with the refresh token API endpoint when it expires. The refresh token can be found un your partner portal > settings under Refresh Token API section at novicap.com.

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=abcd&company_novicap_id=ESB50460609&debtor_novicap_id=ESA08002883&details=eyJmaXJzdF9uYW1lIjoiSm9obiIsImxhc3RfbmFtZSI6IlNub3ciLCJwaG9uZSI6IjcyNDU2NTg5OCIsImVtYWlsIjoic25vd0Bub3ZpY2FwLmNvbSJ9

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

json hash encoded in base64:

eyJmaXJzdF9uYW1lIjoiSm9obiIsImxhc3RfbmFtZSI6IlNub3ciLCJwaG9uZSI6IjcyNDU2NTg5OCIsImVtYWlsIjoic25vd0Bub3ZpY2FwLmNvbSJ9

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 https://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 -H "Content-Type: application/json" \
-X POST -d '{
  "api_key": "abcd",
  "company_novicap_id": "ESA12345678",
  "debtor_novicap_ids": ["ESB12345678", "ESC12345678"]
}' \
"https://api.novicap.com/v1/line_quotes"

The above command returns the following response:

{
  "quote_id": "wxyz",
  "company_novicap_id": "ESA12345678",
  "debtor_novicap_ids": ["ESB12345678", "ESC12345678"]
}

This endpoint allows you to request a line quote for a company.

Submit a company and an optional list of debtors for an automatic price quote.

It returns a quote ID that can be used to poll for the quote.

HTTP Request

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

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": ["api_key", "company_novicap_id"],
  "properties": {
    "api_key": { "type": "string" },
    "company_novicap_id": { "type": "string" },
    "debtor_novicap_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}
Parameter Type Required Default Description
api_key String Your API key for authentication
company_novicap_id String The novicap_id of the company you want a quote for
debtor_novicap_ids Array [] An array of novicap_ids of debtors you want quotes for

Response

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

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "quote_id": { "type": "string" },
    "company_novicap_id": { "type": "string" },
    "debtor_novicap_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

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

Attribute Type Description
quote_id String The ID that can be used to poll for the quote
company_novicap_id String The novicap_id of the company you asked for the quote
debtor_novicap_ids Array The array of novicap_ids of debtors you asked for the quote

Status Codes

Code Meaning Description
202 Accepted The line quote request has been received and our system is processing it
422 Unprocessable Entity The company NoviCap ID is not present

Retrieve a line quote

curl -H "Content-Type: application/json" \
"https://api.novicap.com/v1/line_quotes/wxyz?api_key=abcd"

The above command returns the following response:

{
  "status": "ok",
  "company_novicap_id": "ESA12345678",
  "credit_limit": 70000.0,
  "provisional_quote": false,
  "debtors": [
    {
      "debtor_novicap_id": "ESB12345678",
      "status": "ok",
      "credit_limit": 50000.0,
      "interest_rate": 4.8,
      "invoice_handling_fee": 0.5,
      "advance_rate": 70.0
    },
    {
      "debtor_novicap_id": "ESC12345678",
      "status": "rejected"
    }
  ]
}

This endpoint allows you to retrieve the data for a quote using an existing quote ID.

HTTP Request

GET https://api.novicap.com/v1/line_quotes/:quote_id

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": ["api_key", "quote_id"],
  "properties": {
    "api_key": { "type": "string" },
    "quote_id": { "type": "string" }
  }
}
Parameter Type Required Description
api_key String Your API key for authentication
quote_id String The quote ID retrieved from the previous step

Response

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

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "company_novicap_id": { "type": ["null", "string"] },
    "credit_limit": { "type": ["null", "number"] },
    "provisional_quote": { "type": ["null", "boolean"] },
    "debtors": {
      "type": ["null", "array"],
      "items": {
        "type": "object",
        "properties": {
          "debtor_novicap_id": { "type": "string" },
          "status": { "type": "string" },
          "credit_limit": { "type": ["null", "number"] },
          "advance_rate": { "type": ["null", "number"] },
          "interest_rate": { "type": ["null", "number"] },
          "invoice_handling_fee": { "type": ["null", "number"] }
        }
      }
    }
  }
}

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

Attribute Type Unit Description
status String One of “ok”, “processing”, or “review”
company_novicap_id String The NoviCap ID of the company associated to the quote
credit_limit Number The size of the credit line NoviCap can provide to the company
provisional_quote Boolean Indicates if the quote is provisional and if the credit limit could be higher when more financial documentation is provided
debtors Array A list of debtors that were priced as part of the quote

Each debtor in debtors has these fields:

Attribute Type Unit Description
advance_rate Number % The percentage of the total value of the invoice NoviCap will advance
credit_limit Number The size of the credit line NoviCap can provide to the company for this debtor
debtor_novicap_id String The NoviCap ID of the debtor company
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”, “rejected”, or “review”

Status

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

Status Codes

Code Meaning Description
200 Success The line quote request has been correctly processed
202 Accepted The line quote request is still processing
422 Unprocessable Entity The quote ID is invalid

Retrieve all companies

curl -H "Content-Type: application/json" \
"https://api.novicap.com/v1/companies?api_key=abcd"

The above command returns the following response:

{
  "data": [
    {
      "currency": "EUR",
      "name": "MERCADONA SA",
      "novicap_id": "ESA46103834",
      "status": "not_registered",
      "line_limit": 17000000,
      "line_usage": 0.0,
      "line_remainder": 0.0,
      "debtors": [
        {
        "novicap_id": "ESA46103834",
        "name": "LAVINIA BROADCASTING SL",
        "max_allowed_limit": null,
        "status": "new"
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

This endpoint allows you to retrieve the companies associated to you.

HTTP Request

GET https://api.novicap.com/v1/companies

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": ["api_key"],
  "properties": {
    "api_key": { "type": "string" },
    "status": { "type": "string" }
  }
}
Parameter Type Required Description
api_key String Your API key for authentication
status String Filter companies by current status. It maybe one of “rejected”, “not_registered”, “activated” or “onboarding”

Response

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

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "currency": { "type": "string" },
          "name": { "type": "string" },
          "novicap_id": { "type": "string" },
          "status": { "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" },
                "name": { "type": "string" },
                "max_allowed_limit": { "type": ["null", "number"] },
                "status": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "meta": {
      "current_page": { "type": "number" },
      "next_page": { "type": ["null", "number"] },
      "prev_page": { "type": ["null", "number"] },
      "total_pages": { "type": "number" },
      "total_count": { "type": "number" }
    }
  }
}

A company has the following fields:

Attribute Type Unit Description
currency String ISO 4217 The currency of the credit line. It may be “EUR” or “GBP”
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’
line_limit Number cents The size of the credit line NoviCap can provide to the company
line_usage Number cents The amount currently used by the company
line_remainder Number cents The amount currently available for the company
debtors Array The companies’ debtors

Each debtor in debtors has the following fields:

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

Status Codes

Code Meaning Description
200 Success The companies are returned in the response
422 Unprocessable Entity The status code is not valid

Create an invoice

curl -H "Content-Type: application/json" \
-X POST -d '{
  "api_key": "abcd",
  "reference": "20170832",
  "company_novicap_id": "ESA46103834",
  "debtor_novicap_id": "ESB66367129",
  "amount": 150000,
  "issued_at": "2017-08-12",
  "due_at": "2017-10-12"
}' \
"https://api.novicap.com/v1/invoices"

The above command returns the following response:

{
  "data": {
    "id": "I-1A2B",
    "reference": "20170832",
    "invoice_amount": 150000,
    "currency": "EUR",
    "company_name": "MERCADONA SA",
    "company_novicap_id": "ESA46103834",
    "debtor_name": "LAVINIA BROADCASTING SL",
    "debtor_novicap_id": "ESB66367129",
    "issued_at": "2017-08-12",
    "due_at": "2017-10-12",
    "status": "draft"
  }
}

This endpoint allows you to create an invoice for a company.

If the company is not using NoviCap yet, it will be created and associated to you.

HTTP Request

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

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": ["api_key", "reference", "company_novicap_id", "debtor_novicap_id", "amount", "issued_at", "due_at"],
  "properties": {
    "api_key": { "type": "string" },
    "reference": { "type": "string" },
    "company_novicap_id": { "type": "string" },
    "debtor_novicap_id": { "type": "string" },
    "amount": { "type": "number" },
    "issued_at": { "type": "string" },
    "due_at": { "type": "string" }
  }
}
Parameter Type Required Format Description
api_key String Your API key for authentication
reference String The reference used by the company for this invoice
company_novicap_id String The NoviCap ID of the company associated with the invoice
debtor_novicap_id String The NoviCap ID of the debtor associated with the invoice
amount Integer cents The total amount of the invoice
issued_at String ISO 8601 The date when the invoice was issued
due_at String ISO 8601 The invoice due date

Response

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

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "reference": { "type": "string" },
        "invoice_amount": { "type": "number" },
        "currency": { "type": "string" },
        "company_name": { "type": "string" },
        "company_novicap_id": { "type": "string" },
        "debtor_name": { "type": "string" },
        "debtor_novicap_id": { "type": "string" },
        "issued_at": { "type": "string" },
        "due_at": { "type": "string" },
        "status": { "type": "string" }
      }
    }
  }
}

An invoice has the following fields:

Attribute Type Unit Description
id String The ID of the invoice
reference String The reference used by the company for this invoice
invoice_amount Number cents The total amount of the invoice
currency String ISO 4217 The currency of invoice
company_name String The name of the company
company_novicap_id String The NoviCap ID of the company associated with the invoice
debtor_name String The name of the debtor
debtor_novicap_id String The NoviCap ID of the debtor associated with the invoice
issued_at String ISO 8601 The date when the invoice was issued
due_at String ISO 8601 The invoice due date
status String The status of the invoice

Status Codes

Code Meaning Description
201 Created The invoice has been successfully created
403 Forbidden The provided company is associated to another partner
409 Conflict The invoice was not created because an invoice with the same debtor and reference already exists
422 Unprocessable Entity The invoice has not been created because of errors

Retrieve all invoices

curl -H "Content-Type: application/json" \
"https://api.novicap.com/v1/invoices?api_key=abcd"

The above command returns the following response:

{
  "data": [
    {
      "id": "I-1A2B",
      "reference": "20170832",
      "invoice_amount": 150000,
      "currency": "EUR",
      "company_name": "MERCADONA SA",
      "company_novicap_id": "ESA46103834",
      "debtor_name": "LAVINIA BROADCASTING SL",
      "debtor_novicap_id": "ESB66367129",
      "issued_at": "2017-08-12",
      "due_at": "2017-10-12",
      "status": "draft"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

This endpoint allows you to retrieve the invoices associated to all your companies.

HTTP Request

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

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": ["api_key"],
  "properties": {
    "api_key": { "type": "string" },
    "company_novicap_id": { "type": "string" },
    "debtor_novicap_id": { "type": "string" }
  }
}
Parameter Type Required Description
api_key String Your API key for authentication
company_novicap_id String The company ID you want to filter invoices for
debtor_novicap_id String The debtor ID you want to filter invoices for

Response

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

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "reference": { "type": "string" },
          "invoice_amount": { "type": "number" },
          "currency": { "type": "string" },
          "company_name": { "type": "string" },
          "company_novicap_id": { "type": "string" },
          "debtor_name": { "type": "string" },
          "debtor_novicap_id": { "type": "string" },
          "issued_at": { "type": "string" },
          "due_at": { "type": "string" },
          "status": { "type": "string" }
        }
      }
    },
    "meta": {
      "current_page": { "type": "number" },
      "next_page": { "type": ["null", "number"] },
      "prev_page": { "type": ["null", "number"] },
      "total_pages": { "type": "number" },
      "total_count": { "type": "number" }
    }
  }
}

An invoice has the following fields:

Attribute Type Unit Description
id String The ID of the invoice
reference String The reference used by the company for this invoice
invoice_amount Number cents The total amount of the invoice
currency String ISO 4217 The currency of invoice
company_name String The name of the company
company_novicap_id String The NoviCap ID of the company associated with the invoice
debtor_name String The name of the debtor
debtor_novicap_id String The NoviCap ID of the debtor associated with the invoice
issued_at String ISO 8601 The date when the invoice was issued
due_at String ISO 8601 The invoice due date
status String The status of the invoice

Status Codes

Code Meaning Description
200 Success The companies’ invoices are returned in the response

Retrieve a single invoice

curl -H "Content-Type: application/json" \
"https://api.novicap.com/v1/invoices/I-1A2B?api_key=abcd"

The above command returns the following response:

{
  "data": {
    "id": "I-1A2B",
    "reference": "20170832",
    "invoice_amount": 150000,
    "currency": "EUR",
    "company_name": "MERCADONA SA",
    "company_novicap_id": "ESA46103834",
    "debtor_name": "LAVINIA BROADCASTING SL",
    "debtor_novicap_id": "ESB66367129",
    "issued_at": "2017-08-12",
    "due_at": "2017-10-12",
    "status": "draft"
  }
}

This endpoint allows you to retrieve a single invoice associated to your companies.

HTTP Request

GET https://api.novicap.com/v1/invoices/:invoice_id

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": ["api_key"],
  "properties": {
    "api_key": { "type": "string" }
  }
}
Parameter Type Required Description
api_key String Your API key for authentication
id String The invoice ID

Response

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

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "reference": { "type": "string" },
        "invoice_amount": { "type": "number" },
        "currency": { "type": "string" },
        "company_name": { "type": "string" },
        "company_novicap_id": { "type": "string" },
        "debtor_name": { "type": "string" },
        "debtor_novicap_id": { "type": "string" },
        "issued_at": { "type": "string" },
        "due_at": { "type": "string" },
        "status": { "type": "string" }
      }
    }
  }
}

An invoice has the following fields:

Attribute Type Unit Description
id String The ID of the invoice
reference String The reference used by the company for this invoice
invoice_amount Number cents The total amount of the invoice
currency String ISO 4217 The currency of invoice
company_name String The name of the company
company_novicap_id String The NoviCap ID of the company associated with the invoice
debtor_name String The name of the debtor
debtor_novicap_id String The NoviCap ID of the debtor associated with the invoice
issued_at String ISO 8601 The date when the invoice was issued
due_at String ISO 8601 The invoice due date
status String The status of the invoice

Status Codes

Code Meaning Description
200 Success The requested invoice is returned in the response
404 Not Found The requested invoice does not exist or is not associated to one of your companies

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":"abcd", "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=abcd"

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.

Create a user

curl -H "Content-Type: application/json" \
-X POST -d '{
  "api_key": "abcd",
  "company_novicap_id": "ESX7895123H",
  "first_name": "John",
  "last_name": "Snow",
  "email": "snow@novicap.com",
  "phone": "724565898",
  "language": "es"
}' \
"https://api.novicap.com/v1/users"

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

This endpoint allows you to create a user in a company that has no users associated.

If the company is not using NoviCap yet, it will be created and associated to you.

If the user does not have an account on NoviCap yet, he/she will receive an email to set the password.

HTTP Request

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

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": ["api_key", "company_novicap_id", "first_name", "last_name", "email"],
  "properties": {
    "api_key": { "type": "string" },
    "company_novicap_id": { "type": "string" },
    "first_name": { "type": "string" },
    "last_name": { "type": "string" },
    "email": { "type": "string" },
    "phone": { "type": ["null", "string"] },
    "language": { "type": ["null", "string"] }
  }
}
Parameter Type Required Format Description
api_key String Your API key for authentication
company_novicap_id String The NoviCap ID of the company you want to add the user to
first_name String The user’s first name
last_name String The user’s last name
email String The user’s email
phone String The user’s phone
language String ISO 639-1 The user’s language

Response

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

Status Codes

Code Meaning Description
201 Created The user has been successfully created
403 Forbidden The provided company is associated to another partner
409 Conflict The company is already associated with another user
422 Unprocessable Entity The user has not been created because of errors

Errors

Status 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
{
    "errors": {
        "reference": [
            {
                "code": "ERR002",
                "detail": "Can't be blank"
            }
        ],
        "expected_paid_at": [
            {
                "code": "ERR036",
                "detail": "The invoice must last at least 3 days",
                "values": {
                    "value_0": "3"
                }
            },
            {
                "code": "ERR031",
                "detail": "Expected payment date cannot be in the past"
            }
        ],
        "amount": [
            {
                "code": "ERR027",
                "detail": "Only invoices with a value greater than or equal to €100.00 can be accepted."
            }
        ]
    }
}

Error messages can be localized by passing a language parameter in the request with a supported language value (eg. https://api.novicap.com/v1/invoices?language=es)

Error Code Meaning
ERR000 Is invalid
ERR001 Must be accepted
ERR002 Can’t be blank
ERR003 Must be blank
ERR004 Doesn’t match %{value_0}
ERR005 Can’t be empty
ERR006 Must be equal to %{value_0}
ERR007 Must be even
ERR008 Is reserved
ERR009 Must be greater than %{value_0}
ERR010 Must be greater than or equal to %{value_0}
ERR011 Is not included in the list
ERR012 Must be less than %{value_0}
ERR013 Must be less than or equal to %{value_0}
ERR014 Validation failed: %{value_0}
ERR015 Is not a number
ERR016 Must be an integer
ERR017 Must be odd
ERR018 Must exist
ERR019 Has already been taken
ERR020 Is too long (maximum is 1 character)
ERR021 Is too long (maximum is %{value_0} characters)
ERR022 Is too short (minimum is 1 character)
ERR023 Is too short (minimum is %{value_0} characters)
ERR024 Is the wrong length (should be 1 character)
ERR025 Is the wrong length (should be %{value_0} characters)
ERR026 Must be other than %{value_0}
ERR027 Only invoices with a value greater than or equal to €100.00 can be accepted
ERR028 Copy of original should be present
ERR029 A copy of the promissory note should be present
ERR030 Due date should be after issue date
ERR031 Expected payment date cannot be in the past
ERR032 Issue date must be in the past
ERR033 Expected payment date should be on or after due date
ERR034 Due date cannot be in the past
ERR035 Due date cannot be more than 180 days after issue date
ERR036 The invoice must last at least %{value_0} days
ERR037 The country prefix is not valid