Restaurant Equis API — Pydantic and ORM Data Models

Every request body sent to the Restaurant Equis API is validated by Pydantic v2 before it reaches the database layer, and every JSON response is serialized through these same schemas. The SQLAlchemy ORM models map one-to-one with the PostgreSQL tables defined in the public schema (for restaurant operations) and the Inventario schema (for stock and supplier management). Familiarity with these shapes is essential whether you are building a new frontend widget, scripting bulk imports, or writing integration tests.

Enums

All enum values are stored as plain strings in PostgreSQL ENUM columns. Pydantic coerces input strings to the matching member at validation time, so casing must match exactly.

class EstadoMesaEnum(str, enum.Enum):
    disponible        = "disponible"
    ocupada           = "ocupada"
    reservada         = "reservada"
    fuera_de_servicio = "fuera_de_servicio"

CategoriaPlatoEnum.acompanante is stored as the Unicode string "acompañante" (with ñ) in PostgreSQL. Ensure your HTTP client sends the string encoded as UTF-8.

Table Models

`public.mesa` — Table Management

MesaIn and MesaOut represent a physical dining table in the restaurant. Use these schemas when creating or reading table records via /api/mesas.

MesaIn — Create/Update Table

Sent as the JSON body when creating a new table.

capacidad

integer

required

Seating capacity of the table (number of guests it can accommodate).

estado

EstadoMesaEnum

Current status of the table. Defaults to disponible when omitted. One of disponible, ocupada, reservada, or fuera_de_servicio.

ubicacion

string

Free-text location description (e.g., "Terraza", "Salón principal"). Optional; stored as up to 100 characters.

Example MesaIn body

{
  "capacidad": 4,
  "estado": "disponible",
  "ubicacion": "Terraza"
}

MesaOut — Table Response

Returned by GET /api/mesas and POST /api/mesas. Extends MesaIn with the auto-generated primary key.

id_mesa

integer

Auto-generated primary key for the table.

capacidad

integer

Seating capacity.

estado

EstadoMesaEnum

Current table status.

ubicacion

string

Location description. null if not set.

Order Models

PedidoIn — Create Order

Sent as the JSON body when creating a new order via POST /api/pedidos.

tipo_pedido

TipoPedidoEnum

required

Channel through which the order was placed. One of mesa, pickup, or delivery.

estado_orden

EstadoOrdenEnum

Initial status of the order. Defaults to recibido when omitted.

id_mesa

integer

Table number. Required when tipo_pedido is mesa; omit for pickup and delivery orders.

cedula_cliente

string

required

National ID (cédula) of the customer placing the order. Used as the foreign key to the cliente table.

cliente_nombre

string

Full name of the customer. Used only to auto-register the customer if no record with cedula_cliente exists yet.

cliente_telefono

string

Phone number of the customer. Used only to auto-register the customer if no record with cedula_cliente exists yet.

direccion_envio

string

Delivery address. Required when tipo_pedido is delivery.

detalles

DetallePedidoIn[]

required

List of line items included in this order. Must contain at least one item.

Show DetallePedidoIn fields

id_plato

integer

required

Primary key of the dish being ordered, referencing public.plato.id_plato.

cantidad

integer

required

Number of units of this dish ordered.

subtotal

float

required

Pre-calculated line subtotal (precio × cantidad). The API stores this value as provided; no server-side recalculation is performed.

Example PedidoIn body

{
  "tipo_pedido": "delivery",
  "cedula_cliente": "12345678",
  "cliente_nombre": "Ana Torres",
  "cliente_telefono": "0412-5550123",
  "direccion_envio": "Av. Principal, Local 4, Caracas",
  "detalles": [
    { "id_plato": 3, "cantidad": 2, "subtotal": 19.98 },
    { "id_plato": 7, "cantidad": 1, "subtotal": 4.50 }
  ]
}

PedidoOut — Order Response

