API CofaServe, functional details

 

The main target of the company search is to reach a final buyer’s identification in the Coface database with an EASY number, and therefore increase the probability of an immediate decision after a request on this buyer.

 

In more details, the search process should always go through the following steps:

a) A search by legal identifier, if at least one legal identifier is available.

    Remarks:

• Depending on the type of legal identifier and the fact that the user’s database can use other formats than the Coface database for identification data, you should make different searches in using different possible formats for a given legal identifier (e.g. with or without blank, …).
• To find out which legal identifier is possible for given country, use the endpoint “GET​/companies​/identifier”.

 

b) If you could not find the company you were looking for, a search by company name should be the next step "GET ​/companies​/name".

• With the most important or representative part of the company name, and

• With the town or the postal code (as well as the region for USA and possessions, Canada, as well as for the possessions of Denmark and Australia)

Remark: The fact not to send all available identification data (e.g. the complete address) raises the probability of a hit. Furthermore, it can be very useful for the user to check if other companies with a similar business name are known by Coface.

 

c) If you did not succeed with one of the above alternatives, perform the request without the EASY number.

In this case, indicate ALL available identification data you have, including all available local identifier as well as the phone and fax numbers (especially for USA and Canada”) to increase the probability for Coface to of identify the company.

 

Temporary EASY number

The web service answers requests on buyers without an Easy number with a pending status and a temporary EASY number (beginnings with the letter “Z”). In these cases, Coface has first to identify the requested buyer before sending its final decision.

Remark: As the final decision is notified with the definitive EASY number, you must use the orderID to link this final decision with the original request and replace the temporary EASY number by the final one.

 

Display of matched addresses (in case Coface sends back not only one but several companies as a hit list)

In case of a hit list, Coface advises to display establishments (legally dependent branches) in a way that they can be differentiated from the head offices (which are the ones assessed by Coface).

Remark: Request for a product must be only authorized for main establishment / head offices to avoid an error message.

 

Note:  to retrieve the list of country code is available through the service GET ​/countries  and the possible legal value in GET ​/countries​/identifiers

The portfolio lists all the companies that you have applied for in the last two years and that Coface has been able to identify with an Easy Number. As long as a decision is active, the company remains in the portfolio.

• If the company has not been identified with an Easy Number (temporary or permanent) , it is not listed.
• If the decision is cancelled by Coface or deleted by you, the company remains in the portfolio for 2 years from the date of the decision.

After these 2 years, the company and all decisions are no more accessible via CofaServe. However the historic of decisions is available in CofaNet.

 

At any time, you can consult the list of active decisions and the status in force with the service GET ​/companies​/products

Are listed companies with an "active" product, or with a "pending" status, and the main detail of the last decision taken by product ordered for the company listed.

Decisions archived are stored for 2 years.

 

You can filter your portfolio based on different criterias, if any:

• EasyNumber
• CustomerReference
• OrderId
• DeliveryId
• Date*
• Product code
• Country

Note: *concerning the date format, The format is interpreted in this way : For instance, "2020-07-01" = 2020-07-01T00:00:00 (GMT). Thus, if you want to retrieve all decisions made including the 1st of July 2020, you must set the date field to "2020-07-02" (you have to add one day, 2020-07-01 + 1 day)

 

MY CUSTOMER REFERENCE

 

you can set to a company your own reference, named « Customer Reference ». It can be useful if you have specific internal references that you wish to reuse with other internal systems.

Create or Update a specific customerReference on a company

PATCH ​/companies​/customerreferences

You need to specify your contract number, the easy number and specify the customer reference to set on the company. It will create or update if a reference is already existing.

 

Note: If you want to erase a reference, set a blank in the customer reference attribute

 

To list all customer references already created on a contract number

GET ​/companies​/customerreferences

The best practices to carry on when you want to order a product:

1. Identify your company with the EASY NUMBER

2. Check the product catalog available for this company. The list of products you can order is displayed depending on your special contract terms.

3. Order / Delete the product 

 

The catalog of products 

 

The catalog of Coface products consists of credit insurance products and solvency products. Subject to the contract terms, the catalog will display products you can order for the company searched. If you order a product not authorized for this company, your request will result in an error.

If the order rejection is immediatly provided, despite the catalog options, that means the order is under STATUS_REJECTED (end of lifecycle).The object rejectionReasons (output in services POST/companies/{easyNumber}/products and POST/companies/unknown/products) will be set in the response payload. Further details on rejection codes are available in Utilities resource.

GET ​/companies​/{easyNumber}​/catalog

 

List of possible actions

