Welcome to openprocurement.integrations.edr’s documentation!

Please report any problems or suggestions for improvement either via the mailing list or the issue tracker.

Contents:

Overview

The Integrations EDR procedure is plugin to Open Procurement API software.

REST-ful interface to plugin is in line with core software design principles.

Conventions

This plugin conventions follow the Open Procurement API conventions.

Main responsibilities

Integrations EDR procedure for obtaining information from the Unified State Register of legal entities and individual entrepreneurs (hereinafter - EDR) by Unified State Register of Enterprises and Organizations of Ukraine (hereinafter - EDRPOU) and Individual tax number (hereinafter - IPN). If you need to find an individual entrepreneur who has no IPN - search performed on the series and passport number.

Project status

The project is in active development and has pilot installations.

The source repository for this project is on GitHub: https://github.com/openprocurement/openprocurement.integrations.edr

You can leave feedback by raising a new issue on the issue tracker (GitHub registration necessary). For general discussion use Open Procurement General maillist.

API stability

API is highly unstable, and while API endpoints are expected to remain relatively stable the data exchange formats are expected to be changed a lot. The changes in the API are communicated via Open Procurement API maillist.

Next steps

You might find it helpful to look at the Tutorial.

Tutorial

Basic request

In order to get information from EDR by code EDRPOU you need to make a request to api/1.0/verify endpoint, passing code as GET parameter:

GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "meta": {
    "sourceDate": "2017-04-25T11:56:36+00:00"
  },
  "data": [
    {
      "registrationStatusDetails": "зареєстровано",
      "x_edrInternalId": 2842335,
      "registrationStatus": "registered",
      "identification": {
        "url": "https://zqedr-api.nais.gov.ua/1.0/subjects/2842335",
        "schema": "UA-EDR",
        "id": "14360570",
        "legalName": "АКЦІОНЕРНЕ ТОВАРИСТВО КОМЕРЦІЙНИЙ БАНК \"ПРИВАТБАНК\""
      }
    }
  ]
}

Response consists of the following fields: x_edrInternalId, registrationStatusDetails, registrationStatus, identification.schema, identification.id, identification.legalName, identification.url.

  • x_edrInternalId - unique identification of the subject,
  • registrationStatusDetails - text state of the entity (uk),
  • registrationStatus - text state of the entity,
  • identification.schema - “UA-EDR”
  • identification.id - EDRPOU; if the subject - an individual entrepreneur - instead of IPN system returns ten zeros, because the data is confidential,
  • identification.legalName - name of the entity,
  • identification.url - link to the entity with detailed information.

Also response contains meta.sourceDate field - date when information from EDR API was received.

Request with Individual Tax Number

If you need to obtain information about individual entrepreneurs then send a request with code IPN:

GET /api/1.0/verify?id=1234567891 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "meta": {
    "sourceDate": "2017-04-25T11:56:36+00:00"
  },
  "data": [
    {
      "registrationStatusDetails": "зареєстровано",
      "x_edrInternalId": 2842335,
      "registrationStatus": "registered",
      "identification": {
        "url": "https://zqedr-api.nais.gov.ua/1.0/subjects/2842335",
        "schema": "UA-EDR",
        "id": "1234567891",
        "legalName": "АКЦІОНЕРНЕ ТОВАРИСТВО КОМЕРЦІЙНИЙ БАНК \"ПРИВАТБАНК\""
      }
    }
  ]
}

Errors

Response to the unsuccessful request contains list of errors with description, code in response body and status.

API returns the following response when limit of requests to the resource is reached:

GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org

Response: 429 Too Many Requests
Content-Type: application/json; charset=UTF-8
Retry-After: 26
{
  "status": "error",
  "errors": [
    {
      "description": [
        {
          "message": "Retry request after 26 seconds."
        }
      ],
      "name": "data",
      "location": "body"
    }
  ]
}

Response contains message with time when current limitation will expire.

When given EDRPOU (IPN) were not found in EDR response will contains message EDRPOU not found:

GET /api/1.0/verify?id=123 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org

Response: 404 Not Found
Content-Type: application/json; charset=UTF-8
{
  "status": "error",
  "errors": [
    {
      "description": [
        {
          "meta": {
            "sourceDate": "2017-04-25T11:56:36+00:00"
          },
          "error": {
            "errorDetails": "Couldn't find this code in EDR.",
            "code": "notFound"
          }
        }
      ],
      "name": "data",
      "location": "body"
    }
  ]
}

When GET parameter code or passport is not passed proxy-server will return response with error:

GET /api/1.0/verify HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org

