.. _core-api-known-limitations:

Known limitations of the v1 Core API
------------------------------------

The Core API surface evolved over many releases and a small number of
endpoints carry contracts that are stricter or more permissive than
they look at first glance. This page lists those quirks so you can
code defensively against them and so you know which behaviours are
intentional rather than bugs.

The :ref:`OpenAPI specification <core-openapi>` remains the
authoritative source for every operation's exact request and response
shape. The notes below complement the spec; they do not replace it.

Boolean parameters sent as strings
==================================

A handful of body parameters express true/false as the JSON strings
``"0"`` and ``"1"`` rather than as a JSON ``boolean``. Sending an
actual ``true`` / ``false`` is not accepted.

.. list-table::
   :header-rows: 1
   :widths: 40 25 35

   * - Operation
     - Parameter
     - Accepted values
   * - ``POST /finance_bank/``
     - ``use_parent``
     - ``"0"`` (false), ``"1"`` (true)
   * - ``PUT /finance_bank/{id}``
     - ``use_parent``
     - ``"0"``, ``"1"``
   * - ``POST /finance_bank_sepa/``
     - ``use_parent``
     - ``"0"``, ``"1"``
   * - ``GET /cps_close_by/...``
     - ``include_roaming``
     - ``"0"``, ``"1"``, also ``"2"`` (= roaming-contact only)

Path parameters that accept either a UUID or a numeric ID
=========================================================

Two endpoints accept either form on the same path parameter; what is
expected depends on the value of another path segment or on the
length of the value itself.

* ``GET /charge_log/{type}/{uuid}`` — the ``{uuid}`` segment is:

  * a UUID when ``type`` is ``customer`` or ``cp``,
  * a numeric card ID **or** the card's RFID tag string when
    ``type`` is ``card`` (the endpoint matches by numeric ID first,
    then falls back to the RFID tag),
  * either form when ``type`` is ``details``.

* ``PUT /cp_connector/{cp_connector_id}`` — accepts both the numeric
  ID and the connector's UUID.

The spec types each parameter as the broader of the two forms
(``string`` for the first, ``integer`` for the second) for backward
compatibility. The per-operation description in the spec calls out
the exact contract.

Identifier fields that may be ``null``
======================================

A few response fields look like they should always carry a UUID but
can in fact be ``null`` for older records that were created before
the identifier was introduced. Treat the following as nullable:

* ``Cp.uuid``
* ``CpConnector.uuid``
* ``id`` on ``Company`` and ``User`` responses

Where the spec carries ``format: uuid`` the field is guaranteed to
be a UUID when present. Where ``format: uuid`` is absent (notably the
fields above) the value is still a string but may be ``null``; do not
rely on it as a stable identifier.

Mixed casing in body and query parameters
=========================================

For historical reasons body and query parameter names use a mix of
``snake_case`` and ``camelCase`` across the surface. There is no rule
you can apply to predict the casing of a parameter you have not used
before — check the per-operation spec for the authoritative name.
See :ref:`Conventions <core-api-conventions>` for the broader naming
overview.

Path parameter naming across the ``/contact`` family
====================================================

The same logical parameter is named ``{contact_uuid}`` on
``GET /contact/{contact_uuid}`` and ``{uuid}`` on
``PUT /contact/{uuid}`` and ``DELETE /contact/{uuid}``. The runtime
behaviour is identical (paths are positional), but SDK generators
that derive method-argument names from the spec may emit slightly
different signatures across the three verbs. Pass the same value
regardless of the parameter's name in the spec.

Endpoints not intended for new integrations
===========================================

The following endpoints exist for backward compatibility only. New
integrations should not use them; equivalent functionality is
available through the listed replacement.

.. list-table::
   :header-rows: 1
   :widths: 45 55

   * - Endpoint
     - Replacement
   * - ``GET /datatable_charge_logs/{type}/{uuid}``
     - ``GET /charge_log/{type}/{uuid}``
   * - ``GET /datatable_invoices/{type}/{id}``
     - Newer invoice resources under ``/finance/`` and ``/invoice/``
   * - ``POST /payment_transaction_verify/``
     - No public replacement — this endpoint is invoked internally by a
       scheduled job and is not intended for external callers.