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.