• CREA   To order a product for the first order
• UPDT   To update an amount of cover
• CHANGE    To transform a product to another. For example, you want to transform your CCO into a credit limit, or you want to move from an ECL to @rating limit or a credit limit
• STOP   To stop the monitoring of ‘score’ products
• DELE   To delete the product by using a specific resource

 

The order and update of following optional products - TopLiner, "awaiting delivery" cover (Pending order, Binding order) or manufacturing cover (pre-shipment cover) - are the subject of their own services. 

• TopLiner, POST ​/companies​/{easyNumber}​/products​/topliner

• Awaiting Delivery or manfacturing cover: POST ​/companies​/{easyNumber}​/products​/awaitingdeliveries-manufacturing

 

Note:  Please go to "Product" menu to get further details by product.

Once a product, or a cover, is modified by you or by Coface, you receive a notification and your portfolio is updated.

 

NOTIFICATION - PUSH

 

Coface alerts you in real time each time there is a change in Coface information system.

Coface produces a short json flow on specific topic you have subscribed to send it out directly to the customer repository.

To implement the service, some steps have to be set-up.

 

1. The client creates an endpoint

 

The creation of the endpoint will enable to receive notifications pushed by Coface when there is a change in the status on an active products for a given contract portfolio.

Amazon Simple Notification Service (Amazon SNS) will deliver notifications and “message” content (from SNS notification envelop) customized for CofaServe usage.

Fanout to HTTP/S endpoints - specification to design Amazon SNS notifications consumer client

 

Then to manage messages sent by Coface from Amazon SNS, you should take into consideration the format customized by Coface to receive CofaServe notifications.

Parsing message formats - Amazon SNS messages description (standard envelop)

Below a table describing all notification fields.



 

2. Subscription to topics

 

Notifications are sorted by “topic” depending of the products the client is subject to. To subscribe to a topic, the client calls the webservice “API Cofaserve – Notification PUSH”

POST ​/topics/{topicName}/subscriptions

The subscription to this service will enable Coface to identify the “topicName” on which the client wants to receive notifications (topic name related with concerned products) and specifies client endPoint to use to retrieve notifications.

topicName	productCode
credit_insurance_cover	ECL, CREDITLIMIT, ARATINGLIMIT, ILU
credit_insurance_special_cover	TOPLINER, OCL
coface_opinion	CCO (customized credit opinion)
scoring	ARATING, ARATINGCHMON, SCORECHECK (DRA), SCOREMON (DRA monitored)
extension_of_due_date	EDD (extension of due date)

 

If you need to strengthen the security, we propose 3 solutions, that can be all or a part implemented:

• Use the subscription with Oauth information details
• Add a query parameter, appended to question-mark character, to build up a final endpoint URI
• Certify the sender with a signature

 

Subscription with Oauth details

 

We also propose the subscription using additional Oauth information details. This will ensure that the client's endpoint has authenticated the message and authorizes to consume the message. It provides you an extra layer security.

POST ​/topics/{topicName}/subscriptions/with-token-auth

By this way, you will specify two kinds of details:

• Client endpoint to use to retrieve notifications
• Oauth details, including client API Authentication endpoint, credentials details and options to use in this context

the concept is simple. Before sending any message, Coface will obtain from his client an authentication token via an API call. The token catched will be then appended to the message being sent.

 

Query parameter in your endpoint URI

Regardless the option selected, a specific parameter can also be used by the client. The optional field "query" in object "endpoint" (schema Subscription.Endpointinput) helps you to add a new query param, thus authorizing the system to build URIs embedding additional parameters.

 

Examples :
{

"endpoint": {

"path": "/my_own_path",

"scheme": "https",

"port": "", "host": "my_own_host.com",

"query": "my_technical_user=mtu007"

}

}



 

Signature Certification

An additional safe way consists in establishing a secure channel by a signature. You can check the authenticity of the sender of the message (here, Coface) and prevent any spoofing attacks (Verifying message signatures). 

FIELD	MEANING
SignatureVersion	Version of the CPNS signature used.
Signature	Base64-encoded "SHA256" * signature of the Message, MessageId, Type, Timestamp, and TopicArn values.
SigningCertURL	The URL to the certificate that was used to sign the message

 

A belt and braces approach would be applying on top of that a whitelisting policy, by allowing our sender root domain in an authorized list to get in touch with your endpoint : *.amazonaws.com

 

3. Confirm the subscription to the topic

 

Once the subscription done, Coface will automatically validate it, thus streamlining the subscription workflow and reducing manual intervention.

Please find on this link an example code for an Amazon SNS endpoint Java servlet

