Changelog

​

Cambio de contrato: un pedido puede llegar sin dirección de entrega

• payment_terms: paid_pending_review — el cliente envió el comprobante y la tienda todavía no lo revisó. Trátalo como no pagado hasta que cambie.
• status de producto en las respuestas: unpublished. Crear o editar un producto sigue aceptando sólo published.

​

Un envío que la cuenta no puede pagar ahora responde 402

• insufficient_funds — la cuenta se quedó sin saldo para mensajes salientes.
• wallet_sends_paused — los envíos se cortaron cuando el saldo se acabó.
• wallet_currency_mismatch — el saldo está en una moneda que esta API no puede cotizar. Reintentar no cambia nada; escríbenos.

​

Las plantillas con variables por nombre ya se pueden enviar

• El catálogo publica las claves reales. required_variables lista posiciones (["1", "2"]) o nombres (["name"]) según cómo se creó la plantilla, y un nuevo campo sendable marca la plantilla que mezcla ambos estilos, que no se puede enviar por esta vía.
• variables acepta las mismas claves. {"name": "Ronald"} sale como parámetro nombrado.
• Un envío que el proveedor rechazaría se rechaza antes con 422. Una clave que falta, una que sobra o una posición sobre una plantilla nombrada ya no producen un 202 vacío; el mensaje nombra las claves que la plantilla espera.

​

El carrito abandonado ahora se ve y se apaga desde el panel

• Historial de envíos. Lista los envíos del comercio, del más reciente al más antiguo, con el estado de cada uno, dentro de la ventana de retención de 30 días. Ya no hace falta saber de antemano qué event_id buscar.
• Interruptor de encendido y apagado. El envío se puede apagar y volver a encender sin tocar la integración. Apagarlo no borra nada: el historial sigue ahí.

​

Enviar ya no espera 10 segundos

• El envío aceptado responde 202, no 200. Si tu integración trata sólo el 200 como éxito, empezaría a leer envíos buenos como fallos. Acepta cualquier 2xx. El 200 queda para las respuestas que no producen un envío nuevo: un event_id repetido y un envío descartado (stale, paused).
• El estado de un envío nuevo es accepted, no in_progress. Significan lo mismo — “va en camino, todavía no sabemos cómo terminó” — y el desenlace se sigue consultando en GET /v1/template-messages/{event_id}, que es el único camino: ningún webhook reporta el resultado de un envío. in_progress sigue siendo un valor válido del contrato: los envíos hechos antes de este cambio lo devuelven mientras sigan dentro de la ventana de retención de 30 días.
• La modalidad de acuse rápido por cuenta desaparece, porque ahora es el comportamiento de todos. No hay nada que solicitar ni que configurar.

​

El estado de un envío ahora dice cómo terminó

• Los cuatro estados ya llegan. Si tu integración asumía que in_progress era el final del camino, ahora vas a ver sent, delivered, read y failed. Ramifica sobre status.
• status_detail en un failed no es una lista cerrada y puede faltar. Además de account_not_eligible y no_sender_number, ahora puede traer send_failed cuando el envío no llegó a completarse, send_cancelled cuando se canceló antes de intentarse, o provider_error_<código> con el código de Meta cuando el proveedor rechazó la entrega con uno — por ejemplo provider_error_131049, el tope de frecuencia de plantillas de marketing. Ese catálogo cambia sin que nos avisen: no lo trates de forma exhaustiva, registra el valor y cae a un fallo genérico si no lo reconoces o si viene vacío.
• updated_at es cuándo cambió por última vez el registro del envío, no cuándo consultaste. Consultar ya no lo mueve, pero sí puede moverse sin que el estado cambie, así que no sirve como marca de agua: reconcilia por event_id.

​

GET /v1/templates lee el catálogo del que realmente se envía

• language ya no puede venir vacío. Antes te decíamos que, si la plantilla no tenía idioma registrado, cualquier código pasaba la validación. Ese caso ya no existe: el catálogo registra el idioma siempre, así que un idioma que no coincide es 422, sin excepción. Si dependías de ese escape, manda el código que devuelve la lista.
• category ahora llega en minúsculas — marketing, no MARKETING. Si comparas el string tal cual, ajústalo.
• Tu lista puede cambiar de tamaño, incluso a vacía. Las plantillas viven en el catálogo del riel de envío, y se llenan cuando tu cuenta sincroniza con WhatsApp. Una lista vacía significa que hoy todo envío se rechaza: escríbenos y la sincronizamos.

​

Los rechazos de un envío ahora dicen qué pasó

