{
  "openapi": "3.0.3",
  "info": {
    "title": "ACCUZ® Brand Guard™ Customer Verification API",
    "version": "1.0.0",
    "description": "Server-to-server NFC verification API. Send the untouched URL captured at the approved website entry to the assigned API. Each 200 response contains an immutable verification decision. SKU and displayPath are optional.",
    "x-platform-version": "Capability dependent; confirm the assigned environment with the operator",
    "x-http-api-version": "v1",
    "x-package-version": "1.3.3"
  },
  "servers": [
    {
      "url": "https://api.example.invalid",
      "description": "Placeholder. Set the HTTPS API origin assigned to your integration by BrandGuard before making live calls."
    }
  ],
  "paths": {
    "/api/customer/v1/verifications": {
      "post": {
        "operationId": "executeVerification",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "description": "Requires verifications:execute and explicit integration/environment binding. Idempotency scope: environment + tenant + stable integration + case-sensitive key. Rotated token for the same integration can recover. clientRequestId excluded from digest. Pending lease 60s; processing budget 30s. Terminal decisions/timestamps retained unchanged. BrandGuard does not persist raw tapUrl. visitorContext is also excluded from the digest. First durable context and response capability cannot be changed by retry; changed encoding/tap URL still conflicts. Location uses only the local database and never blocks an otherwise valid verification.",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Original immutable terminal receipt plus separate current eligibility.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                }
              }
            }
          },
          "202": {
            "description": "Pending. GET cannot process; resubmit identical POST when requiresResubmission is true.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pending"
                }
              }
            }
          },
          "400": {
            "description": "Malformed input or unsupported encoding.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Scope, tenant, integration or environment not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency key reused with different business input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 4096 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "application/json required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retain original key and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "503": {
            "description": "Dependency failure or uncertain commit. Retain original key and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          }
        }
      }
    },
    "/api/customer/v1/verifications/{verificationId}": {
      "get": {
        "operationId": "readVerification",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "description": "Requires verifications:read for original tenant/integration/environment. Read only; does not process SUN or change counters/timestamps. Return original decidedAt/acceptedAt on historical retrieval.",
        "parameters": [
          {
            "in": "path",
            "name": "verificationId",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 32
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Original immutable terminal receipt plus separate current eligibility.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                }
              }
            }
          },
          "202": {
            "description": "Pending. GET cannot process; resubmit identical POST when requiresResubmission is true.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pending"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Scope, tenant, integration or environment not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No operation in authorized integration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retain original key and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "503": {
            "description": "Dependency failure or uncertain commit. Retain original key and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Explicit verification token; business API tokens do not gain verification scopes."
      }
    },
    "schemas": {
      "Request": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "encodingVersionId",
          "tapUrl"
        ],
        "properties": {
          "encodingVersionId": {
            "type": "string",
            "maxLength": 32
          },
          "tapUrl": {
            "type": "string",
            "maxLength": 1024,
            "description": "Exact original URL; maximum 1024 UTF-8 bytes. Do not decode/re-encode or sort."
          },
          "clientRequestId": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 128,
            "description": "Optional correlation label: 1-128 characters without control characters; excluded from the business digest."
          },
          "visitorContext": {
            "$ref": "#/components/schemas/VisitorContext"
          }
        },
        "description": "Maximum 4096 UTF-8 bytes. Duplicate and unknown properties are rejected at both object levels. visitorContext does not affect authentication or business idempotency."
      },
      "Receipt": {
        "type": "object",
        "required": [
          "verificationId",
          "result",
          "decidedAt",
          "acceptedAt",
          "uid",
          "itemId",
          "counter",
          "acceptedVerificationCount",
          "seal",
          "encodingVersionId",
          "clientRequestId"
        ],
        "properties": {
          "verificationId": {
            "type": "string"
          },
          "result": {
            "type": "string",
            "enum": [
              "valid",
              "invalid_signature",
              "replay",
              "unknown_tag",
              "policy_rejected"
            ]
          },
          "decidedAt": {
            "type": "string",
            "format": "date-time"
          },
          "acceptedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "uid": {
            "type": "string",
            "nullable": true
          },
          "itemId": {
            "type": "string",
            "nullable": true
          },
          "counter": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 16777215
          },
          "acceptedVerificationCount": {
            "type": "integer",
            "nullable": true
          },
          "encodingVersionId": {
            "type": "string"
          },
          "clientRequestId": {
            "type": "string",
            "nullable": true
          },
          "seal": {
            "type": "object",
            "properties": {
              "supported": {
                "type": "boolean",
                "description": "False for ordinary DNA, including physical VOID packaging."
              },
              "state": {
                "type": "string",
                "nullable": true,
                "description": "Authenticated electronic seal evidence. CC: no opening reported by this reading; OC/OO (historical CO): opening/change reported, never render intact; I: uninitialized, current policy rejects acceptance; null: no usable authenticated evidence. If supported=false, ordinary DNA has no electronic seal, even with physical VOID packaging. Render separately from authentication result."
              }
            },
            "required": [
              "supported",
              "state"
            ]
          },
          "sku": {
            "type": "string",
            "nullable": true,
            "maxLength": 100,
            "description": "Optional exact product or variant SKU snapshot, case-sensitive. May be absent on historical receipts, for an unavailable SKU or in UID-only mode. A malformed or unmapped optional SKU cannot invalidate the verification decision."
          },
          "displayPath": {
            "type": "string",
            "nullable": true,
            "description": "Optional same-origin display path for an accepted tap. Item-specific assignments have priority. In path mode the server may fall back to variant or product defaults. A missing or unsafe route leaves the receipt available on the generic page."
          }
        }
      },
      "Result": {
        "type": "object",
        "required": [
          "receipt",
          "recovered",
          "currentEligibility"
        ],
        "properties": {
          "receipt": {
            "$ref": "#/components/schemas/Receipt"
          },
          "recovered": {
            "type": "boolean",
            "description": "True on retrieval or recovery of an existing operation. Recovery never increments acceptance. When a same-key retry produces the first confirmed result for the active tap, its first presentation can show that tap. Later views display the saved decision and original time."
          },
          "currentEligibility": {
            "type": "object",
            "properties": {
              "eligible": {
                "type": "boolean"
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "eligible",
              "checkedAt"
            ],
            "description": "Eligibility at checkedAt, separate from the immutable historical receipt; do not label a retrieved receipt as a new NFC tap."
          },
          "visitorLocation": {
            "$ref": "#/components/schemas/VisitorLocation"
          }
        }
      },
      "Pending": {
        "type": "object",
        "required": [
          "verificationId",
          "status",
          "requiresResubmission"
        ],
        "properties": {
          "verificationId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending"
            ]
          },
          "requiresResubmission": {
            "type": "boolean"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "retrySameRequest"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "retrySameRequest": {
                "type": "boolean"
              }
            }
          }
        },
        "required": [
          "error"
        ]
      },
      "VisitorContext": {
        "type": "object",
        "nullable": true,
        "additionalProperties": false,
        "description": "Optional visitor metadata. Omit or send null for the response without location metadata. An empty object opts into unavailable location. First durable context, including absence, is frozen across retries/recovery. Supply only a visitor IP obtained at a controlled server ingress. Excluded from business digest. No browser-provided city, GPS or user agent.",
        "properties": {
          "ipAddress": {
            "type": "string",
            "nullable": true,
            "maxLength": 64,
            "description": "Single IPv4/IPv6 address, no controls. Missing, invalid or non-public addresses do not block verification; they return an unavailable reason. Never substitute your website server IP."
          }
        }
      },
      "VisitorLocation": {
        "type": "object",
        "additionalProperties": false,
        "description": "Auxiliary coarse IP estimate reported by the customer website, not authenticated phone location. Present only when the FIRST operation opted in. Saved terminal snapshot, unchanged by later GET/retries or database updates. No raw IP.",
        "required": [
          "state",
          "city",
          "country",
          "countryCode",
          "source",
          "unavailableReason",
          "attribution"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "available",
              "unavailable"
            ]
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "countryCode": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "enum": [
              "customer_website_reported"
            ]
          },
          "unavailableReason": {
            "type": "string",
            "nullable": true,
            "enum": [
              null,
              "missing_ip",
              "invalid_ip",
              "non_public_ip",
              "disabled",
              "local_database_required",
              "database_unavailable",
              "not_found"
            ]
          },
          "attribution": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "provider",
              "url",
              "license",
              "licenseUrl"
            ],
            "properties": {
              "provider": {
                "type": "string",
                "enum": [
                  "DB-IP"
                ]
              },
              "url": {
                "type": "string",
                "enum": [
                  "https://db-ip.com"
                ]
              },
              "license": {
                "type": "string",
                "enum": [
                  "CC BY 4.0"
                ]
              },
              "licenseUrl": {
                "type": "string",
                "enum": [
                  "https://creativecommons.org/licenses/by/4.0/"
                ]
              }
            }
          }
        }
      }
    },
    "headers": {
      "RetryAfter": {
        "description": "Minimum retry delay in seconds. Keep the original Idempotency-Key and request body for POST retries.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    }
  },
  "x-error-codes": [
    {
      "status": 400,
      "code": "invalid_idempotency_key",
      "retrySameRequest": false,
      "action": "Send exactly one Idempotency-Key header."
    },
    {
      "status": 400,
      "code": "invalid_body",
      "retrySameRequest": false,
      "action": "Validate JSON, encodingVersionId, tapUrl and optional fields against the request schema. The complete UTF-8 URL must fit 1024 bytes."
    },
    {
      "status": 400,
      "code": "invalid_encoding_version",
      "retrySameRequest": false,
      "action": "Confirm the immutable encoding ID for the environment and selected connection with its administrator."
    },
    {
      "status": 400,
      "code": "invalid_tap_url",
      "retrySameRequest": false,
      "action": "Inspect the approved origin, exact NFC entry and encoding template. Capture the next tap before any rewrite."
    },
    {
      "status": 401,
      "code": "not_authorized",
      "retrySameRequest": false,
      "action": "Check the server secret, expiry, revocation and assigned API origin."
    },
    {
      "status": 403,
      "code": "not_authorized",
      "retrySameRequest": false,
      "action": "Check the scope granted for this API operation."
    },
    {
      "status": 403,
      "code": "integration_not_authorized",
      "retrySameRequest": false,
      "action": "Check tenant, connection, active credential and environment binding."
    },
    {
      "status": 403,
      "code": "execute_scope_required",
      "retrySameRequest": false,
      "action": "POST requires verifications:execute."
    },
    {
      "status": 403,
      "code": "read_scope_required",
      "retrySameRequest": false,
      "action": "GET requires verifications:read. An execute-only caller can recover with the original POST."
    },
    {
      "status": 404,
      "code": "verification_not_found",
      "retrySameRequest": false,
      "action": "Check the receipt ID within the original integration."
    },
    {
      "status": 409,
      "code": "idempotency_conflict",
      "retrySameRequest": false,
      "action": "The key is already bound to a different business request. Recover the original operation using its original request."
    },
    {
      "status": 413,
      "code": "body_too_large",
      "retrySameRequest": false,
      "action": "Limit the JSON body to 4096 bytes."
    },
    {
      "status": 415,
      "code": "json_required",
      "retrySameRequest": false,
      "action": "Use Content-Type: application/json."
    },
    {
      "status": 429,
      "code": "rate_limited",
      "retrySameRequest": true,
      "action": "Respect Retry-After and resume the same operation."
    },
    {
      "status": 503,
      "code": "operation_busy",
      "retrySameRequest": true,
      "action": "Wait and retry the identical POST."
    },
    {
      "status": 503,
      "code": "retry_same_request",
      "retrySameRequest": true,
      "action": "Outcome is uncertain. Preserve the original key, body and API origin."
    },
    {
      "status": 503,
      "code": "environment_unconfigured",
      "retrySameRequest": true,
      "action": "Contact the environment operator. Retry only the same pending operation once service recovers."
    }
  ]
}