Note:  The client repeats step 2 and 3 if he wants to subscribe to multiple topics. a push notification flow starts right after his subscription to the appropriate topic is confirmed. A notification can be consumed once.

 

Reception of an email alert in case of emails notification failed out:

When subscribing to a topic, a confirmation email will be sent to the email address linked to the user of the API Portal (https://developers.coface.com/). Once you click on the confirmation hyperlink embedded in this email, you land to a page (https://aws.amazon.com/fr/ses/details/) indicating that his email address is now ready to receive potential alerting messages whether the endpoint is experiencing some issues.

It's highly recommended to confirm your email address to make sure Coface will monitor all messages that you may not be correctly received on the endpoint you set up. 

In that specific case, an alert is sent when the "retry process" has ended, i.e. when our client is not able to receive our emails anymore (see the “When is the replay API operable ?” section). Coface then starts to store notifications, waiting for our client's validation to restart the process, called 'API Replay'.

 

4. When is the replay API operable?

 

Right after the end of the two-steps failed message retry policy, our CofaServe user can trigger the replay process for a given message, either by calling dynamically or manually the API (basically, 5 hours after the initial notification generation and sending, those 5 hours represents the time needed for the whole automated retry process to reach its end).

For the same given message, the replay API will be able to trigger the regular push notification process until 5 days after the initial notification generation and sending.

Our CofaServe user is granted with 7 replay attempts maximum per message, otherwise, the message will be impossible to replay, never again. The user must therefore be sure that his endpoint is operational before calling the API.

The API PATCH /replay is available for CPNS users.

 

server : https://api.coface.com/tci  + rootContext : replay/v1  + endpoint : /replay

= complete URL : https://api.coface.com/tci/replay/v1/replay

 

Graphical timeline:

 

 

DETAILS OF DELIVERY

For any products ordered, if you need the full details of an answer to a request, you can consult the resource: 

GET ​/companies​/{easyNumber}​/products​/deliveries​/{deliveryIdOrExternalId}

 

 The List of possible delivery status

• CANCELLED : the product has been cancelled (always by Coface)
• DECIDED_FULL: the product has been granted
• DECIDED_PARTIAL: the product has been partially granted
• DECIDED_REFUSED: the product has been refused
• EXPIRED: the decision has expired
• REDUCED: the decision has been reduced
• WITHDRAWN: the product has been deleted by you or by Coface
• UNDER_WITHDRAWAL: you have set a date of expiry
• UNDER_CANCELLATION: Coface has set a date of expiry
• DELIVERED: the report has been delivered
• STATUS_FULLFILLED: only for extension of due date product (EDD)
• STATUS_REPLACED: only for extension of due date product (EDD)

 

Note You will get the last orderId and/or the last externalID in the catalog of products for a contract number and a EASYNumber ( GET ​/companies​/{easyNumber}​/catalog), as well as the portfolio follow-up service ( GET​ /companies​/products) The ExternalId is specific number delivered when you check your notification (GET /notifications)

 

Details of an order 

If you need to retrieve the details of an order, whatever the product, or the status of your order, you can check the service: GET​/companies​/{easyNumber}​/products​/orders​/{orderId}

The list of possible order status: 

• STATUS_CLOSED : the request has been closed
• STATUS_STARTED: the request has been produced
• STATUS_REJECTED: the request has been rejected (always by Coface)
• STATUS_ANNULED: the request has been annuled
• STATUS_PENDING_COMPLEMENTARY_INFORMATION: the request is pending, Coface needs complementary information to take a decision
• STATUS_PENDING_DEBTOR_VALIDATION: the request is pending, Coface is trying to identify your partner
• STATUS_PENDING_ON_HOLD: the request is pending
• STATUS_PENDING_UNDERWRITING: the request is pending, A risk underwriter is taken a decision

Frequently Asked Questions:   Can a subscriber subscribe to several topics?  Yes, a subscriber can subscribe to all available topics if needed. Only one subscription to a topic is sufficient to cover all his policies. Can a subscriber cancel a subscription?  Yes, a subscriber can cancel a subscription to a topic, by calling back the URL given in field UnsubscribeURL (available in each notification belonging to the topic). How can a subscriber validate his endpoint implementation?  As for Pull Notifications test process, Push notifications end-to-end process will be tested and validated using a TEST contract. Is a subscriber able to consume notifications related to events occurred before his subscription?  No, a push notification flow starts right after his subscription to the appropriate topic is confirmed. Is a subscriber able to consume again a notification he already consumed?  No, a push notification can only be consumed once. What kind of assistance / support is provided?  A technical implementation documentation is provided to sustain endpoint container set up, and regular assistance (on the flow support) provided as regard exploitation. What if a new subject is added to an existing topic?  If a user is already subscribed to the concerned topic, he will naturally receive new notifications related to this new subject. It could be related to a new or an already existing product. What if a new topic is released?  A complete release note will be sent to all users, explaining all assets related to this new topic. Each user intending to benefit from this new topic will have to subscribe to it. How many notifications can I receive at the same time?  The maximum amount of notifications per second and per subscription is 10. What if a subscriber fails to receive or integrate a notification?  A technical retry process is set up to ensure several data reception opportunities. What are the details of the technical retry process?  Immediately after a notification reception failure, retry process is triggered. The whole process will last at its maximum 3600 seconds and during this period there will be a maximum of 50 retries. Below the exact timeline and details to understand the settings of this retry process : - Immediately after the initial failure, the system will retry 5 times without any delay - If the failure persists, the system will retry 5 times, each time separated by 1 second - If the failure still persists, the system will retry 30 times. The delay between each retry will grow exponentially from 1 second to 240 seconds - And finally, if the failure remains, the system will retry 10 times, likewise the delay between each retry will grow exponentially from 1 second to 240 seconds What if this technical retry process is not sufficient enough? This process is implemented to cope first with transitory customer endpoints failures (1st step). For longer customer endpoints failures, as a 2nd step: - CPNS will trigger the same retry process once If the consumer’s endpoint is still failing, the same retry process will be triggered again - Loop until 4 retries maximum, for a maximum duration of 4 hours. So at the end, in the worst case scenario, if the client is still failing to receive a notification: - the message would have followed the retry policy described on 1st step 5 times - it would have taken 5 hours at maximum. What occurs to the notification if this whole retry process fails?  The API Replay is available to inform Coface the client endpoint is up and running well again, ready to consume all missed notifications until 5 days (limited to 7 attempts, after that, the notification is irretrievably lost.)

 

As of december 2022

When a debtor does not pay you its invoices, partially or totally, you have to send this information to Coface. The webservices allow to manage your overdues, on known debtor (company identified in your portfolio and on which a product is ordered) or on unknown debtor (unamed buyer in dicretionnary limit) or depending on your contractual terms, on uncovered debts.

To perform your tests, please make sure to use an EasyNumber of a dummy debtor. Contact your Coface contact to get more details.

 

Overdue account on cover debts You must notify your overdues before a time limit. The due date can’t be over the maximum credit period, except if an extension of due date (EDD) has been granted by the risk underwriter. Timit limit for notification of overdue account (NOA) = 30 days after the maximum credit period (as set in the special terms / calculated from the invoice date) Timit limit for NOA with an EDD = 30 days from the extended due date applies to the first unpaid extended due date, for the whole balance.   Overdue account on uncover debts With the option "debt collection" on your contract, you can submit to Coface your uncovered debts for debt collection. If the cover of your debt is rejected by our claim services (ie: the cover of all your invoices in the Debt Account tab will be rejected), you will be able to convert your NOA into a request of debt collection  PATCH​/companies​/{easyNumber}​/overdues​/{overdueId}   If you know from the beginning that your debt is not covered, you can specify the debttype = NGD (non Guarantee Debt) when declaring the overdue account POST​/companies​/{easyNumber}​/overdues

 

How does it work?

Step 1: identify in the catalog the actions and type of debt (credit insurance or non guarantee debt), depending on your contract terms, that can be performed on the company - relevant if you have the EasyNumber.

The overdue services manage cover debts and uncover debts when the option is available on your contract. A catalog has been created to help you manage the different possibilities available for a company based on your contract specifities.

 

If you do not have the easy number of the company, you can notify an overdue account for unknown debtor, or search in first step to identify the easy number of the debtor.

We recommend you this last solution, because if Coface can't identify based on company details provided, your request will be rejected. You take the risk to be out of time to declare your NOA.

GET​/companies​/{easyNumber}​/catalog-overdue

This service lists all the necessary features required when you need to notify an overdue, like the type of possible products you can request, some options details you would have the capability to active with your overdue, and the overdueId of your case...

• debtType:
  • - CI = Notification of overdue account - on cover debt 
  • - NGD = Request the intervention of Coface for debt collection on uncovered debt 

• - actionCodes:
  • CREA = Create a case
  • UPDT = Update your case
  • MOVE = Convert your NOA into a request of debt collection

Services to consult depending on DebtType and Action to perform :

	CREA	UPDT	MOVE
CI	POST​/companies​/{easyNumber}​/overdues	PUT​/companies​/{easyNumber}​/overdues​/{overdueId}	-
NGD	POST​/companies​/{easyNumber}​/overdues	PATCH​/companies​/{easyNumber}​/overdues​/{overdueId}	PATCH​/companies​/{easyNumber}​/overdues​/{overdueId}

 

Step 2 : Declare your overdue account

You want to declare an overdue on a buyer for which you have the EasyNumber, please use the service: 

POST /companies​/{easyNumber}​/overdues

You want to declare an overdue on a buyer for which you do not have the EasyNumber, please use this service:

POST /companies​/unknown​/overdues

Note:  A search will be done in our companies database as a mandatory step to identify the EasyNumber of the buyer. To avoid wasting time and being out of delay, we encourage you to identify on your side the EasyNumber when possible. If no easyNumber can be identified by our service, the request will be rejected.  GET ​/companies​/identifier (if you have legal identifier of the company) or GET /companies​/name (only if you have geographical details on the company)

 

The creation of a NOA case leads automatically to the creation of a case, with an overdueId.

The main steps are:

• Identification of the contact person in your company (invoices issuer)
• Identification of the debtor and of its contact person (company invoiced)
• Specification of the non-payment reason
• Set of the invoices (you can input an "invoice reference" only once)
• Set of the payments, settlement and credit note already received
• Specify the debt type of your request, CI for a NOA on covered debts, or NGD for debt collection on uncovered debts. This last option depends on your contract term
• Choice if with or without intervention request
• If applicable, possible reduction of the waiting period
• Call of the creation web service for validating the NOA

Once submitted, an OverdueId is initiated in Coface system (in SOAP / XML version, this indicator was named “claimID”, as the NOA identifier). It could take few hours.

This OverdueId is your main reference to update or follow-up your case in the next steps you may do on your case (add documents, consult a case...)

 

Step 3: Transmit to Coface all documents in link with your overdue (copy of shipping documents, invoices, orders...)

Transfer of any documents related to the claim (sales contract, invoices, statement of account…). The list of documents required depends on the country of the debtor. For a given overdueID, by using this service, you can add a document whenever you want.

The whitelist of permitted media types, selected based on the types of files we support, includes:

• application/msword (.doc)
• application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx)
• image/gif (.gif)
• image/jpeg (.jpeg, .jpg)
• application/pdf (.pdf)
• image/png (.png)
• application/vnd.ms-excel (.xls)
• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (.xlsx)

