Integration readiness teardown

fulfilment-api.json

Sealed report: 22aca6e881d8
Profile: default v1
Engine: 0.1.0
Coverage: complete
Read: 968 fragments

At a glance

127

findings

causes (one piece of work each)

points taken off

critical or high findings

Critical	High	Medium	Low
0	2	102	23

Rules: 13 found a gap, 8 found none, 14 not applicable, 4 could not be assessed, 2 switched off, 0 failed. The weakest family is contract. 364 points were not taken because a rule reached its cap.

Fix first

Clearing these 5 causes takes back 69 points of 87 points (79.3%).

#	Severity	Rule	Cause	Places	Points	Running total
1	medium	`CC-ERR-01`	no error response documented	53	15	15
2	medium	`CC-PARAM-01`	required parameter without description	42	15	30
3	medium	`PAG-01`	no pagination	5	15	45
4	high	`CC-SCHEMA-01`	no schema for application/json	2	15	60
5	low	`CC-DESC-02`	weak description: restates its name	9	9	69

Families

Family	Sub-score	Findings	Causes	Points	Share	Rules: applied · clean · not assessed	Worst rules (findings)
contract	34	116	10	66	75.9%	13 · 6 · 1	`CC-ERR-01 (53), CC-PARAM-01 (43), CC-SCHEMA-01 (2), CC-DESC-02 (11), CC-RESP-01 (4)`
pagination	85	5	1	15	17.2%	1 · 0 · 0	`PAG-01 (5)`
onboarding	98	2	1	2	2.3%	2 · 1 · 1	`AUTH-02 (2)`
data	99	1	1	1	1.1%	1 · 0 · 0	`DATA-02 (1)`
examples	99	1	1	1	1.1%	2 · 1 · 0	`CC-EX-01 (1)`
limits	99	1	1	1	1.1%	1 · 0 · 0	`RATE-01 (1)`
reliability	99	1	1	1	1.1%	1 · 0 · 0	`IDEM-01 (1)`

No rule applied, so nothing was assessed for: documentation, errors, lifecycle, links, webhooks, workflow. That is not a clean result.

Hotspots

53 operations with findings. 8 findings are about the document as a whole (11 points).

Operations

Operation	Points	Findings	High	Med.	Low	Families	Rules
`GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}`	10	2	1	1	0	contract	`CC-ERR-01, CC-SCHEMA-01`
`GET /api/fulfilment/v1/configuration/warehouses`	8	2	0	2	0	contract, pagination	`CC-ERR-01, PAG-01`
`GET /api/fulfilment/v1/configuration/warehouses/{warehouseId}`	8	2	0	2	0	contract	`CC-ERR-01, CC-PARAM-01`
`GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values`	6	4	0	2	2	contract, pagination	`CC-DESC-02, CC-ERR-01, PAG-01`
`GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames`	5	2	1	1	0	contract	`CC-ERR-01, CC-SCHEMA-01`
`GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}`	4	3	0	2	1	contract	`CC-ERR-01, CC-PARAM-01, CC-RESP-01`
`POST /api/fulfilment/v1/configuration/docks/{dockId}/activation`	4	3	0	2	1	contract	`CC-DESC-02, CC-ERR-01, CC-PARAM-01`
`DELETE /api/fulfilment/v1/configuration/holidays/{holidayId}`	4	2	0	2	0	contract	`CC-ERR-01, CC-PARAM-01`
`DELETE /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}`	4	2	0	2	0	contract	`CC-ERR-01, CC-PARAM-01`
`GET /api/fulfilment/v1/configuration/docks`	4	2	0	2	0	contract, pagination	`CC-ERR-01, PAG-01`
`POST /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots/{supplyLotId}/transfer`	4	1	0	1	0	contract	`CC-ERR-01`
`GET /api/fulfilment/v1/inventory/items/{itemId}/warehouses/{warehouseId}/dispatched`	3	4	0	4	0	contract, pagination	`CC-ERR-01, CC-PARAM-01, PAG-01`
`PUT /api/fulfilment/v1/inventory/skus/{skuId}/warehouses/{warehouseId}`	1	4	0	3	1	contract	`CC-DESC-02, CC-ERR-01, CC-PARAM-01`
`GET /api/fulfilment/v1/inventory/skus/{skuId}`	1	3	0	2	1	contract	`CC-ERR-01, CC-PARAM-01, CC-RESP-01`
`POST /api/fulfilment/v1/configuration/docks/{dockId}/deactivation`	1	3	0	2	1	contract	`CC-DESC-02, CC-ERR-01, CC-PARAM-01`

