Skip to content
Destesi Docs

Ask AI

Ask anything about Destesi — setup, products, APIs.

Powered by Claude. Answers may be wrong — always verify against the docs.

Commerce reference

The Commerce API is workspace-scoped and lives at https://api.commerce.destesi.io.

Authentication

Section titled “Authentication”

Two ways in, checked in this order:

Terminal window
# 1. Personal access token — requires the workspace header
curl https://api.commerce.destesi.io/v1/products \
  -H "Authorization: Bearer idn_pat_xxxxxxxx" \
  -H "X-Destesi-Workspace: your-workspace-slug"
Terminal window
# 2. Session cookie — what the web app uses
curl https://api.commerce.destesi.io/v1/products \
  -H "Cookie: commerce_session=..."

Mint a token from your account. Notes that bite:

  • The workspace header is required with a token. Without X-Destesi-Workspace, the request is rejected — a token by itself doesn’t say which workspace you mean.
  • A malformed bearer is rejected outright. Authorization: Bearer something-else returns 401 unknown_bearer_scheme; it does not fall back to the cookie.
  • The session cookie is host-only on the API subdomain and lasts 30 days.

Errors are always JSON: {"error":"<code>"}, sometimes with a detail field.

Endpoint groups

Section titled “Endpoint groups”
Group Representative routes
Catalog `GET
Orders `GET
Logistics /v1/orders/{id}/address, /shipment, /quote, /select-rate, /buy-label, /mark-shipped, /mark-delivered, /v1/shipping/origin, /v1/shipping/carriers, /v1/dispatch-queue
Customers /v1/conversations, /v1/conversations/{id}, follow-up drafts
Campaigns /v1/campaigns, /v1/campaigns/{id}/ads, /publish, /boost, /insights, /v1/strategies
Operator chat POST /v1/chat, POST /v1/chat/resume, /v1/chat/conversations, /v1/chat/uploads
Settings /v1/settings/profile, /v1/settings/payments, /v1/settings/shipping, /v1/payments/status, /v1/setup/readiness
Notifications /v1/notifications

Everything above requires authentication and is scoped to your workspace. An id belonging to another workspace returns 404 — never a 403, which would confirm the id exists.

Public endpoints

Section titled “Public endpoints”

These are deliberately outside the session/token check, because the caller is a payment provider, a carrier, or a buyer holding a link.

Route Who calls it
POST /v1/webhooks/wompi Wompi, on a payment event. Signature-verified and idempotent.
POST /v1/webhooks/skydropx The carrier, on a tracking event.
GET /v1/storefront/products/{id} A buyer opening a product link.
POST /v1/storefront/checkout/{order,shipping,pay} A buyer completing a checkout link, authorized by the opaque code in the link.
`GET POST /v1/storefront/bodega/{token}`

Order states

Section titled “Order states”
State Terminal Can move to
draft no pending_payment, cancelled
pending_payment no paid, payment_failed, cod_pending, expired, cancelled
cod_pending no paid, cancelled
payment_failed no pending_payment, cancelled
paid no fulfilled
fulfilled yes —
cancelled yes —
expired yes —

Any other move returns 409 illegal_transition. Orders in draft, pending_payment, and payment_failed still hold their reserved stock.

Plan limits

Section titled “Plan limits”
Free Pro Team
Sales channels 1 3 All
Products (SKUs) 100 2,500 10,000
Sales-agent turns per month 10 100 300
Generated images per month 5 100 500
Campaign publishes per month 5 100 500

Orders and sales volume are measured but are neither capped nor charged for. When the agent-turn allowance runs out, buyers get one message telling them a person will follow up and the conversation is routed to you — it does not go silent. See Plans and billing.

Settings that change behaviour

Section titled “Settings that change behaviour”
Setting Effect
Payment mode Resolved automatically in precedence order: your own Wompi account → Destesi’s account (only if granted) → bank transfer → cash on delivery → disabled. GET /v1/payments/status reports the active one.
Warehouse origin Required before any shipping quote. Missing → quotes are refused.
Product weight Required per product for a quote. Missing → 422 weight_incomplete.
Reservation window 30 minutes by default; can be set per order at creation.
Bre-B llave Adds a scannable QR to the bank-transfer instructions.

Connected services

Section titled “Connected services”

Commerce reads every third-party credential from Connect — it stores none of its own.

Provider Enables Without it
WhatsApp The buyer-facing sales agent, inbound and outbound Replies are composed and stored but never delivered
Meta Ads Publishing and measuring campaigns 422 meta_settings_not_set
Skydropx Quotes, labels, tracking, cash on delivery 503 carrier_disabled
Wompi Card and PSE payment links Falls through to bank transfer or cash on delivery
Gmail Automatic bank-transfer confirmation Falls back to asking you on WhatsApp
OpenAI Generating product imagery from a reference photo openai_not_connected
Section titled “Related”