Returned by GET /api/pedidos, GET /api/pedidos/{id}, and on success from POST /api/pedidos.

num_ticket

integer

Auto-generated primary key for the order.

tipo_pedido

TipoPedidoEnum

Order channel: mesa, pickup, or delivery.

estado_orden

EstadoOrdenEnum

Current lifecycle status of the order.

id_mesa

integer

Table number. null for pickup and delivery orders.

cedula_cliente

string

National ID of the customer who placed the order.

direccion_envio

string

Delivery address. null for dine-in and pickup orders.

fecha_creacion

datetime

UTC timestamp of when the order was created (ISO 8601 format).

cliente

ClienteOut

Nested customer object. null if the customer record cannot be resolved.

Show ClienteOut fields

cedula_cliente

string

Customer national ID.

nombre

string

Full name.

telefono

string

Phone number.

string

Email address. null if not provided.

direccion_habitual

string

Usual delivery address. null if not provided.

detalles

DetallePedidoOut[]

List of line items attached to this order. Defaults to an empty list.

Show DetallePedidoOut fields

num_ticket

integer

Foreign key back to the parent order.

id_plato

integer

Foreign key to the dish (public.plato.id_plato).

cantidad

integer

Number of units ordered.

subtotal

float

Line subtotal as stored.

plato

PlatoOut

Nested dish object. null if the dish cannot be resolved.

Show PlatoOut fields

id_plato

integer

Dish primary key.

nombre

string

Dish name.

descripcion

string

Description text. null if not set.

precio

float

Unit price.

categoria

CategoriaPlatoEnum

Dish category.

PedidoUpdateEstatus — Update Order Status

Sent as the JSON body when updating only the status of an existing order via PUT /api/pedidos/{id}.

estado_orden

EstadoOrdenEnum

required

The new lifecycle status to assign to the order. One of recibido, preparando, listo, or entregado.

Example PedidoUpdateEstatus body

{
  "estado_orden": "preparando"
}

FacturaIn — Create Invoice

Sent as the JSON body when generating a new invoice via POST /api/facturas.

num_ticket

integer

required

Foreign key to the originating order (public.pedido.num_ticket). One invoice per order — this value must be unique.

subtotal

float

required

Pre-tax order total.

impuesto

float

Tax amount to apply. Defaults to 0 when omitted.

total

float

required

Final amount charged (subtotal + impuesto).

estado_pago

EstadoPagoEnum

Payment status at the time of invoice creation. Defaults to pendiente when omitted.

metodo_pago

string

Payment method description (e.g., "efectivo", "tarjeta"). Optional; stored as up to 30 characters.

Example FacturaIn body

{
  "num_ticket": 17,
  "subtotal": 24.48,
  "impuesto": 3.67,
  "total": 28.15,
  "estado_pago": "pagado",
  "metodo_pago": "tarjeta"
}

FacturaOut — Invoice Response

Returned when a Factura is generated for a completed order. A Factura has a one-to-one relationship with a Pedido via num_ticket.

num_factura

integer

Auto-generated primary key for the invoice.

num_ticket

integer

Foreign key to the originating order (public.pedido.num_ticket). Unique — one invoice per order.

fecha_emision

datetime

UTC timestamp of invoice generation (ISO 8601 format).

subtotal

float

Pre-tax order total.

impuesto

float

Tax amount applied. Defaults to 0 if not specified at creation time.

total

float

Final amount charged (subtotal + impuesto).

estado_pago

EstadoPagoEnum

Payment status: pendiente, pagado, or anulado. Defaults to pendiente.

metodo_pago

string

Payment method description (e.g., "efectivo", "tarjeta"). null if not recorded.

Example FacturaOut

{
  "num_factura": 42,
  "num_ticket": 17,
  "fecha_emision": "2024-11-15T14:32:00Z",
  "subtotal": 24.48,
  "impuesto": 3.67,
  "total": 28.15,
  "estado_pago": "pagado",
  "metodo_pago": "tarjeta"
}