Resources

Resource	Points	Findings	Crit.	High	Med.	Low	Families	Rules
`/api` (53 operations)	76	119	0	2	101	16	contract, examples, pagination	`CC-DESC-02, CC-ERR-01, CC-EX-01, CC-PARAM-01, CC-RESP-01, CC-SCHEMA-01, PAG-01`

What this report cannot say

Source	Provides	Coverage	Read	Not read	Failed
`fulfilment-api.json`	an API description	complete	1	0	0

4 checks could not be made: needs guide pages; none was supplied. Not a pass, and no points were taken off. CC-CONFLICT-01, LINK-01, ON-ENV-01, DOC-CODE-01
1 rule found nothing, but 1 example was not checked against its schema: the example is too long to keep. That is not a clean result. CC-EX-02
2 rules are switched off by the profile. PAG-02, CC-DESC-03

Causes in detail

medium `CC-ERR-01` no error response documented

contract · 53 places · 15 points taken, 197 points withheld by the rule's cap

Impact. Developers cannot tell which failures to expect or how to handle them, so error paths are discovered in production.

Recommendation. Document the error responses (4xx and 5xx or a default) with their bodies and when each occurs.

Where. GET /api/fulfilment/v1/configuration/warehouses/{warehouseId}, GET /api/fulfilment/v1/configuration/warehouses, POST /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots/{supplyLotId}/transfer, POST /api/fulfilment/v1/configuration/docks/{dockId}/activation, DELETE /api/fulfilment/v1/configuration/warehouses/{warehouseId}, GET /api/fulfilment/v1/inventory/skus/{skuId}, GET /api/fulfilment/v1/configuration/geoshape, POST /api/fulfilment/v1/inventory/reservations/{reservationId}/confirm and 45 more

Evidence, first place. not found: an error response (4xx, 5xx or default); inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses~1{warehouseId}/get, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses~1{warehouseId}/get/responses/200

medium `CC-PARAM-01` required parameter without description

contract · 42 places · 15 points taken, 153 points withheld by the rule's cap

Impact. Developers must guess the meaning, format and valid values of a parameter they are required to send.

Recommendation. Describe what the parameter means, its format and valid values.

Where. GET /api/fulfilment/v1/configuration/warehouses/{warehouseId}, DELETE /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}, DELETE /api/fulfilment/v1/configuration/holidays/{holidayId}, GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}, GET /api/fulfilment/v1/configuration/pickuppoints/_search, GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}/warehouses/{warehouseId}, GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}, GET /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId} and 24 more

Evidence, first place. not found: description; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses~1{warehouseId}/get/parameters/2

medium `PAG-01` no pagination

pagination · 5 places · 15 points taken, 5 points withheld by the rule's cap

Impact. Clients cannot retrieve more than the first batch reliably, or must guess how paging works.

Recommendation. Document a pagination mechanism (cursor or page parameters and the field or header carrying the next position).

Where. GET /api/fulfilment/v1/configuration/warehouses, GET /api/fulfilment/v1/configuration/docks, GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values, GET /api/fulfilment/v1/inventory/items/{itemId}/warehouses/{warehouseId}/dispatched, GET /api/fulfilment/v1/configuration/pickuppoints

Evidence, first place. not found: pagination parameters, next-page field or Link header; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses/get, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses/get/responses/200

high `CC-SCHEMA-01` no schema for application/json

contract · 2 places · 15 points taken, 5 points withheld by the rule's cap

Impact. Developers cannot know the fields, types or required properties, and generated clients fall back to untyped data.

Recommendation. Add a schema to each structured media type, or remove the media type if no body is exchanged.