• Cuenta no habilitada para enviar → 422 con "type": "account_not_eligible" en detail[0]. No es transitorio: escríbenos para habilitarla.
• Sin número remitente conectado → 422 con "type": "no_sender_number". Conecta el número de WhatsApp de tu cuenta y reintenta.
• Conversación en pausa → 200 con "status": "discarded" y "status_detail": "paused". La petición funcionó; el envío está apagado a propósito, porque un agente humano tomó la conversación o hay un corte por facturación.
• event_id ya atado a otro mensaje, o fuera de la ventana de idempotencia → 409 con "type": "idempotency_conflict". Manda el evento con un event_id nuevo: repetir el mismo devuelve el mismo 409.

​

El envío outbound ya se dirige por entorno

​

Lista de plantillas aprobadas

• name — el valor que va en template.name.
• language — el valor que va en template.language. Puede venir vacío: la plantilla no tiene idioma registrado, pero el envío igual exige un código, así que no mandes el null tal cual — el request lo rechaza con 422. Solo en ese caso cualquier código pasa la validación; si la plantilla sí registra idioma y no coincide, también es 422. El código viaja tal cual a WhatsApp, así que si te equivocas de idioma el envío falla allá — y hoy eso no se ve desde aquí: el estado se queda en in_progress.
• required_variables — las claves que tienen que estar en variables. "1" llena {{1}}. Una lista vacía significa que la plantilla no lleva variables.
• category y display_name — este último es null salvo que difiera del name, para reconocerla desde tu lado. La clave siempre viene: comprueba el valor, no su presencia.

​

Corrección del contrato de Mensajes de Plantilla

• La ruta es POST /v1/template-messages, y el estado se consulta en GET /v1/template-messages/{event_id}.
• La plantilla viaja en el request, como template: {name, language}. La versión anterior decía lo contrario: que quedaba fijada de nuestro lado.
• template_variables ahora se llama variables.
• first_name, last_name y second_last_name no existen. Este endpoint no crea ni actualiza el contacto, y hoy ninguna llamada pública lo hace: la API de Contactos es de solo lectura.
• occurred_at es opcional. Si lo omites, el aviso nunca se considera vencido.
• Nuevo campo opcional metadata.use_case para atribuir el envío a un caso de uso.
• Alcances requeridos: outbound:send y outbound:read.

​

Conversaciones, contactos, perfil de empresa y conteo de pedidos

• Conversaciones: Lista las conversaciones del comercio (GET /v1/conversations, con filtro sale_status) y los mensajes de una conversación (GET /v1/conversations/{conversation_id}/messages). Leer mensajes por la API nunca los marca como leídos.
• Contactos: Lista los contactos del comercio con sus tags, estado de opt-in y metadata (GET /v1/contacts).
• Empresa: Perfil público de la empresa (GET /v1/company).
• Conteo de pedidos: Total de pedidos y desglose por estado (GET /v1/orders/counts).

​

Vouchers de pago, resumen de conversación y fix de media

• Vouchers de pago: Nuevo campo payment_receipt_urls en las respuestas de pedidos. Contiene la lista de URLs de las imágenes de comprobantes de pago subidos por el cliente (Yape, Plin, transferencia, etc.). Si hay múltiples vouchers, todos se incluyen.
• Resumen de conversación: Nuevo campo summary_conversation en las respuestas de pedidos. Contiene un resumen generado por IA con los detalles del pedido y preferencias del cliente, evitando tener que entrar a la conversación.
• Fix media de variante: Crear una imagen de variante sin el campo title ya no retorna error. El campo es opcional tal como está documentado.

​

Webhooks, zonas horarias y SKU

• Webhooks: Recibe eventos de pedidos en tiempo real (order.created, order.status_changed). CRUD completo en /v1/webhooks. Firma HMAC-SHA256 en cada entrega.
• Zonas horarias: Todas las fechas (order_date, created_at) ahora se devuelven en la zona horaria local del comercio. Header X-Timezone incluido en cada respuesta.
• SKU: Nuevo campo sku en variantes de productos y en items de pedidos.
• Variant ID: Nuevo campo variant_id en items de pedidos para identificar la variante interna.

​

Gestión completa de productos

• Productos: Crear, actualizar y eliminar productos (POST, PATCH, DELETE /v1/products)
• Variantes: CRUD completo de variantes por producto
• Opciones y valores: Gestión de opciones y sus valores por producto
• Media: Subida, actualización y eliminación de media por variante
• Categorías: Crear, actualizar, eliminar categorías y asignarlas a productos
• Catálogos: Listado de catálogos disponibles (GET /v1/catalogs)

​

Lanzamiento de la Business API

• Pedidos: Listado y detalle de pedidos (GET /v1/orders, GET /v1/orders/{order_id})
• Productos: Consulta de productos (GET /v1/products, GET /v1/products/{product_id})
• Autenticación: API Keys con header X-API-Key
• Rate Limiting: Control de tasa de peticiones por API Key
• Paginación: Paginación basada en cursor para todos los listados