Product Models

PlatoIn — Create/Update Dish

Sent as the JSON body when creating a dish via POST /api/productos.

nombre

string

required

Display name of the dish. Stored as up to 100 characters.

descripcion

string

Free-text description of the dish. Optional; stored as up to 255 characters.

precio

float

required

Unit price with up to two decimal places (maps to NUMERIC(8,2) in PostgreSQL).

categoria

CategoriaPlatoEnum

required

Dish category. One of entrada, plato_principal, postre, bebida, or acompañante.

PlatoOut — Dish Response

Returned by GET /api/productos and nested inside DetallePedidoOut.

id_plato

integer

Auto-generated primary key.

nombre

string

Dish name.

descripcion

string

Description text. null if none was provided.

precio

float

Unit price.

categoria

CategoriaPlatoEnum

Dish category.

Customer Model

ClienteIn and ClienteOut share the same fields. The only distinction is that ClienteOut enables from_attributes=True for ORM serialization.

ClienteIn / ClienteOut — Customer

cedula_cliente

string

required

National ID number. Acts as the primary key in public.cliente. Stored as up to 20 characters.

nombre

string

required

Full name of the customer. Stored as up to 100 characters.

telefono

string

required

Contact phone number. Stored as up to 20 characters.

string

Email address. Optional; stored as up to 100 characters.

direccion_habitual

string

Usual delivery or home address. Optional; stored as up to 255 characters.

Example ClienteIn body

{
  "cedula_cliente": "12345678",
  "nombre": "Ana Torres",
  "telefono": "0412-5550123",
  "email": "ana.torres@email.com",
  "direccion_habitual": "Av. Principal, Local 4, Caracas"
}

Inventory Models

Inventory tables live in the Inventario PostgreSQL schema, separate from the public schema used by restaurant operations. Field names follow PascalCase to mirror the original database conventions.

InsumoIn — Create Inventory Item

Sent as the JSON body when creating a new supply item via POST /api/inventario.

Nombre_Insumo

string

required

Name of the supply item. Must be unique across all items; stored as up to 100 characters.

Unidad_Medida

string

required

Unit of measurement (e.g., "kg", "litros", "unidades"). Stored as up to 20 characters.

Stock_Actual

float

Current quantity on hand. Defaults to 0. Maps to NUMERIC(12,4) in PostgreSQL.

Stock_Minimo

float

Minimum acceptable stock level before restocking is required. Defaults to 0.

Punto_Reorden

float

Stock level at which a purchase order should be triggered. Defaults to 0.

FK_IDCategoria

integer

Foreign key to Inventario.Categoria.ID_Categoria. Optional; null if the item is uncategorized.

InsumoOut — Inventory Item Response

Returned by GET /api/inventario and POST /api/inventario.

ID_Insumos

integer

Auto-generated primary key (BigInteger in PostgreSQL).

Nombre_Insumo

string

Name of the supply item.

Unidad_Medida

string

Unit of measurement.

Stock_Actual

float

Current stock level.

Stock_Minimo

float

Minimum stock threshold.

Punto_Reorden

float

Reorder trigger level.

FK_IDCategoria

integer

Category ID. null if uncategorized.

Supplier Models

ProveedorIn — Create Supplier

All fields are required when registering a new supplier via POST /api/proveedores.

Nombre_Empresa

string

required

Company name. Stored as up to 150 characters.

Identificacion_RIF

string

required

Venezuelan tax identification number (RIF). Must be unique; stored as up to 30 characters. The underlying PostgreSQL column is named Identificación_RIF (with accent).

Ciudad

string

required

City where the supplier operates. Stored as up to 100 characters.

Telefono_Empresa

string

required

Company phone number. Stored as up to 30 characters.

Email_Empresa

string

required

Company email address. Must be unique; stored as up to 100 characters.