Where. GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}, GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames

Evidence, first place. not found: a schema for application/json; inspected fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames~1{windowDay}F{windowStartTime}T{windowEndTime}/get/responses/200

low `CC-DESC-02` weak description: restates its name

contract · 9 places · 9 points taken

Impact. A description that says nothing beyond the name gives a developer no more than the name already did.

Recommendation. Say what it does, what it returns or accepts, and anything the name does not show.

Where. POST /api/fulfilment/v1/inventory/reservations/{reservationId}/confirm, POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/activation, PUT /api/fulfilment/v1/configuration/holidays/{holidayId}, POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/deactivation, POST /api/fulfilment/v1/inventory/reservations/{reservationId}/acknowledge, POST /api/fulfilment/v1/inventory/reservations/{reservationId}/cancel, POST /api/fulfilment/v1/configuration/docks/{dockId}/deactivation, PUT /api/fulfilment/v1/inventory/skus/{skuId}/warehouses/{warehouseId} and 1 more

Evidence, first place. "Confirms reservation by reservation ID." at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1reservations~1{reservationId}~1confirm/post

low `CC-RESP-01` response without description

contract · 4 places · 4 points taken

Impact. Developers do not learn what the response means or when it occurs.

Recommendation. Describe when this response is returned and what it contains.

Where. PUT /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}, GET /api/fulfilment/v1/inventory/skus/{skuId}, GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}, POST /api/fulfilment/v1/shipping/calculate

Evidence, first place. not found: description; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1pickuppoints~1{pickupPointId}/put/responses/200

medium `CC-CONSIST-01` conflicting types for freight-values.absolutemoneycost

contract · 1 place · 4 points taken

Impact. A client that models the property once breaks on the other schema, and readers cannot tell which type is meant.

Recommendation. Use one type for a property name across schemas, or rename one of them to say it is a different thing.

Where. Property `absoluteMoneyCost` has different types across variants of `freight-values`: number in `ListFreightValues`, string in `CreateUpdateFreightValuesRequest`

Evidence. "absoluteMoneyCost" at fulfilment-api.json#/components/schemas/ListFreightValues/properties

Evidence. "absoluteMoneyCost" at fulfilment-api.json#/components/schemas/CreateUpdateFreightValuesRequest/properties

low `AUTH-02` security scheme without description

onboarding · 2 places · 2 points taken

Impact. Developers are not told how to obtain or send credentials for this scheme.

Recommendation. Describe how to obtain credentials and how to send them.

Where. Security scheme `appToken` has no description, Security scheme `appKey` has no description

Evidence, first place. not found: description; inspected fulfilment-api.json#/components/securitySchemes/appToken

low `CC-DESC-02` weak description: too short

contract · 2 places · 2 points taken

Impact. A description that says nothing beyond the name gives a developer no more than the name already did.

Recommendation. Say what it does, what it returns or accepts, and anything the name does not show.

Where. GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values

Evidence, first place. "Postal code." at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1freights~1{carrierId}~1{postalCode}~1values/get/parameters/3

low `CC-EX-01` no request or response example

examples · 1 place · 1 point taken

Impact. Developers have to infer payload shape from the schema alone, which slows a first successful call.

Recommendation. Add a realistic example for the request body and the success response.

Where. PUT /api/fulfilment/v1/configuration/geoshape

Evidence. not found: an example request or response body; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1geoshape/put, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1geoshape/put/responses/200

low `DATA-02` unformatted date/time properties

data · 1 place · 1 point taken

Impact. Clients cannot tell whether values are ISO 8601, epoch text or local time, so parsing and timezone handling are guesses.

Recommendation. Set `format: date-time` or `date`, or describe the format and timezone (for example ISO 8601 in UTC).

Where. 25 date/time-named string properties declare no format or timezone

Evidence. "closingTime" at fulfilment-api.json#/components/schemas/BusinessHour/properties

Evidence. "openingTime" at fulfilment-api.json#/components/schemas/BusinessHour/properties

Evidence. "startDate" at fulfilment-api.json#/components/schemas/CreateUpdateHolidayRequest/properties

