{"openapi":"3.1.0","info":{"title":"Atenta · API pública","version":"1.0.0","license":{"name":"Uso bajo los términos de Atenta","url":"https://atenta.mx/terminos"},"summary":"La atención por WhatsApp de tu negocio, abierta a tus herramientas.","description":"Un token por negocio (`atk_<slug>_…`, se genera en Ajustes → Integraciones de la app). Misma semántica que la app: cada ruta es una ruta del negocio y el token acota qué puede tocar (permisos). Además de las rutas documentadas aquí, cualquier ruta del negocio de solo lectura o de escritura permitida funciona en `/v1/<ruta>` con las mismas reglas; lo que solo se hace desde la app (aprobar la base, encender, cobrar el plan, campañas, borrar) responde 403 `solo_desde_la_app`. Límite: 120 llamadas por minuto por token. Los teléfonos de los clientes llegan redactados.","contact":{"name":"Kalia Code","url":"https://atenta.mx"}},"servers":[{"url":"https://api.atenta.mx"}],"tags":[{"name":"chats","description":"Conversaciones de WhatsApp"},{"name":"pedidos","description":"Pedidos"},{"name":"citas","description":"Citas y disponibilidad"},{"name":"clientes","description":"CRM"},{"name":"finanzas","description":"Monedero, créditos, cobranza, links de pago"},{"name":"reporte","description":"Reporte del mes"},{"name":"base","description":"Base de respuestas"},{"name":"menu","description":"Menú"},{"name":"menu_dia","description":"Menú del día"},{"name":"llamadas","description":"Llamadas con IA"},{"name":"webhooks","description":"Webhooks salientes"},{"name":"token","description":"El token"},{"name":"partner","description":"Partner tokens (integradores)"}],"paths":{"/v1/conversaciones":{"get":{"operationId":"chats_listar","summary":"atenta.chats.listar","description":"Lista las conversaciones de WhatsApp del negocio (fijadas primero, luego las que te necesitan, luego por actividad). Filtros: todas | te_necesitan | tu_al_mando | sin_leer | pedidos | resueltas | archivadas; q busca por nombre, teléfono (≥4 dígitos) o texto. Permiso: leer_chats.","tags":["chats"],"security":[{"token":[]}],"parameters":[{"name":"filtro","in":"query","required":false,"schema":{"description":"Qué conversaciones (por defecto todas)","type":"string","enum":["todas","te_necesitan","tu_al_mando","sin_leer","pedidos","resueltas","archivadas"]},"description":"Qué conversaciones (por defecto todas)"},{"name":"q","in":"query","required":false,"schema":{"description":"Búsqueda","type":"string","maxLength":80},"description":"Búsqueda"},{"name":"limite","in":"query","required":false,"schema":{"description":"Máximo (por defecto 50)","type":"integer","minimum":1,"maximum":100},"description":"Máximo (por defecto 50)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/conversaciones/{id}":{"get":{"operationId":"chats_leer","summary":"atenta.chats.leer","description":"Lee una conversación completa (mensajes con autor cliente | atenta | persona, estado ✓/✓✓, tipo, media). Marca los mensajes como leídos. Permiso: leer_chats.","tags":["chats"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":5,"maxLength":40,"description":"Id de la conversación (el wa_id del cliente, como lo devuelve chats.listar)"},"description":"Id de la conversación (el wa_id del cliente, como lo devuelve chats.listar)"},{"name":"desde","in":"query","required":false,"schema":{"description":"ISO: solo mensajes posteriores","type":"string"},"description":"ISO: solo mensajes posteriores"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/conversaciones/{id}/mensajes":{"post":{"operationId":"chats_escribir","summary":"atenta.chats.escribir","description":"Manda un mensaje al cliente en esa conversación como persona del negocio (o guarda una nota interna que el cliente no ve). Fuera de la ventana de 24 h de WhatsApp responde 409 fuera_de_ventana: entonces usa una plantilla aprobada. En un negocio de prueba solo llega a sus números de prueba. Permiso: escribir_chats.","tags":["chats"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":5,"maxLength":40,"description":"Id de la conversación"},"description":"Id de la conversación"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"texto":{"description":"Texto para el cliente","type":"string","minLength":1,"maxLength":4000},"nota":{"description":"Nota interna (no sale al cliente)","type":"string","minLength":1,"maxLength":4000},"plantilla":{"description":"Plantilla aprobada de Meta, para escribir fuera de la ventana de 24 h","type":"object","properties":{"nombre":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}}},"required":["nombre"]}},"required":[],"additionalProperties":false}}}}}},"/v1/conversaciones/{id}/control":{"post":{"operationId":"chats_tomar_control","summary":"atenta.chats.tomar_control","description":"Toma el control de la conversación: Atenta deja de contestar y una persona sigue desde aquí. Permiso: escribir_chats.","tags":["chats"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":5,"maxLength":40,"description":"Id de la conversación"},"description":"Id de la conversación"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["modo"],"properties":{"modo":{"type":"string","enum":["persona","atenta"],"description":"persona = una persona toma el control; atenta = se lo devuelve"}}}}}}}},"/v1/crm/pedidos":{"get":{"operationId":"pedidos_listar","summary":"atenta.pedidos.listar","description":"Lista pedidos del negocio (con cliente, items, total, estado y pago). Permiso: pedidos.","tags":["pedidos"],"security":[{"token":[]}],"parameters":[{"name":"estado","in":"query","required":false,"schema":{"type":"string","enum":["nuevo","confirmado","preparando","en_camino","entregado","cancelado"]}},{"name":"cliente","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Solo los de este cliente"},"description":"Solo los de este cliente"},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/crm/clientes/{cliente_id}/pedidos":{"post":{"operationId":"pedidos_crear","summary":"atenta.pedidos.crear","description":"Crea un pedido para un cliente (items con nombre, cantidad y precio; el total se calcula si no viene). Permiso: pedidos.","tags":["pedidos"],"security":[{"token":[]}],"parameters":[{"name":"cliente_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del cliente (clientes.buscar)"},"description":"Id del cliente (clientes.buscar)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1},"cantidad":{"default":1,"type":"number","exclusiveMinimum":0},"precio":{"type":"number","minimum":0}},"required":["nombre"]}},"total":{"type":"number","minimum":0},"direccion":{"type":"string","maxLength":300},"notas":{"type":"string","maxLength":1000},"estado":{"type":"string","enum":["nuevo","confirmado"]}},"required":["items"],"additionalProperties":false}}}}}},"/v1/crm/pedidos/{id}":{"put":{"operationId":"pedidos_actualizar","summary":"atenta.pedidos.actualizar","description":"Cambia el estado o las notas de un pedido (nuevo → confirmado → en_camino → entregado; o cancelado). Permiso: pedidos.","tags":["pedidos"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del pedido"},"description":"Id del pedido"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"estado":{"type":"string","enum":["nuevo","confirmado","preparando","en_camino","entregado","cancelado"]},"notas":{"type":"string","maxLength":1000}},"required":[],"additionalProperties":false}}}}}},"/v1/pedidos/{id}/pagar":{"post":{"operationId":"pedidos_cobrar","summary":"atenta.pedidos.cobrar","description":"Registra el pago de un pedido (efectivo, transferencia, monedero del cliente o link de pago). Con monedero descuenta saldo (409 saldo_insuficiente si no alcanza). Permiso: finanzas.","tags":["pedidos"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del pedido"},"description":"Id del pedido"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metodo":{"type":"string","enum":["efectivo","transferencia","wallet","link"]},"monto":{"description":"Parcial; por defecto el total","type":"number","exclusiveMinimum":0},"referencia":{"type":"string","maxLength":80}},"required":["metodo"],"additionalProperties":false}}}}}},"/v1/citas":{"get":{"operationId":"citas_listar","summary":"atenta.citas.listar","description":"Citas del negocio en un rango de fechas. Permiso: citas.","tags":["citas"],"security":[{"token":[]}],"parameters":[{"name":"desde","in":"query","required":false,"schema":{"description":"ISO o YYYY-MM-DD","type":"string"},"description":"ISO o YYYY-MM-DD"},{"name":"hasta","in":"query","required":false,"schema":{"type":"string"}},{"name":"estado","in":"query","required":false,"schema":{"type":"string","enum":["solicitada","confirmada","cancelada","atendida"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}},"post":{"operationId":"citas_crear","summary":"atenta.citas.crear","description":"Agenda una cita (inicio ISO; duración por defecto la del negocio). Permiso: citas.","tags":["citas"],"security":[{"token":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inicio":{"type":"string","minLength":10,"description":"Inicio (ISO 8601, con zona)"},"duracion_min":{"type":"integer","minimum":10,"maximum":480},"nombre":{"type":"string","maxLength":80},"motivo":{"type":"string","maxLength":200},"cliente_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Cliente"},"estado":{"type":"string","enum":["solicitada","confirmada"]},"notas":{"type":"string","maxLength":500}},"required":["inicio"],"additionalProperties":false}}}}}},"/v1/citas/disponibles":{"get":{"operationId":"citas_disponibles","summary":"atenta.citas.disponibles","description":"Próximos huecos libres dentro del horario del negocio (sin chocar con citas vivas). Permiso: citas.","tags":["citas"],"security":[{"token":[]}],"parameters":[{"name":"n","in":"query","required":false,"schema":{"description":"Cuántos huecos (por defecto los de la configuración)","type":"integer","minimum":1,"maximum":20},"description":"Cuántos huecos (por defecto los de la configuración)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/citas/{id}":{"put":{"operationId":"citas_mover","summary":"atenta.citas.mover","description":"Mueve una cita a otro inicio (y opcionalmente cambia su duración, estado o notas). Permiso: citas.","tags":["citas"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id de la cita"},"description":"Id de la cita"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inicio":{"type":"string","description":"Nuevo inicio ISO"},"duracion_min":{"type":"integer","minimum":10,"maximum":480},"estado":{"type":"string","enum":["solicitada","confirmada","atendida","cancelada"]},"notas":{"type":"string","maxLength":500}}}}}}}},"/v1/crm/clientes":{"get":{"operationId":"clientes_buscar","summary":"atenta.clientes.buscar","description":"Busca clientes por nombre, apodo o teléfono (teléfonos redactados). También filtra por etiqueta, zona o consentimiento. Permiso: clientes.","tags":["clientes"],"security":[{"token":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":80}},{"name":"etiqueta","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"zona","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"pendientes","in":"query","required":false,"schema":{"description":"Solo con datos por confirmar","type":"boolean"},"description":"Solo con datos por confirmar"},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/crm/clientes/{id}":{"get":{"operationId":"clientes_ficha","summary":"atenta.clientes.ficha","description":"Ficha completa: datos, preferencias, compras, conversaciones, etapa, seguimientos, pagos. Permiso: clientes.","tags":["clientes"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del cliente"},"description":"Id del cliente"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/crm/clientes/{id}/nota":{"post":{"operationId":"clientes_nota","summary":"atenta.clientes.nota","description":"Agrega una nota al historial del cliente. Permiso: clientes.","tags":["clientes"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del cliente"},"description":"Id del cliente"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"texto":{"type":"string","minLength":1,"maxLength":2000}},"required":["texto"],"additionalProperties":false}}}}}},"/v1/crm/clientes/{id}/seguimientos":{"post":{"operationId":"clientes_seguimiento","summary":"atenta.clientes.seguimiento","description":"Programa un seguimiento (fecha + qué hacer) que aparece en «Hoy» del CRM. Permiso: clientes.","tags":["clientes"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del cliente"},"description":"Id del cliente"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fecha":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD"},"texto":{"type":"string","minLength":1,"maxLength":500}},"required":["fecha","texto"],"additionalProperties":false}}}}}},"/v1/crm/clientes/{id}/etiquetas":{"put":{"operationId":"clientes_etiquetar","summary":"atenta.clientes.etiquetar","description":"Agrega o quita etiquetas del cliente. Permiso: clientes.","tags":["clientes"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del cliente"},"description":"Id del cliente"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agregar":{"type":"array","items":{"type":"string","maxLength":40}},"quitar":{"type":"array","items":{"type":"string","maxLength":40}}},"required":[],"additionalProperties":false}}}}}},"/v1/crm/clientes/{id}/wallet":{"get":{"operationId":"finanzas_saldo","summary":"atenta.finanzas.saldo","description":"Saldo del monedero del cliente y sus movimientos. Permiso: finanzas.","tags":["finanzas"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del cliente"},"description":"Id del cliente"},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/crm/clientes/{id}/wallet/movimientos":{"post":{"operationId":"finanzas_recargar","summary":"atenta.finanzas.recargar","description":"Recarga el monedero del cliente (o ajuste / reembolso). Permiso: finanzas. El cuerpo se completa con: {\"tipo\":\"recarga\"}.","tags":["finanzas"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del cliente"},"description":"Id del cliente"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"monto":{"type":"number","exclusiveMinimum":0},"concepto":{"type":"string","minLength":1,"maxLength":200},"tipo":{"type":"string","enum":["recarga","ajuste","reembolso"]}},"required":["monto","concepto"],"additionalProperties":false}}}}}},"/v1/creditos/{id}/abonos":{"post":{"operationId":"finanzas_abonar","summary":"atenta.finanzas.abonar","description":"Registra un abono a un crédito (se aplica a las cuotas en orden). Permiso: finanzas.","tags":["finanzas"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Id del crédito"},"description":"Id del crédito"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"monto":{"type":"number","exclusiveMinimum":0},"metodo":{"type":"string","enum":["efectivo","transferencia","wallet","link"]},"fecha":{"type":"string"},"nota":{"type":"string","maxLength":300}},"required":["monto","metodo"],"additionalProperties":false}}}}}},"/v1/finanzas/cobranza":{"get":{"operationId":"finanzas_cobranza","summary":"atenta.finanzas.cobranza","description":"Cuotas por cobrar (hoy, semana, vencidas, todas) con cliente y monto. Permiso: finanzas.","tags":["finanzas"],"security":[{"token":[]}],"parameters":[{"name":"cuando","in":"query","required":false,"schema":{"type":"string","enum":["hoy","semana","vencidas","todas"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/pagos/links":{"post":{"operationId":"finanzas_link","summary":"atenta.finanzas.link","description":"Crea un link de pago (simulado en negocios de prueba; Stripe cuando el CEO lo activa) para un pedido, un crédito o un monto suelto. Permiso: finanzas.","tags":["finanzas"],"security":[{"token":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"monto":{"type":"number","exclusiveMinimum":0},"concepto":{"type":"string","minLength":1,"maxLength":200},"cliente_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Cliente"},"pedido_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Pedido"},"credito_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Crédito"}},"required":["monto","concepto"],"additionalProperties":false}}}}}},"/v1/reporte":{"get":{"operationId":"reporte_mes","summary":"atenta.reporte.mes","description":"Reporte del mes: conversaciones, respuesta, escalaciones, ventas, cobros, monedero, crédito, clientes, campañas, satisfacción, llamadas; comparado con el mes anterior. Permiso: reportes.","tags":["reporte"],"security":[{"token":[]}],"parameters":[{"name":"mes","in":"query","required":false,"schema":{"description":"YYYY-MM (por defecto el actual)","type":"string","pattern":"^\\d{4}-\\d{2}$"},"description":"YYYY-MM (por defecto el actual)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/base":{"get":{"operationId":"base_leer","summary":"atenta.base.leer","description":"La base de respuestas ACTIVA del negocio (descripción, ubicación, horario, contacto, servicios, políticas, FAQ, por confirmar), la persona, el estado y las capacidades. Permiso: base.","tags":["base"],"security":[{"token":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/parches":{"post":{"operationId":"base_proponer","summary":"atenta.base.proponer","description":"Propone una corrección a la base (pregunta → respuesta correcta). Queda como parche propuesto: el dueño lo acepta y aprueba desde la app. Nunca se aprueba por aquí. Permiso: base.","tags":["base"],"security":[{"token":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pregunta":{"type":"string","minLength":3,"maxLength":300},"respuesta":{"type":"string","minLength":1,"maxLength":1000},"conversacion":{"type":"string","maxLength":40}},"required":["pregunta","respuesta"],"additionalProperties":false}}}}}},"/v1/menu":{"get":{"operationId":"menu_leer","summary":"atenta.menu.leer","description":"El menú estructurado (tamaños, items con precio, extras). Permiso: base.","tags":["menu"],"security":[{"token":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/menu-dia":{"get":{"operationId":"menu_dia_hoy","summary":"atenta.menu_dia.hoy","description":"El menú del día vigente (aprobado) y los pendientes por confirmar. Permiso: base.","tags":["menu_dia"],"security":[{"token":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/llamadas/historial":{"get":{"operationId":"llamadas_historial","summary":"atenta.llamadas.historial","description":"Historial de llamadas con IA (resultado, duración, pedido/cita ligados; números redactados). Permiso: reportes.","tags":["llamadas"],"security":[{"token":[]}],"parameters":[{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"estado","in":"query","required":false,"schema":{"type":"string","enum":["en_curso","terminada","perdida","fallida"]}},{"name":"resultado","in":"query","required":false,"schema":{"type":"string","enum":["pedido","cita","transferida","info","sin_resultado","perdida"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"},"404":{"$ref":"#/components/responses/Desconocido"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"},"429":{"$ref":"#/components/responses/Limite"}}}},"/v1/yo":{"get":{"operationId":"yo","summary":"Quién soy","description":"El negocio de este token, sus permisos, plan y estado.","tags":["token"],"security":[{"token":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/NoAutorizado"}}}},"/v1/webhooks":{"get":{"operationId":"webhooks_listar","summary":"Webhooks salientes","description":"Lista los webhooks del negocio (sin secretos). Permiso: integraciones.","tags":["webhooks"],"security":[{"token":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"}}},"post":{"operationId":"webhooks_crear","summary":"Crear webhook","description":"Da de alta un webhook (máximo 5 por negocio). Eventos: mensaje, escalacion, pedido, cita, pago, llamada. Si no mandas `secreto` se genera uno y se devuelve UNA vez. Firma: cabecera X-Atenta-Firma = t=<unix>,v1=<hmac_sha256(secreto, `${t}.${cuerpo}`)>. Permiso: integraciones.","tags":["webhooks"],"security":[{"token":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","eventos"],"properties":{"url":{"type":"string","format":"uri","description":"https://…"},"eventos":{"type":"array","items":{"type":"string","enum":["mensaje","escalacion","pedido","cita","pago","llamada"]}},"secreto":{"type":"string","minLength":16,"maxLength":128},"nombre":{"type":"string"}}}}}},"responses":{"201":{"description":"Creado"},"401":{"$ref":"#/components/responses/NoAutorizado"},"409":{"$ref":"#/components/responses/Conflicto"},"422":{"$ref":"#/components/responses/Validacion"}}}},"/v1/webhooks/{id}":{"delete":{"operationId":"webhooks_borrar","summary":"Quitar webhook","tags":["webhooks"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/Desconocido"}}}},"/v1/webhooks/{id}/probar":{"post":{"operationId":"webhooks_probar","summary":"Probar webhook","description":"Manda un evento `ping` firmado al webhook y devuelve el resultado (status, ms).","tags":["webhooks"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Resultado de la entrega"},"401":{"$ref":"#/components/responses/NoAutorizado"},"404":{"$ref":"#/components/responses/Desconocido"}}}},"/v1/webhooks/{id}/entregas":{"get":{"operationId":"webhooks_entregas","summary":"Últimas entregas","tags":["webhooks"],"security":[{"token":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"}}}},"/v1/tokens":{"get":{"operationId":"tokens_listar","summary":"Tokens del negocio","description":"Lista los tokens (prefijo, permisos, último uso). Crear tokens solo se hace desde la app. Permiso: integraciones.","tags":["token"],"security":[{"token":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"}}}},"/v1/alta":{"post":{"operationId":"partner_alta","summary":"Alta de un negocio (partner)","description":"Solo con partner token (atp_…): da de alta un negocio como lo hace el formulario de atenta.mx. Devuelve slug, folio y la sesión inicial del dueño (15 min) para que él entre y verifique con el enlace de su WhatsApp.","tags":["partner"],"security":[{"token":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["negocio","giro","whatsapp"],"properties":{"negocio":{"type":"string"},"giro":{"type":"string"},"whatsapp":{"type":"string"},"sitio":{"type":"string"},"correo":{"type":"string"},"pais":{"type":"string","description":"ISO-2 (MX, US, CO)"},"horario":{"type":"string"}}}}}},"responses":{"200":{"description":"Alta recibida"},"403":{"$ref":"#/components/responses/SinPermiso"}}}},"/v1/tenants":{"get":{"operationId":"partner_tenants","summary":"Negocios de este partner","tags":["partner"],"security":[{"token":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/NoAutorizado"},"403":{"$ref":"#/components/responses/SinPermiso"}}}},"/v1/tenants/{slug}/base":{"get":{"operationId":"partner_tenant_base","summary":"Base y estado de un negocio del partner (lectura)","tags":["partner"],"security":[{"token":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/Desconocido"}}}}},"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer","bearerFormat":"atk_<slug>_<32 hex>","description":"Authorization: Bearer atk_…"}},"responses":{"NoAutorizado":{"description":"Token inválido o revocado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"motivo":{"type":"string"}}}}}},"SinPermiso":{"description":"El token no tiene el permiso, o la acción solo se hace desde la app (`solo_desde_la_app`), o el token es de otro negocio (`otro_negocio`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"permiso":{"type":"string"},"motivo":{"type":"string"}}}}}},"Desconocido":{"description":"No existe en este negocio"},"Conflicto":{"description":"Estado que no permite la acción (la clave viene en `error`)"},"Validacion":{"description":"Datos incompletos o inválidos (`campos`)"},"Limite":{"description":"Más de 120 llamadas en un minuto; `reintentar_en_s`"}}}}