API REST de Cashod: envía pedidos contra entrega desde cualquier tienda, CRM o agente de IA

Si tus pedidos llegan desde una herramienta que Cashod no conecta de forma nativa (una tienda a medida, un CRM, un creador de landing pages o un agente de IA), la API REST pública de Cashod permite que esa herramienta cree pedidos contra entrega, lea su estado de entrega y su número de seguimiento, y mantenga sincronizados productos y stock. Creas una clave por tienda en Configuración → Desarrolladores, envías POST /v1/orders con tu propio external_id para que los reintentos nunca creen duplicados y consultas el pedido para seguir su entrega. Guías completas y referencia interactiva en el portal de desarrolladores.

API, integración nativa, webhook o Google Sheets: ¿cuál usar?

Cashod recibe pedidos de cuatro formas. Elige la más ligera que te sirva:

• Integraciones nativas: Shopify, YouCan, WooCommerce, LightFunnels, Storeep y xPage. Si tu tienda funciona con alguna de ellas, conéctala desde Integraciones sin escribir código. Ejemplo: la integración con Shopify.
• Webhook entrante: tu formulario o herramienta envía cada pedido nuevo a una URL de webhook de Cashod. Ideal cuando la herramienta puede enviar el pedido y no necesitas nada de vuelta. Detalles en la página del webhook.
• Importación desde Google Sheets: para equipos que aún recogen pedidos en una hoja de cálculo.
• API REST pública: cuando necesitas comunicación en ambos sentidos: crear pedidos, leer estado y seguimiento, crear o actualizar productos por SKU y actualizar stock. Es la opción para desarrolladores, agencias que trabajan para varios comerciantes y agentes de IA.

¿Cómo funcionan las claves de API y los scopes?

Cada petición lleva la cabecera Authorization: Bearer csk_live_…. Las claves se crean por tienda en Configuración → Desarrolladores. Una clave se muestra una sola vez, al crearla, y Cashod solo guarda un hash de ella, así que cópiala directamente a tu gestor de secretos.

Cada clave recibe solo los scopes que necesita:

• orders:read y orders:write: listar, leer y crear pedidos.
• products:read y products:write: listar, leer y crear o actualizar productos.
• stock:write: actualizar el stock de una variante.

Un scope de escritura incluye la lectura correspondiente. Una landing page que solo crea pedidos necesita orders:write y nada más; un script de almacén que solo envía stock necesita stock:write. Las agencias deberían crear una clave por tienda cliente: revocar a un cliente nunca afecta a los demás.

¿Cómo crear un pedido contra entrega sin duplicados?

Envía POST /v1/orders con un cuerpo JSON. Los campos principales son:

• external_id: tu propio identificador del pedido (muy recomendable, ver abajo).
• customer: nombre y teléfono. El teléfono puede ir en cualquier formato; Cashod lo normaliza.
• shipping: dirección, ciudad y un teléfono de entrega opcional.
• items: cada uno con una cantidad y uno de estos: sku, product_id o un name libre (con precio unitario) para un artículo fuera del catálogo.
• Opcionales: total o discount, notes para el agente de confirmación, source_name para tus propios informes, scheduled_for para una fecha de vencimiento, y confirmed.

Por defecto, el pedido nuevo entra en la cola de confirmación como cualquier otro, y tu call center o tu agente de IA lo confirma. Pon confirmed en true solo si ya confirmaste el pedido con el cliente tú mismo.

Reintentos seguros con external_id

Sin idempotencia, una petición reenviada puede convertirse en un segundo pedido real entregado a un repartidor real. Con external_id, la primera llamada devuelve 201 (creado) y cualquier reintento con el mismo identificador devuelve 200 con el pedido que ya existe. Tu código puede reintentar sin riesgo.

¿Cómo leer el estado de entrega y el seguimiento?

GET /v1/orders/:id devuelve el pedido con su estado de envío, estado de confirmación, empresa de mensajería, tracking_number, importes (incluidos el anticipo y el importe contra entrega por cobrar) y marcas de tiempo como el envío y la entrega. GET /v1/orders lista pedidos con filtros por estado de envío, estado de confirmación y fecha de creación: así devuelves los estados a un CRM o se los muestras a tu cliente.

