Coverage service

Coverage is the only service a distribution partner calls directly, and the only one that writes policyholder data. It runs in the data plane, once per market, so a Vietnamese coverage is created by a Vietnamese deployment against a Vietnamese database.

The service does two things: it issues a coverage, and it moves one to a new status. Both are described below as behaviour rather than as a request you can copy.

Note

The wire surface is the standard’s. Resource paths, methods, status codes, the error model, pagination and idempotency are declared once in Conventions, and each module’s API page carries the operations over its entities. What is tenant-specific, the host and the scope names your credentials carry, is issued with those credentials, because it differs per tenant by design. See Tenancy and scopes.

What one create does

The call is one request and six steps.

1. Validate the submitted coverage against the product’s own attribute definitions, its currency and premium rules, and its date rules.
2. Resolve the channel and the product from the control plane, over HTTP.
3. Check the product is permitted for that channel. A product the channel may not sell is rejected here, before anything reaches an insurer.
4. Resolve the insurer by asking routing which carrier handles this product, channel and market.
5. Issue by calling that insurer’s system through its adapter, and record the timestamp the insurer returned alongside the one the channel sent.
6. Persist and publish. The coverage is written to the market’s database, then a domain event goes onto Kafka for whatever consumes it downstream.

Only the first five are on the path you are waiting on. The publish is asynchronous, so ledger accounting never sits between a customer tapping a button and a certificate coming back.

One adapter per insurer

Step five is not one integration. Every carrier is reached through its own adapter, which translates between the platform’s model and whatever that insurer’s system actually speaks.

No carrier’s format reaches the interior of the platform. That is the point: insurer systems are the least controllable dependency in this business, they differ from each other in ways that have nothing to do with insurance, and a platform that let those differences leak inward would encode one carrier’s quirks into the shared model. The cost is one adapter to write and maintain per carrier, which is real work and the right work.

Tenant and channel are different parties

Whose book a record belongs to and who sold it are two separate facts, and a request carries both. They are frequently different organisations, so the platform never infers one from the other.

A request also carries an identifier that makes a retry safe. Use a new one for a new coverage, and the same one when you are retrying the same coverage after a timeout.

Status changes are checked against the product

A status change is a request for a transition, not an instruction to set a value. The service validates the requested move against the lifecycle the product itself declares, and there are four ways it can refuse.

The target status may not be one the product declares at all. The product may declare no statuses, in which case it is not stateful and rejects status changes entirely. The move may not be declared while other moves out of the current status are, which means you asked for a transition that does not exist and a different one might work. Or the current status may have no moves out of it, which means the coverage is finished and nothing will change it.

The last two are worth telling apart, and the response says which one you hit. One is worth retrying differently and the other is not worth retrying at all.

Because the lifecycle lives in the catalogue rather than in this service, the set of statuses depends on which product you are working with. The product service explains why.