Response: 403 Forbidden
Content-Type: application/json; charset=UTF-8
{
  "status": "error",
  "errors": [
    {
      "description": [
        {
          "message": "Wrong name of the GET parameter"
        }
      ],
      "name": "data",
      "location": "body"
    }
  ]
}

Rest of errors appears on the proxy-server side and can contain one of next messages:

GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org

Response: 403 Forbidden
Content-Type: application/json; charset=UTF-8
{
  "status": "error",
  "errors": [
    {
      "description": [
        {
          "message": "Invalid or expired token.",
          "code": 2
        }
      ],
      "name": "data",
      "location": "body"
    }
  ]
}

or

GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org

Response: 403 Forbidden
Content-Type: application/json; charset=UTF-8
{
  "status": "error",
  "errors": [
    {
      "description": [
        {
          "message": "Payment required.",
          "code": 5
        }
      ],
      "name": "data",
      "location": "body"
    }
  ]
}

These errors are not related to the created request.

Identification Bot

File-reference

For users from group robot endpoint api/1.0/verify will return details information. Request looks like:

GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cm9ib3Q6cm9ib3Q=
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "meta": {
    "sourceDate": "2017-04-25T11:56:36+00:00",
    "detailsSourceDate": ["2017-04-25T11:56:36+00:00"]
  },
  "data": [{
    "additionalActivityKinds": [
      {
        "scheme": "КВЕД",
        "id": "64.92",
        "description": "Інші види кредитування"
      },
      {
        "scheme": "КВЕД",
        "id": "64.99",
        "description": "Надання інших фінансових послуг (крім страхування та пенсійного забезпечення), н. в. і. у."
      },
      {
        "scheme": "КВЕД",
        "id": "66.11",
        "description": "Управління фінансовими ринками"
      },
      {
        "scheme": "КВЕД",
        "id": "66.12",
        "description": "Посередництво за договорами по цінних паперах або товарах"
      },
      {
        "scheme": "КВЕД",
        "id": "66.19",
        "description": "Інша допоміжна діяльність у сфері фінансових послуг, крім страхування та пенсійного забезпечення"
      }
    ],
    "management": "ЗАГАЛЬНІ ЗБОРИ",
    "name": "ПАТ КБ \"ПРИВАТБАНК\"",
    "registrationStatusDetails": "зареєстровано",
    "registrationStatus": "registered",
    "identification": {
      "scheme": "UA-EDR",
      "id": "14360570",
      "legalName": "АКЦІОНЕРНЕ ТОВАРИСТВО КОМЕРЦІЙНИЙ БАНК \"ПРИВАТБАНК\""
    },
    "address": {
      "postalCode": "49094",
      "countryName": "УКРАЇНА",
      "streetAddress": "Дніпропетровська обл., місто Дніпропетровськ, Жовтневий район"
    },
    "founders": [
      {
        "role_text": "засновник",
        "role": 4,
        "name": "АКЦІОНЕРИ - ЮРИДИЧНІ ТА ФІЗИЧНІ ОСОБИ"
      }
    ],
    "activityKind": {
      "scheme": "КВЕД",
      "id": "64.19",
      "description": "Інші види грошового посередництва"
    }
  }]
}

File-reference name is edr_identification.yaml and is uploaded to tenders with status ` active.pre-qualification` and procurementMethodType: aboveThresholdEU, competitiveDialogueUA, competitiveDialogueEU and tender with status active.qualification with procurementMethodType: aboveThresholdUA, aboveThresholdUA.defense, aboveThresholdEU, competitiveDialogueUA.stage2, competitiveDialogueEU.stage2. Field identifier.scheme should have value UA-EDR. File-reference is uploaded to award/qualification with pending status and contains field documentType: registerExtract. If identifier:id is not found in EDR, then file will include next error {error: {code: notFound, errorDetails: Couldn’t find this code in EDR.}}.

File-reference also includes service information in meta.

  • author - author of file-reference, have value IdentificationBot,
  • id - unique identifier of file-reference,
  • sourceDate - creation date,
  • sourceRequests - list of request numbers to API, EDR-proxy,
  • version - file-reference format version.

Value meta.version now have value 1.1.1. First number - major version (delete field, rename, remove), second number - minor version (add field), third number - bugfix version (changes that do not change fields, but fix bugs). For example, changing of file-reference name from edr_request.yaml to edr_identification.yaml increased first number(major version), adding meta.author field increased second number (minor version).

Change value of meta.version filed to 1.2.1 after adding fields to file-reference:

  • registrationStatusDetails - text state of the entity (uk),
  • registrationStatus - text state of the entity.

Authentication

For EDR Proxy authentication Basic Authenication scheme (see RFC 2617#section-2) is used.

In this scheme:

  • Username is broker’s id
  • Password is API key for EDR Proxy

Indices and tables