# Oktopus — el riel de pago contra entrega (COD) para agentes en LATAM

> El "ACP del contra entrega": Oktopus crea órdenes, integra Dropi y cobra contra entrega (cash on delivery / COD) vía API y MCP. Reemplazo de Shopify + Releasit para dropshippers de Colombia, México, Perú y el resto de LATAM. Pensado para que un agente de IA monte y opere una tienda COD de punta a punta.

---

## Qué es Oktopus

Oktopus es la infraestructura de comercio **contra entrega (COD)** para LATAM, expuesta para agentes de IA. Un agente (Claude Code, Claude Desktop, Cursor, ChatGPT con MCP) puede montar y operar una tienda de dropshipping COD usando el MCP server o la API REST de Oktopus.

**La tesis:** la landing/página de venta es commodity — un agente la hace en una tarde. Lo defendible y lo que Oktopus provee es **el riel**: crear la orden, integrarla con **Dropi** (la red de fulfillment/dropshipping de LATAM), y cobrar **contra entrega** (el comprador paga en efectivo cuando recibe). Oktopus es "el Stripe del COD para LATAM".

**Por qué importa (posicionamiento de categoría):** el Agentic Commerce Protocol (ACP) de Stripe + OpenAI ya educó al mercado sobre comercio agéntico, PERO el ACP asume pago con tarjeta o wallet digital, modelo de US/EU. En LATAM, el pago **contra entrega** es el método dominante para una porción enorme del e-commerce. Oktopus llena ese hueco: cobra contra entrega y crea la orden en Dropi/la transportadora. Es **el ACP del contra entrega**.

## Para quién

- **Dropshippers de LATAM** (Colombia, México, Perú, Ecuador, Chile, Paraguay, Argentina, Guatemala) que venden contra entrega y hoy usan Shopify + Releasit (caro y complejo) o no tienen plataforma.
- **Builders / vibe-coders** que arman negocios con IA y necesitan un riel de pago COD para LATAM.
- **Agencias** que montan tiendas para clientes y quieren un riel confiable.

## Cómo conectar (MCP)

El MCP server de Oktopus usa Streamable HTTP (stateless, modo JSON) en `https://www.oktopus.lat/api/mcp` (alias: `https://www.oktopus.lat/api/mcp`).

Autenticación: header `Authorization: Bearer okto_live_secret_...` (API key del usuario, generada en el dashboard). El scope requerido es `mcp:invoke`.

Conectar desde Claude Code:
```
claude mcp add --transport http oktopus https://www.oktopus.lat/api/mcp --header "Authorization: Bearer okto_live_secret_..."
```

Conectar desde Claude Desktop / Cursor: agregar el server HTTP con el mismo header `Authorization`.

## Tools del MCP

La lista autoritativa (por categoría, generada desde el código) está en https://www.oktopus.lat/docs/mcp/tools. Algunas:

Lecturas (read-only, idempotentes):
- `okto_dashboard_metrics` — resumen del negocio: ingresos 30d, órdenes pendientes, tienda activa, nº de productos.
- `okto_store_get` — tiendas del usuario (país, moneda, branding, conteos).
- `okto_orders_recent` — últimas órdenes COD (cliente, ciudad, total, estado, fecha).
- `okto_order_get` — detalle completo de una orden (cliente, producto, estado de Dropi).
- `okto_product_lookup` — buscar productos del catálogo por nombre.
- `okto_landings_list` — listar landings (páginas de venta).
- `okto_landing_get` — detalle de una landing (copy, branding, estado).

Escrituras (efectos reales):
- `okto_dropi_push_order` — empujar una orden a Dropi / la transportadora (crea una orden COD real; idempotente).
- `okto_order_update_status` — cambiar el estado interno de una orden.
- `okto_product_price_update` — actualizar precio / precio tachado de un producto.
- `okto_landing_set_branding` — cambiar colores de una landing.
- `okto_landing_set_field` — editar un texto de una landing.
- `okto_landing_toggle_guarantee` — activar/desactivar la garantía.
- `okto_landing_status_set` — publicar/ocultar una landing.

