Skip to content

External Codice event API

The event API lets an authenticated external system trigger the same player Codice path as a physical marker.

Endpoint and authentication

POST /api/codice/event
Authorization: Bearer <named-connector-credential>
Content-Type: application/json

Example:

curl --fail-with-body 'https://showcase.example/api/codice/event' \
  -H 'Authorization: Bearer <named-connector-credential>' \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"MEMBER-42","connector":"crm","action":"tap","dropZone":"scan-desk"}'

Use either code for a direct Showcase Codice code or externalId plus optional connector namespace for an alias. action is tap, down, or up. The named drop zone supplies position and rotation.

Codice database used to create people/codes and manage aliases

Codice DB is the operator surface for seeded codes. Open an entry to manage manual aliases; connector-fed aliases remain connector-managed.

Aliases

Aliases resolve at event time. A namespaced alias avoids collisions between external systems. Manual aliases can be added in Codice DB or imported by CSV; connector-fed aliases are read-only from the manual panel. Test at least one production-shaped alias before deployment.

There is no dry-run mode for network callers

The event API always dispatches. There is no resolution-only or dry-run option a network caller can pass — every request that resolves to a known code is sent on to the player. Test with a harmless code and drop zone instead of relying on a safe preview call.

Unknown IDs and rejections

  • Unknown code or externalId: the API returns HTTP 404 with {"status": "unknown-id", "policy": "ignore" | "wall-feedback"}. Which policy applies is the drop zone's configured unknownIdPolicy, not something the caller chooses per call. When the policy is wall-feedback, the response also includes delivered.
  • No player connected, or the control server is unavailable: the API returns HTTP 503 with an error detail. This is the case to watch for in monitoring — it means the event never reached the wall.
  • HTTP 401 means the named connector credential is missing, invalid, or revoked. HTTP 400 means payload or drop-zone validation failed.

Connected-player test

  1. Start the packaged player and confirm its control connection is healthy.
  2. Create/select a harmless test code and drop zone.
  3. Record the player/server event count.
  4. Send one tap request for the test code.
  5. Verify exactly one synthetic marker down/up sequence and expected wall behavior.
  6. Send a request for a code that does not exist and confirm you get a 404 with status: "unknown-id" rather than any player action.
  7. Send malformed input and verify the count does not change.

Never retry a down or up request blindly; use tap for operator testing.