La API no envía webhooks salientes, así que la sincronización de estados es una tarea de polling: por ejemplo, listar cada pocos minutos los pedidos del periodo que te interesa y escribir los cambios en tu sistema.

¿Cómo sincronizar productos y stock?

• POST /v1/products hace upsert por SKU: la misma llamada crea el producto la primera vez y lo actualiza después. Las variantes también se emparejan por SKU; una variante que no envíes queda intacta, no se borra.
• GET /v1/products y GET /v1/products/:id leen el catálogo, con filtros por SKU, nombre y estado activo.
• PATCH /v1/products/:id/variants/:variantId/stock fija el nivel de stock. Es un valor absoluto, no un delta, así que una llamada repetida no puede contar dos veces.

Paginación, límites de peticiones y errores

• Paginación: los listados usan cursores. Cada página devuelve data, has_more y next_cursor; vuelve a enviar el cursor para obtener la página siguiente (hasta 100 elementos por página).
• Límite de peticiones: 120 por minuto por clave. Si lo superas recibes HTTP 429: espera y reintenta.
• Errores: siempre con la misma forma, un objeto error con un type (como invalid_request, authentication_error, permission_error, not_found, rate_limit_exceeded o server_error) y un message legible.

¿Un agente de IA debe usar la API o el servidor MCP?

Depende de para quién trabaje el agente:

• Tu propio agente o automatización (un bot de ventas en tu landing page, un agente que toma pedidos en tu CRM) usa la API REST con una clave de scopes limitados. Actúa para una sola tienda, con exactamente los permisos que diste a esa clave. La especificación OpenAPI en https://api.cashod.ma/api/v1/openapi.json facilita convertir los endpoints en herramientas para el agente.
• Un asistente de IA que usa una persona pasa por el servidor MCP de Cashod en https://mcp.cashod.ma/mcp. Funciona con asistentes de IA que admiten conectores MCP, como Claude y ChatGPT. El acceso es por OAuth: el usuario inicia sesión con su cuenta de Cashod y aprueba el acceso, y el asistente actúa con los permisos habituales de ese usuario en sus tiendas. Los pasos están en Configuración → Chat con IA. Más información sobre la IA en Cashod.

¿Puede Cashod enviar eventos a tu sistema?

No desde la API. Para enviar eventos hacia fuera, usa Workflows: un workflow puede llamar a cualquier URL con su acción de webhook, y también publicar en Slack o Discord, enviar un correo, un SMS o un mensaje de WhatsApp.

Checklist antes de salir a producción

1. Crea una clave por tienda con el mínimo de scopes y guárdala solo en el servidor.
2. Envía un external_id en cada pedido y trata tanto 201 como 200 como éxito.
3. Usa SKU que coincidan con tu catálogo de Cashod, o haz primero el upsert de los productos.
4. Deja confirmed desactivado salvo que de verdad hayas confirmado con el cliente.
5. Gestiona el 429 con espera progresiva y lee el campo error.type.
6. Sigue next_cursor hasta que has_more sea false.
7. Programa una tarea de polling para estados y seguimiento, o un webhook de workflow para eventos.
8. Prueba el recorrido completo con un pedido real: crear, confirmar, enviar y leer el número de seguimiento.

Preguntas frecuentes

¿La API de Cashod envía webhooks?

No. Lee los estados con peticiones GET, o usa la acción de webhook de un Workflow para llamar a tu URL.

Gestiono varias tiendas. ¿Necesito varias claves?

Sí. Las claves son por tienda, lo que separa los datos y los accesos de cada una.

¿Dónde está la referencia completa?

En el portal de desarrolladores, con guías, una referencia interactiva y la especificación OpenAPI.

Empieza ahora

Abre la documentación para desarrolladores, crea tu primera clave en Configuración → Desarrolladores y envía un pedido de prueba. Para elegir un plan según el número de tiendas y pedidos mensuales, consulta los precios.