web UI  ·  WhatsApp agent  ·  MCP  ·  cron      ← channels (each a thin adapter)
                       │  all call the same core
                       ▼
   schema `api`  =  business actions  (this contract)   ← single definition
                       ▼
   public / private / <domain> schemas  =  internal logic, triggers, helpers

{ "data":    { "...": "the affected resource(s): ids, amounts, state" },
  "effects": { "...": "what the command changed, grouped by domain" },
  "warnings":[ { "code": "STOCK_NEGATIVO", "message": "..." } ] }

create or replace function api.crear_<noun>(
  p_body jsonb,
  p_idempotency_key text
) returns jsonb
language plpgsql
security definer
set search_path = ''
as $$
declare
  v_actor   <type> := <resolve from session, NOT from p_body>;  -- R6
  v_id      <type>;
  v_effects jsonb := '{}'::jsonb;
begin
  -- validate (read-only) → RAISE 'CODE: detalle' on failure (R4)

  insert into <domain>.<table> (...)
  values (...)
  on conflict (<idempotency unique key>) do nothing     -- R5
  returning id into v_id;

  if v_id is null then
    select id into v_id from <domain>.<table> where <idempotency key> = ...;
  end if;

  -- collect side-effects into v_effects, grouped by domain (R3)

  return jsonb_build_object(
    'data',     jsonb_build_object('<noun>_id', v_id, 'estado', '...'),
    'effects',  v_effects,
    'warnings', '[]'::jsonb
  );
end; $$;

comment on function api.crear_<noun>(jsonb, text) is
  'Crea <noun>. [IDEMPOTENT: ON CONFLICT (<key>)]. effects: {<dominios>}.';