Evidence. "dockTime" at fulfilment-api.json#/components/schemas/DeliveryItemOption/properties

Evidence. "timeToDockPlusDockTime" at fulfilment-api.json#/components/schemas/DeliveryItemOption/properties

Evidence. "totalTime" at fulfilment-api.json#/components/schemas/DeliveryItemOption/properties

Evidence. "transitTime" at fulfilment-api.json#/components/schemas/DeliveryItemOption/properties

Evidence. "endTime" at fulfilment-api.json#/components/schemas/DeliveryRange/properties

Evidence. "startTime" at fulfilment-api.json#/components/schemas/DeliveryRange/properties

Evidence. "endTime" at fulfilment-api.json#/components/schemas/DeliveryRange1/properties

low `IDEM-01` no idempotency

reliability · 1 place · 1 point taken

Impact. A retry after a timeout can create the resource twice, so clients cannot retry safely.

Recommendation. Accept an Idempotency-Key header on creating operations and document how long keys are remembered.

Where. None of the 4 resource-creating POST operations documents an idempotency key

Evidence. not found: an Idempotency-Key header parameter; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1docks/post, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses/post, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1reservations/post and 1 more

low `NAME-01` verbs in some paths

contract · 1 place · 1 point taken

Impact. Action verbs in some resource paths duplicate what the HTTP method already says and break the pattern of the other paths.

Recommendation. Name paths after resources and express the action with the HTTP method.

Where. 1 of 40 paths put an action verb in the path while the rest do not

Evidence. "/api/fulfilment/v1/configuration/freights/{carrierId}/values/update" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1freights~1{carrierId}~1values~1update/post

low `NAME-01` inconsistent casing: kebab-case,snake_case,camelcase

contract · 1 place · 1 point taken

Impact. Inconsistent naming makes the API harder to learn and guess; developers cannot predict names from the ones they have seen.

Recommendation. Choose one naming convention and apply it everywhere; keep old names only as documented deprecated aliases.

Where. paths mix kebab-case, snake_case, camelCase with no dominant convention

Evidence. "/api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames" at fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames/get

Evidence. "/api/fulfilment/v1/configuration/pickuppoints/_search" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1pickuppoints~1_search/get

Evidence. "/api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1items~1{skuId}~1warehouses~1{warehouseId}~1supplyLots/get

Evidence. "/api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}" at fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames~1{windowDay}F{windowStartTime}T{windowEndTime}/get

Evidence. "/api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots/{supplyLotId}" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1items~1{skuId}~1warehouses~1{warehouseId}~1supplyLots~1{supplyLotId}/put

Evidence. "/api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots/{supplyLotId}/transfer" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1items~1{skuId}~1warehouses~1{warehouseId}~1supplyLots~1{supplyLotId}~1transfer/post

Evidence. "/api/fulfilment/v1/shipping-policies" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1shipping-policies/get

Evidence. "/api/fulfilment/v1/shipping-policies/{id}" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1shipping-policies~1{id}/get

low `RATE-01` no rate limit documentation

limits · 1 place · 1 point taken

Impact. Integrators cannot size their clients or plan back-off, and learn the limits from production errors.

Recommendation. Document the limits, a 429 response and the headers that report remaining quota and when to retry.

Where. No rate limiting is documented

Evidence. not found: a 429 response, rate-limit headers, or a description of rate limits; inspected fulfilment-api.json#, fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames/get, fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames~1{windowDay}F{windowStartTime}T{windowEndTime}/get and 3 more

medium `CC-PARAM-01` required request property without description

contract · 1 place · 0 points taken, 4 points withheld by the rule's cap

Impact. Developers must guess the meaning, format and valid values of a field they are required to send.

Recommendation. Describe what the property means, its format and valid values.

Where. POST /api/fulfilment/v1/shipping-policies

Evidence. not found: description; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1shipping-policies/post/requestBody/content/application~1json/schema/properties/cubicWeightSettings/properties/minimunAcceptableVolumetricWeight

Every rule

