Organización

La Organización es la unidad principal de aislamiento. Cada API key pertenece a una organización; cada usuario miembro tiene un rol (owner, admin, member, operator, accountant). Toda data está aislada por organization_id con RLS en Postgres.

Marketplace

Un Marketplace es una conexión a una cuenta externa (Mercado Libre, Amazon, Walmart, Shopify, Coppel, Elektra). Una organización puede tener varios. La cantidad incluida varía por plan; se pueden comprar add-ons.

Campos clave:

slug: mercado_libre, amazon, walmart, shopify, coppel, elektra.
display_name: el nombre que tú le pusiste (ej. "Tienda principal").
external_seller_id: ID del seller en el marketplace upstream.
status: connected, disconnected, token_expired, error.

Pedido (Order)

Un Pedido es una transacción comercial. Pertenece a un marketplace y a una organización. Campos clave:

id: ID externo del marketplace (no normalizado).
marketplace: slug del marketplace de origen.
status: status raw del marketplace.
category: categoría normalizada (CREADA, PROCESANDO, ENVIADA, ENTREGADA, CANCELADA, REEMBOLSO). Igual entre marketplaces.
total, currency: total cobrado al comprador.
date_created: cuándo se creó.
date_closed: cuándo se cerró (pago confirmado). Útil para reportes financieros.
last_updated: cualquier cambio actualiza este campo. Úsalo para delta-sync.
items, shipments, payments, buyer: objetos relacionados.

Item / Publicación

Un Item representa una publicación en un marketplace. Campos clave:external_item_id, title, sku, price, stock, tags, condition. Sincronizamos el catálogo completo de cada marketplace conectado.

Envío (Shipment)

Un envío puede ser interno (manejado por el marketplace, ej. ML Flex / Walmart Fulfillment) o externo (paquetería propia como Paquetexpress o Zipnova). Tiene tracking_number, carrier, status, estimated_delivery.

Devolución (Return)

Cubre claims de Mercado Libre y returns de Walmart. Estructura unificada con external_return_id, order_id, status, reason, líneas de devolución.

CFDI (factura SAT)

Documento fiscal mexicano. Cubrimos emisión (vía PAC InvoiceOne) y descarga masiva (vía e.firma del SAT). Tipos: ingreso, egreso, traslado, pago, retención, nómina. Identificado por uuid (folio fiscal).