The Content-Type entity of the request body parameter document must be correctly defined according to the type and extension of the current document to avoid rejection.

It is possible to add several files but only one file can be added at a time.

It is not possible to attach more than 500 files to a claim case.

The size limit per document is of 10 MB.

You can't submit two documents with the same name and the same extension on a same OverdueId. The filename should not exceed 255 caracters.

POST​/companies​/{easyNumber}​/overdues​/{overdueId}​/documents

To get the details of all documents provided to Coface for an OverdueId, you can use the webservice

Remark: Only the name of the file is delivered, not its content.

GET /companies​/{easyNumber}​/overdues​/{overdueId}​/documents)

 

Step 4: Update your overdue case

After the Notification of Overdue Account, If your overdue has a status "Pending" or "Pending_debtor_validation", you shall inform Coface of any recoveries you received, new invoices and/or the request for intervention.

Remark: It is not possible to update an overdue case based on an unknown debtor (i.e. until the unknown debtor has been identified and attached to an EASY number, and therefore has become a known debtor).

PUT /companies​/{easyNumber}​/overdues​/{overdueId}

 

Step 5: Request the debt collection service when your overdue account is not covered (subject to contract term - option)

Subject to your contract term, if the analysis of your overdue has been rejected and if your contract is subject to the option, you can PATCH your overdue case to ask our service entities to take in charge the debt collection of the debt.

PATCH​/companies​/{easyNumber}​/overdues​/{overdueId}

Our webservice allows you only to notify the request of our action, not to follow up in details your case.

You also use the service PATCH to update your case if any with new invoices or payments.

Overdue Follow-up

 

To follow-up your overdues portfolio, you can :

• consult the totally of your overdues submitted to Coface. The status of the overdue must be specified, and you can also filter the lists of overdues based on your overdue "customer reference" or an easy number.

GET​/companies​/overdues

• You list your overdues with the main variables:
• - Intervention of Coface Requested ?
• - overdue Customer Reference
• - last Update Date
• - overdueId
• - creationDate
• - status of the overdue
• - easyNumber

 

• consult the details on a case based on the combinaison of easynumber and overdueId. you will get the full details of features communicated to our services and the details on the indemnification.

GET​/companies​/{easyNumber}​/overdues​/{overdueId}