Rule	Family	Version	Result	Findings
`CC-REF-01`	contract	1	not applicable	0
`CC-DESC-01`	contract	1	no gap found	0
`CC-PARAM-01`	contract	1	gap found	43
`CC-RESP-01`	contract	1	gap found	4
`CC-ERR-01`	contract	1	gap found	53
`CC-EX-01`	examples	1	gap found	1
`CC-EX-02`	examples	1	no gap found	0
`ERR-05`	errors	1	not applicable	0
`CC-CONFLICT-01`	contract	1	could not be assessed (needs guide pages; none was supplied)	0
`CC-PATH-01`	contract	1	no gap found	0
`CC-SCHEMA-01`	contract	1	gap found	2
`CC-TYPE-01`	contract	1	no gap found	0
`CC-CONSIST-01`	contract	1	gap found	1
`RATE-02`	limits	1	not applicable	0
`WH-01`	webhooks	1	not applicable	0
`WH-02`	webhooks	1	not applicable	0
`WH-03`	webhooks	1	not applicable	0
`AUTH-03`	onboarding	1	not applicable	0
`IDEM-02`	reliability	1	not applicable	0
`ERR-04`	errors	1	not applicable	0
`WF-04`	workflow	1	not applicable	0
`DATA-02`	data	1	gap found	1
`DATA-03`	data	1	not applicable	0
`CC-ENV-01`	contract	1	no gap found	0
`AUTH-04`	onboarding	1	not applicable	0
`AUTH-01`	onboarding	1	no gap found	0
`AUTH-02`	onboarding	1	gap found	2
`CC-SEC-01`	contract	1	no gap found	0
`NAME-01`	contract	1	gap found	2
`PAG-01`	pagination	1	gap found	5
`PAG-02`	pagination	1	switched off	0
`RATE-01`	limits	1	gap found	1
`ERR-02`	errors	1	not applicable	0
`IDEM-01`	reliability	1	gap found	1
`CC-DEP-01`	lifecycle	1	not applicable	0
`CC-DESC-02`	contract	1	gap found	11
`CC-DESC-03`	contract	1	switched off	0
`CC-DESC-04`	contract	1	no gap found	0
`LINK-01`	links	1	could not be assessed (needs guide pages; none was supplied)	0
`ON-ENV-01`	onboarding	1	could not be assessed (needs guide pages; none was supplied)	0
`DOC-CODE-01`	documentation	1	could not be assessed (needs guide pages; none was supplied)	0

Method

Every figure is a count, a sum or a sort over the sealed report. Nothing was estimated or generated.
Points are the deductions the profile applies to findings, as recorded in the report's score trace. They rank findings; they are not a measure of how long a fix takes.
A cause is the findings of one rule that share one problem at different places; it counts as one piece of work. Causes are ranked by points taken, then by places, then by severity, then by rule id.
A resource is the first path segment of an operation. A finding with no operation is about the document as a whole and is counted apart.
The detail part shows at most 8 places per cause and the evidence of its first finding. The JSON report and the SARIF export carry every finding.
A rule that could not be assessed is neither a pass nor a deduction. A rule that found nothing while an input it needs was read only in part is not a clean result.
Confidence values in the report are a rule's own estimate, not a calibrated probability, and are not used for any figure here.

Integration readiness teardown

At a glance

Fix first

Families

Hotspots

Operations

Resources

What this report cannot say

Causes in detail

medium CC-ERR-01 no error response documented

medium CC-PARAM-01 required parameter without description

medium PAG-01 no pagination

high CC-SCHEMA-01 no schema for application/json

low CC-DESC-02 weak description: restates its name

low CC-RESP-01 response without description

medium CC-CONSIST-01 conflicting types for freight-values.absolutemoneycost

low AUTH-02 security scheme without description

low CC-DESC-02 weak description: too short

low CC-EX-01 no request or response example

low DATA-02 unformatted date/time properties

low IDEM-01 no idempotency

low NAME-01 verbs in some paths

low NAME-01 inconsistent casing: kebab-case,snake_case,camelcase

low RATE-01 no rate limit documentation

medium CC-PARAM-01 required request property without description