Referencia de recursos de la API v1
La URL base habitual es https://app.synvaxis.com/api/v1. Todos los ejemplos requieren una clave Bearer. Los campos pueden tener valores nulos según el registro; no presupongas que todos los datos de contacto estén completos.
Operaciones disponibles
| Método | Ruta | Alcance | Resultado |
|---|---|---|---|
| GET | /_meta | read | Identidad, permiso y plan de la clave. |
| GET | /contacts | read | Listado de contactos. |
| POST | /contacts | write | Nuevo contacto. |
| GET | /conversations | read | Listado de conversaciones. |
| GET | /conversations/{id} | read | Una conversación. |
| GET | /messages | read | Mensajes de una conversación. |
| GET | /orders | read | Listado de pedidos. |
| GET | /orders/{id} | read | Un pedido. |
| GET | /products | read | Listado de productos. |
| GET | /products/{id} | read | Un producto. |
| GET | /appointments | read | Listado de citas. |
| GET | /appointments/{id} | read | Una cita. |
Las rutas de esta tabla se añaden a /api/v1. Sustituye {id} por el identificador real. Descarga el contrato OpenAPI para ver parámetros y respuestas por operación.
Contactos
GET /contacts admite limit y cursor. Los registros incluyen id, phone, name, status, last_interaction, total_orders y created_at.
POST /contacts recibe phone como texto obligatorio de al menos cinco caracteres y name opcional. Si name está vacío se usa “Desconocido”. Envía el teléfono con código de país para evitar ambigüedades.
curl --fail-with-body -X POST "https://app.synvaxis.com/api/v1/contacts" \
-H "Authorization: Bearer $SYNVAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{"phone":"+12025550123","name":"Contacto de prueba"}'
El número es ilustrativo: reemplázalo por un contacto de prueba autorizado. La creación devuelve 201 y el objeto creado directamente. Un teléfono duplicado puede devolver 409. La operación no envía mensajes.
Conversaciones
GET /conversations admite platform e is_bot_active, además de paginación. Usa true o false para is_bot_active. platform compara el valor almacenado del canal, por ejemplo whatsapp, messenger, instagram, telegram o web.
El listado y detalle incluyen id, contact_phone, contact_name, platform, channel_phone_id, is_bot_active, last_message_at, last_message_content, last_message_role, unread_count, handoff_active, handoff_reason, meta_campaign_id y created_at. Se excluyen conversaciones eliminadas.
Mensajes
GET /messages requiere conversation_id y admite limit y cursor. Se comprueba que la conversación pertenezca a la cuenta de la clave.
Los registros incluyen id, conversation_id, role, content, is_bot, platform_message_id, payload y created_at. payload puede variar por canal y tipo de mensaje. Revisa la limitación de paginación de mensajes antes de construir exportaciones históricas.
Pedidos
GET /orders filtra por status, payment_status y conversation_id. Los campos de listado y detalle son id, platform, external_id, status, payment_status, customer_phone, customer_name, total, currency, conversation_id, created_at y updated_at.
No se devuelve aquí una colección de líneas de pedido. Tampoco existe una escritura pública de pedidos en esta versión.
Productos
GET /products admite is_active=true o false. El listado y detalle incluyen id, name, sku, price, price_min, price_max, pricing_type, description, category, item_type, inventory_quantity, is_active, add_ons, knowledge_base, variants, faqs, created_at, updated_at, sale_price, sale_label, sale_ends_at y el valor calculado sale_active.
Interpreta el precio junto con pricing_type, variantes y vigencia de oferta. No presupongas que price por sí solo sea una cotización final.
Citas
GET /appointments admite status, from y to. from incluye citas cuyo start_time sea mayor o igual; to excluye las que empiecen en ese instante o después. Envía fechas ISO con zona horaria.
Los campos son id, conversation_id, customer_name, customer_phone, customer_email, start_time, end_time, status, meeting_link, notes y created_at.
Respuestas
Los listados usan data y next_cursor. Los detalles devuelven el objeto directamente. Las rutas de detalle responden 404 cuando no encuentran un recurso de la cuenta. Consulta errores de API para validación, autenticación, permisos y límites.