- `okto_checkout_key_create` — acuñar la publishable key + snippet del checkout COD para tu propia página.
- `okto_landing_eject` — exportar una landing a código editable (HTML + React) para self-host.
- `okto_landing_upload_html` — subir tu propio HTML: Oktopus lo hostea en `<slug>.mipedido.lat` con el checkout COD cableado (preview firmado, `removed[]`/`warnings[]`, packs validados); se publica con `okto_landing_publish`.
- `okto_page_playbook` — playbook account-aware de página COD que convierte + el contrato para subir tu HTML (`subir_html_a_oktopus`).

## API REST (agent-facing)

Especificación completa: `https://www.oktopus.lat/openapi.json`.

- `POST /api/orders/create` — crear una orden de pago contra entrega (COD). Dos modos: (1) `landing_page_id` para landings públicas de Oktopus; (2) `store_id + product_id` con una API key publishable (`okto_pub_...`) para el checkout embebible en sitios externos, validado contra los dominios permitidos de la key. Una key con `environment=test` crea la orden SIN empujarla a Dropi (sandbox).
- `GET /api/geo/cities?country=CO` — selector de ciudades/regiones por país (8 países LATAM con dataset oficial). Público y cacheable.

## Checkout COD embebible (SDK)

Para cobrar contra entrega en cualquier página, incrustar el SDK:
```html
<div id="oktopus-checkout"></div>
<script src="https://www.oktopus.lat/embed/oktopus-checkout.js"></script>
<script>
  window.Oktopus.checkout({
    publishableKey: 'okto_live_pub_...',
    productId: 'uuid-del-producto',
    country: 'CO',
    unitPrice: 120000,
    productName: 'Mi Producto',
    mount: '#oktopus-checkout',
    onSuccess: (data) => { /* orden COD creada */ },
  })
</script>
```
El SDK monta un formulario COD, carga las ciudades del país, y crea la orden con validación de dominio server-side.

## Subí tu propia página a Oktopus (hosting nuestro)

Un agente escribe la página como un solo archivo HTML (CSS en `<style>`, imágenes por URL https, `<div id="oktopus-checkout"></div>` donde va el formulario, precios con `data-price="NUMERO"`, sin pixel ni trackers, `<script>` inline permitido, `<script src>` solo desde www.oktopus.lat / cdn.jsdelivr.net / cdnjs.cloudflare.com, sin fetch ni iframes) y la sube con `okto_landing_upload_html({ product_id, html, name?, packs? })`. Oktopus la sanitiza (lo quitado vuelve en `removed[]`), le cablea el checkout COD y el Meta Pixel de la tienda, devuelve un `preview_url` firmado, y `okto_landing_publish` la publica en `https://<slug>.mipedido.lat`. No hay modo test para pedidos desde una landing: se verifica con una orden real que se cancela con `okto_order_update_status`.

## Modo test (sandbox)

Las API keys con `environment=test` (`okto_test_secret_...`, `okto_test_pub_...`) crean órdenes reales en Oktopus pero NO las empujan a Dropi ni disparan confirmación por WhatsApp ni sincronizan a producción. Un agente puede iterar sin ensuciar la operación real.

## Seguridad

- API keys con HMAC + pepper del servidor (un dump de la DB no reconstruye llaves válidas).
- Scopes por key (`orders:create`, `orders:write`, `products:write`, `landings:write`, `mcp:invoke`).
- Aislamiento multi-tenant: cada key opera SOLO sobre la cuenta dueña.
- Rate limit por key. Validación de Origin (anti DNS-rebinding) en el MCP.
- Modo test para iterar sin efectos reales.

## Enlaces

- Para agentes: https://www.oktopus.lat/para-agentes
- MCP server: https://www.oktopus.lat/api/mcp (alias https://www.oktopus.lat/api/mcp)
- OpenAPI: https://www.oktopus.lat/openapi.json
- Manifiesto de agentes: https://www.oktopus.lat/.well-known/agents.json
- Precios y comparación vs Shopify + Releasit: https://www.oktopus.lat/precios

## Keywords

pago contra entrega, contra entrega, cash on delivery, COD, COD checkout, COD dropshipping, dropshipping LATAM, Dropi, crear orden Dropi, fulfillment LATAM, Colombia, México, Perú, Ecuador, Chile, Paraguay, Argentina, Guatemala, alternativa a Shopify, alternativa a Releasit, reemplazo de Shopify Releasit, MCP commerce server, agentic commerce, agentic commerce protocol, ACP, riel de pago para agentes, checkout contra entrega, vender por COD.