Direccion

string

required

Full business address. Stored as up to 255 characters.

Nombre_Encargado

string

required

Name of the account contact or manager. Stored as up to 100 characters.

Example ProveedorIn body

{
  "Nombre_Empresa": "Distribuidora Central C.A.",
  "Identificacion_RIF": "J-29876543-2",
  "Ciudad": "Valencia",
  "Telefono_Empresa": "0241-8887766",
  "Email_Empresa": "ventas@districentral.com",
  "Direccion": "Zona Industrial Norte, Galpón 12, Valencia",
  "Nombre_Encargado": "Carlos Mendoza"
}

ProveedorOut — Supplier Response

Returned by GET /api/proveedores, POST /api/proveedores, and PUT /api/proveedores/{id}. Extends ProveedorIn with the auto-generated primary key.

ID_Proveedor

integer

Auto-generated primary key (BigInteger in PostgreSQL).

Nombre_Empresa

string

Company name.

Identificacion_RIF

string

Company RIF tax ID.

Ciudad

string

Operating city.

Telefono_Empresa

string

Company phone.

Email_Empresa

string

Company email.

Direccion

string

Business address.

Nombre_Encargado

string

Contact person name.

Report Models

ResumenReporte — Dashboard Summary

Returned by GET /api/reportes/resumen. Provides a period-over-period snapshot for the management dashboard.

total_pedidos

integer

Total number of orders in the current reporting period.

ingresos_brutos

float

Gross revenue (sum of all invoice totals) in the current period.

tiempo_promedio_seg

float

Average order fulfillment time in seconds, measured from order creation to entregado status.

pct_cambio_pedidos

float

Percentage change in total orders compared with the previous period. Positive values indicate growth.

pct_cambio_ingresos

float

Percentage change in gross revenue compared with the previous period. Positive values indicate growth.

Example ResumenReporte response

{
  "total_pedidos": 143,
  "ingresos_brutos": 4821.60,
  "tiempo_promedio_seg": 1320.5,
  "pct_cambio_pedidos": 12.4,
  "pct_cambio_ingresos": 8.7
}

Database Tables (ORM)

The SQLAlchemy models in models.py map to the following PostgreSQL tables. All columns marked PK are auto-incremented unless noted otherwise.

`public` schema — Restaurant Operations

public.mesa

Field	Type	Constraints
`id_mesa`	`INTEGER`	PK, auto-increment, indexed
`capacidad`	`INTEGER`	NOT NULL
`estado`	`EstadoMesaEnum`	NOT NULL, default `disponible`
`ubicacion`	`VARCHAR(100)`	nullable

public.plato

Field	Type	Constraints
`id_plato`	`INTEGER`	PK, auto-increment, indexed
`nombre`	`VARCHAR(100)`	NOT NULL
`descripcion`	`VARCHAR(255)`	nullable
`precio`	`NUMERIC(8,2)`	NOT NULL
`categoria`	`CategoriaPlatoEnum`	NOT NULL

public.cliente

Field	Type	Constraints
`cedula_cliente`	`VARCHAR(20)`	PK (natural key), indexed
`nombre`	`VARCHAR(100)`	NOT NULL
`telefono`	`VARCHAR(20)`	NOT NULL
`email`	`VARCHAR(100)`	nullable
`direccion_habitual`	`VARCHAR(255)`	nullable

public.pedido

Field	Type	Constraints
`num_ticket`	`INTEGER`	PK, auto-increment, indexed
`tipo_pedido`	`TipoPedidoEnum`	NOT NULL
`estado_orden`	`EstadoOrdenEnum`	NOT NULL, default `recibido`
`id_mesa`	`INTEGER`	FK → `public.mesa.id_mesa`, nullable
`cedula_cliente`	`VARCHAR(20)`	FK → `public.cliente.cedula_cliente`, NOT NULL
`direccion_envio`	`VARCHAR(255)`	nullable
`fecha_creacion`	`TIMESTAMP`	NOT NULL, default `utcnow`

