API Evangelist enhancements for the SantéVet Reimbursement API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the SantéVet Reimbursement API
  version: 1.0.0
extends: openapi/santevet-reimbursement-openapi.yml
x-generated: '2026-08-17'
x-method: generated
x-source: >-
  Derived from live probes of https://reimbursement.api.santevet.com. The harvested
  specification is never mutated — openapi/_original/santevet-reimbursement-openapi-original.json
  is the verbatim fetch from https://reimbursement.api.santevet.com/api/doc.json.
actions:
- target: $.info
  description: >-
    The document has a real title, version and developer contact — the best-formed of SantéVet's
    three contracts. Adding the description it lacks.
  update:
    description: >-
      SantéVet's partner claims and reimbursement API. Creates and retrieves pet-insurance
      reimbursement claims, lists a client's or an animal's claims, and retrieves the
      third-party-payment (tiers payant) instalment schedule for a coverage — the API behind
      SantéVet's PayVet product, where the insurer settles directly with the veterinary clinic
      instead of reimbursing the owner afterwards. Six operations. Requires partner credentials.
- target: $.components.securitySchemes
  description: >-
    THE MOST IMPORTANT CORRECTION IN THIS OVERLAY. The document declares NO securitySchemes and
    NO security requirement, yet every operation returns 401 "User authentication required"
    anonymously. An agent reading this specification would conclude the API is open. Recording
    the observed scheme, matching the sibling toolkit API's declared apiKey scheme.
  update:
    x-apievangelist-observed-apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        OBSERVED, NOT DECLARED. Partner API key in the Authorization header, consistent with the
        apiKey scheme the SantéVet Toolkit API declares. Verified by
        GET https://reimbursement.api.santevet.com/api/v1/reimbursements/1 returning HTTP 401
        with body {"message":"User authentication required"}.
- target: $.info
  description: Recording the undeclared authentication and error contract at document level.
  update:
    x-apievangelist-auth:
      declared_in_spec: false
      observed: true
      scheme: apiKey
      location: header
      parameter: Authorization
      observed_status: 401
      observed_body: '{"message":"User authentication required"}'
      issuance: >-
        Not self-serve. Partner onboarding via https://www.santevet.com/partenaire-btob
    x-apievangelist-error-envelope:
      media_type: application/json
      shape:
        message: human-readable explanation
      note: >-
        A flat {"message"} envelope — not RFC 7807, and different from the problem+json / Hydra
        envelopes the sibling toolkit API returns. No error code, no type URI, no stable
        identifier.
- target: $.info
  description: >-
    Recording the operations that declare no failure response at all, so the gap is
    machine-visible.
  update:
    x-apievangelist-gaps:
      declared_401_responses: 0
      declared_403_responses: 0
      declared_429_responses: 0
      operations_with_no_4xx:
      - createReimbursement
      - updateReimbursement
      - findSchedule
      rate_limit_headers: none
      request_id_header: none
      idempotency: none
      pagination: none
      note: >-
        createReimbursement is a multipart/form-data write with no declared failure mode and no
        idempotency key — a retried claim submission has no published deduplication contract.
- target: $.servers
  description: >-
    The servers[] block is correct and complete and is NOT altered. Recording only the
    observation about the third entry.
  update:
    x-apievangelist-server-note: >-
      The Development server https://{user}.reimbursement-api.srv-dev-web-2021.santevet.lan
      enumerates four developer trigrams (xch, gle, mau, tpe) in a public document. Unreachable
      from outside SantéVet's network and harmless to callers, but it is internal topology and
      staff-adjacent initials published in a public contract — worth raising with the provider.
    x-apievangelist-tls:
      production_host: reimbursement.api.santevet.com
      tls_version: TLSv1.3
      hsts: false
      note: >-
        No HSTS header on the API host, unlike www.santevet.com which sets
        max-age=63072000. See security/santevet-domain-security.yml.
- target: $.info
  description: >-
    Recording the dangling identifier problem — the single biggest usability gap in this contract.
  update:
    x-apievangelist-dangling-references:
      note: >-
        These fields appear on reimbursement DTOs but resolve to no operation in any published
        SantéVet contract, so an agent handed a reimbursement cannot follow any of them.
      fields:
      - contract_id
      - clinic_id
      - veterinary_id
      - sinister_notification_id
      - correspondence_id
      - origin_id
      partially_resolvable:
      - field: coverage_id
        via: GET /api/v1/third-party-payments/{coverageId}/schedule
      - field: animal_id
        via: GET /api/v1/animals/{animalId}/reimbursements
      probable_cross_api_binding:
      - field: origin_id
        to: 'SantéVet Toolkit API OrigineCommerciale (/commercial-origins/{id})'
        confidence: medium
      detail: data-model/santevet-data-model.yml
- target: $.info
  description: >-
    Recording that the three near-duplicate reimbursement schemas are not distinguishable by name.
  update:
    x-apievangelist-schema-note:
      duplicates:
      - schema: ApiReimbursement
        properties: 25
        returned_by: findReimbursement
      - schema: ApiReimbursement2
        properties: 18
        returned_by: findAllReimbursementsByAnimal
      - schema: ApiReimbursement3
        properties: 19
        returned_by: findAllReimbursementsByClient
      note: >-
        Auto-numbered suffixes carry no meaning. The same applies to ApiClinic / ApiClinic2 /
        ApiClinic3. Naming them for their serialization context would make the contract
        self-explanatory.
- target: $.info
  description: API Evangelist profile cross-references.
  update:
    x-apievangelist-artifacts:
      authentication: authentication/santevet-authentication.yml
      conventions: conventions/santevet-conventions.yml
      errors: errors/santevet-problem-types.yml
      data_model: data-model/santevet-data-model.yml
      lifecycle: lifecycle/santevet-lifecycle.yml
      conformance: conformance/santevet-conformance.yml
      rate_limits: rate-limits/santevet-rate-limits.yml
      sandbox: sandbox/santevet-sandbox.yml
      skills: skills/_index.yml