{"openapi":"3.0.0","info":{"title":"NL Official Documents API","description":"NL Official Documents API project represents the functionality to order documents from the KVK website.\n","version":"v0.1.0"},"servers":[{"url":"https://api.company.info/nl/organizations/official-documents","description":"Production Server"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"NL Official Documents API","description":"Calls related to the Official Documents API"}],"paths":{"/v1/orders":{"get":{"operationId":"getOrdersList","summary":"List previously placed orders","tags":["Order"],"description":"List previously placed orders","parameters":[{"name":"filter","in":"query","style":"deepObject","description":"Filter is used for filtering the orders based on `documentType`, `organizationID`, and `branchID`.","schema":{"type":"object","description":"Filter is used for filtering the orders based on `documentType`, `organizationID`, `branchID`, `status`, and `date`.","properties":{"organizationID":{"type":"string","example":"11111111"},"branchID":{"type":"string","example":"111111110011"},"status":{"type":"string","example":"done"},"documentType":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"date":{"type":"object","properties":{"from":{"type":"string","example":"2024-08-06"},"to":{"type":"string","example":"2024-08-07"}}}}}},{"name":"page","in":"query","style":"deepObject","description":"`size` defines the number of records to return in each page.\ndefault value: 10, maximum value: 20.\n<br>`number` specifies the page number.\"\n","schema":{"$ref":"#/components/schemas/Page"}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderResultData"}},"links":{"type":"object","properties":{"first":{"$ref":"#/components/schemas/JSONAPILink"},"last":{"$ref":"#/components/schemas/JSONAPILink"},"next":{"$ref":"#/components/schemas/JSONAPILink"},"prev":{"$ref":"#/components/schemas/JSONAPILink"},"self":{"$ref":"#/components/schemas/JSONAPILink"}}},"meta":{"type":"object","properties":{"totalPages":{"type":"integer","example":15},"totalResults":{"type":"integer","example":150}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"createOrder","summary":"Place a new document order","tags":["Order"],"description":"Place a new document order","requestBody":{"description":"The request body","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"orders"},"attributes":{"allOf":[{"type":"object","required":["documentType","organizationID"],"properties":{"documentType":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"organizationID":{"type":"string","example":"33302047"}}}],"oneOf":[{"$ref":"#/components/schemas/ExtractDocumentAttributes"}]}}}}}}}},"responses":{"201":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderResultData"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/orders/{order_id}":{"get":{"operationId":"getOrder","summary":"Get a specific order","tags":["Order"],"description":"Get a specific order","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderResultData"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"runAnActivity","summary":"Retry a failed order activity","tags":["Order"],"description":"Retry a failed order activity","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The request body","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"orders"},"attributes":{"allOf":[{"type":"object","properties":{"activity":{"type":"string","enum":["order","convert"],"example":"order"}}}]}}}},"example":{"data":{"type":"orders","attributes":{"activity":"convert"}}}}}}},"responses":{"204":{"description":"No Content"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"423":{"description":"Not Ready","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":423},"code":{"type":"string","example":423},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested document is not ready yet"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/orders/{order_id}/document":{"get":{"operationId":"downloadDocument","summary":"Download a document from an order","tags":["Order"],"description":"Download a document from an order","parameters":[{"name":"Accept","required":true,"in":"header","schema":{"type":"string","example":"application/json"}},{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns PDF/HTML/JSON","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"description":"Not Acceptable","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":406},"code":{"type":"string","example":406},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested content-type is not supported"}}}}}}}}},"423":{"description":"Not Ready","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":423},"code":{"type":"string","example":423},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested document is not ready yet"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/":{"get":{"operationId":"getSupportedDocuments","summary":"Discover supported documents for an organization","tags":["Document"],"description":"Discover supported documents for an organization","parameters":[{"name":"filter","in":"query","style":"deepObject","description":"Filter is used for filtering the orders based on `type`, `organizationID`, and `branchID`.","schema":{"type":"object","description":"Filter is used to get the supported documents for the requested organization.","required":["organizationID"],"properties":{"organizationID":{"type":"string","example":"87654321"},"branchID":{"type":"string","example":"876543210001"}}}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"documents"},"attributes":{"type":"object","properties":{"organizationID":{"type":"string","example":"33302047"},"branchID":{"type":"string","example":"000016450760"},"date":{"type":"string","example":"2024-03-15T11:19:39+01:00"},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"standardExtract"},"mimeType":{"type":"string","example":"text/html"},"price":{"type":"number","example":2.95},"available":{"type":"boolean","example":true},"expectedTime":{"type":"integer","example":60},"description":{"type":"string","example":"Business Register Extract"},"productName":{"type":"string"},"productDate":{"type":"string"},"maskedGDPR":{"type":"boolean","example":false}}}}}}}},"links":{"type":"object","properties":{"first":{"$ref":"#/components/schemas/JSONAPILink"},"last":{"$ref":"#/components/schemas/JSONAPILink"},"next":{"$ref":"#/components/schemas/JSONAPILink"},"prev":{"$ref":"#/components/schemas/JSONAPILink"},"self":{"$ref":"#/components/schemas/JSONAPILink"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/documents":{"get":{"operationId":"getListOfDocuments","summary":"List available cached documents","tags":["Document"],"description":"List available cached documents","parameters":[{"name":"filter","in":"query","style":"deepObject","description":"Filter is used for filtering the documents based on `type`, `organizationID`, and `branchID`.","schema":{"type":"object","description":"Filter is used for filtering the orders based on `type`, `organizationID`, `branchID` and `date`.","required":["organizationID"],"properties":{"organizationID":{"type":"string","example":"11111111"},"branchID":{"type":"string","example":"111111110011"},"type":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"date":{"type":"object","properties":{"from":{"type":"string","example":"2024-08-06"},"to":{"type":"string","example":"2024-08-07"}}}}}},{"name":"page","in":"query","style":"deepObject","description":"`size` defines the number of records to return in each page.\ndefault value: 10, maximum value: 20.\n<br>`number` specifies the page number.\"\n","schema":{"$ref":"#/components/schemas/Page"}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentResultData"}},"links":{"type":"object","properties":{"first":{"$ref":"#/components/schemas/JSONAPILink"},"last":{"$ref":"#/components/schemas/JSONAPILink"},"next":{"$ref":"#/components/schemas/JSONAPILink"},"prev":{"$ref":"#/components/schemas/JSONAPILink"},"self":{"$ref":"#/components/schemas/JSONAPILink"}}},"meta":{"type":"object","properties":{"totalPages":{"type":"integer","example":15},"totalResults":{"type":"integer","example":150}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/documents/{document_id}":{"get":{"operationId":"downloadDocumentByDocumentId","summary":"Download a cached document","tags":["Document"],"description":"Download a cached document","parameters":[{"name":"Accept","required":true,"in":"header","schema":{"type":"string","example":"application/json"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns PDF/HTML/JSON","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"description":"Not Acceptable","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":406},"code":{"type":"string","example":406},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested content-type is not supported"}}}}}}}}},"423":{"description":"Not Ready","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":423},"code":{"type":"string","example":423},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested document is not ready yet"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"OrderResultData":{"title":"Order","type":"object","properties":{"id":{"type":"string","example":"01HS0SZQECSKQ8NV20391MZ0R1"},"type":{"type":"string","example":"orders"},"attributes":{"allOf":[{"type":"object","properties":{"documentType":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"status":{"type":"string","enum":["pending","done","failed","cancelled"],"example":"pending"},"organizationID":{"type":"string","example":"33302047"},"mimeTypes":{"type":"array","items":{"type":"string","enum":["application/pdf","application/json","text/html"]},"example":["text/html","application/pdf","application/json"]},"createdAt":{"type":"string","example":"2024-03-15T11:19:39+01:00"}}}],"oneOf":[{"$ref":"#/components/schemas/ExtractDocumentAttributes"}]},"links":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/JSONAPILink"}}}}},"DocumentResultData":{"title":"Document","type":"object","properties":{"id":{"type":"string","example":"MDFLRVI5TldFMkdHN0I1Nkc1MENSQ1hRV0sIKeVgHoPvCxQswzN0i6m4VvYCkCC2fSf0XW3_51YXrA"},"type":{"type":"string","example":"documents"},"attributes":{"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"organizationID":{"type":"string","example":"33302047"},"mimeTypes":{"type":"array","items":{"type":"string","enum":["application/pdf","application/json","text/html"]},"example":["text/html","application/pdf","application/json"]},"createdAt":{"type":"string","example":"2024-03-15T11:19:39+01:00"},"upToDate":{"type":"boolean","example":true}}}],"oneOf":[{"$ref":"#/components/schemas/ExtractDocumentAttributes"}]},"links":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/JSONAPILink"}}}}},"ExtractDocumentAttributes":{"type":"object","properties":{"branchID":{"type":"string","example":"000016450760"}}},"Page":{"type":"object","properties":{"size":{"type":"integer","default":10,"description":"The number of records to return in each page."},"number":{"type":"integer","default":1,"description":"This parameter specifies the page number."}}},"JSONAPILinkObject":{"title":"JSON:API Link Object","description":"a structured representation of a URL","type":"object","required":["href"],"properties":{"href":{"type":"string","example":"/organizations/<cin>"},"meta":{"type":"object","example":{"count":"10"}}}},"JSONAPILink":{"title":"JSON:API Link","description":"A JSON:API link can be either a URL string or a structured link object.","oneOf":[{"type":"string","format":"url","example":"https://example.com/"},{"$ref":"#/components/schemas/JSONAPILinkObject"}]},"JSONAPIErrorResponse":{"title":"JSON:API Error Response","type":"object","required":["errors"],"properties":{"errors":{"title":"An array of Error objects","type":"array","minItems":1,"items":{"type":"object","required":["status","code","title","detail"],"properties":{"status":{"description":"the HTTP status code applicable to this problem","type":"string","minLength":3,"maxLength":3},"code":{"description":"an application-specific error code. It can be the same as 'status'","type":"string"},"title":{"description":"a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization","type":"string"},"detail":{"description":"a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized","type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/JSONAPIErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/JSONAPIErrorResponse"}}}},"NotFound":{"description":"Not Found","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/JSONAPIErrorResponse"}}}}}}}