public.detalle_pedido

Field	Type	Constraints
`num_ticket`	`INTEGER`	PK + FK → `public.pedido.num_ticket`
`id_plato`	`INTEGER`	PK + FK → `public.plato.id_plato`
`cantidad`	`INTEGER`	NOT NULL
`subtotal`	`NUMERIC(8,2)`	NOT NULL

detalle_pedido uses a composite primary key of (num_ticket, id_plato). Rows are cascade-deleted when the parent pedido is removed.

public.factura

Field	Type	Constraints
`num_factura`	`INTEGER`	PK, auto-increment, indexed
`num_ticket`	`INTEGER`	FK → `public.pedido.num_ticket`, UNIQUE, NOT NULL
`fecha_emision`	`TIMESTAMP`	NOT NULL, default `utcnow`
`subtotal`	`NUMERIC(8,2)`	NOT NULL
`impuesto`	`NUMERIC(8,2)`	NOT NULL, default `0`
`total`	`NUMERIC(8,2)`	NOT NULL
`estado_pago`	`EstadoPagoEnum`	NOT NULL, default `pendiente`
`metodo_pago`	`VARCHAR(30)`	nullable

`Inventario` schema — Stock Management

Inventario.Categoria

Field	Type	Constraints
`ID_Categoria`	`BIGINT`	PK, auto-increment
`Nombre_Categoria`	`VARCHAR(100)`	UNIQUE, NOT NULL

Inventario.Insumos

Field	Type	Constraints
`ID_Insumos`	`BIGINT`	PK, auto-increment
`Nombre_Insumo`	`VARCHAR(100)`	UNIQUE, NOT NULL
`Unidad_Medida`	`VARCHAR(20)`	NOT NULL
`Stock_Actual`	`NUMERIC(12,4)`	NOT NULL, default `0`
`Stock_Minimo`	`NUMERIC(12,4)`	NOT NULL, default `0`
`Punto_Reorden`	`NUMERIC(12,4)`	NOT NULL, default `0`
`FK_IDCategoria`	`BIGINT`	FK → `Inventario.Categoria.ID_Categoria`, nullable

Inventario.Proveedores

Field	Type	Constraints
`ID_Proveedor`	`BIGINT`	PK, auto-increment
`Nombre_Empresa`	`VARCHAR(150)`	NOT NULL
`Identificacion_RIF`	`VARCHAR(30)`	UNIQUE, NOT NULL
`Ciudad`	`VARCHAR(100)`	NOT NULL
`Telefono_Empresa`	`VARCHAR(30)`	NOT NULL
`Email_Empresa`	`VARCHAR(100)`	UNIQUE, NOT NULL
`Direccion`	`VARCHAR(255)`	NOT NULL
`Nombre_Encargado`	`VARCHAR(100)`	NOT NULL

Overview

Endpoints

Data Models

Restaurant Equis API — Pydantic and ORM Data Models

Enums

Table Models

`public.mesa` — Table Management

Order Models

Product Models

Customer Model

Inventory Models

Supplier Models

Report Models

Database Tables (ORM)

`public` schema — Restaurant Operations

`Inventario` schema — Stock Management

Build docs developers (and LLMs) love

Overview

Endpoints

Data Models

Documentation Index

​Enums

​Table Models

​public.mesa — Table Management

​Order Models

​Product Models

​Customer Model

​Inventory Models

​Supplier Models

​Report Models

​Database Tables (ORM)

​public schema — Restaurant Operations

​Inventario schema — Stock Management

Build docs developers (and LLMs) love

Enums

Table Models

`public.mesa` — Table Management

Order Models

Product Models

Customer Model

Inventory Models

Supplier Models

Report Models

Database Tables (ORM)

`public` schema — Restaurant Operations

`Inventario` schema — Stock Management