> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Iniciar contacto de recuperación para flujos de usuario abandonados

> Notifica al agente de recuperación de Yuno para que contacte a un cliente que abandonó el checkout antes de completar el pago

> [!WARNING]
>
> Este endpoint aún no está disponible a través de la API pública. `POST /smart-support/external/payments` devuelve 404 actualmente. Para iniciar el contacto de recuperación de un pago rechazado, usa [Declined Payment Calls](https://docs.y.uno/es/reference/ai-caller/declined-payment-calls.md).

Este endpoint permite a los comercios notificar al Recovery Agent de Yuno cuando un usuario abandona su flujo de compra, por ejemplo durante la selección de productos o después de iniciar el checkout, antes de completar un pago. Los datos enviados permiten a Yuno hacer seguimiento al usuario por llamada o WhatsApp para animarlo a completar la transacción.

## Seguridad y cumplimiento

* **Autenticación**: El acceso a la API requiere una clave de API válida incluida en los encabezados de la solicitud.

* **Protección de datos**: Todos los datos deben transmitirse por HTTPS. Yuno cumple con las regulaciones de protección de datos pertinentes, incluidas **GDPR** y **LGPD**.

* **Uso de los datos**: Los datos enviados se usarán únicamente con el fin de interactuar con el cliente y no se almacenarán más allá del tiempo necesario.

> [!NOTE]
>
> **Ejemplo de caso de uso**
>
> Una usuaria llamada Jane Doe agrega unos audífonos inalámbricos a su carrito en el sitio web de un comercio, pero abandona el proceso de checkout. El sistema del comercio lo detecta y envía el payload correspondiente a la API del Recovery Agent de Yuno. Yuno inicia entonces un mensaje de WhatsApp a Jane, le recuerda los artículos que dejó en su carrito y le ofrece ayuda para completar la compra.


## OpenAPI

````yaml openapi/es/ai-caller/initiate-recovery-outreach-for-abandoned-user-flows.json POST /smart-support/external/payments
openapi: 3.0.0
info:
  title: AI Caller
  description: >-
    API for initiating large-scale processing of calls and WhatsApp messages
    related to declined payments and abandoned user flows.
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - public_api_key: []
    private_secret_key: []
tags:
  - name: AI Caller
    description: Operaciones relacionadas con las cuentas de usuario
paths:
  /smart-support/external/payments:
    post:
      tags:
        - AI Caller
      summary: >-
        Iniciar el contacto de recuperación para flujos abandonados por el
        usuario
      operationId: initiate-recovery-outreach-for-abandoned-user-flows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecoveryOutreachRequest'
            examples:
              recoveryOutreachExample:
                summary: Example Recovery Outreach Request (USA)
                value:
                  customer:
                    full_name: Robert Johnson
                    phone_number: '+12125550103'
                    email: robert.johnson@example.com
                    country_code: US
                    language: en
                  session:
                    abandonment_timestamp: '2025-05-13T22:45:00Z'
                    flow_stage: cart_review
                    platform: ios
                    session_id: sess_def456uvw
                  cart:
                    total_value: 29.99
                    currency: USD
                    items:
                      - name: Bluetooth Speaker
                        sku: BSPEAKER-PRO
                        quantity: 1
                        price: 29.99
                  engagement:
                    preferred_channel: whatsapp
                    reason: user_abandoned_cart
                    metadata:
                      utm_campaign: summer_promo
                      last_clicked_button: Continue Shopping
      responses:
        '200':
          description: El contacto de recuperación se inició correctamente.
        '400':
          description: Payload de solicitud no válido o error de validación.
        '401':
          description: 'No autorizado: falta la clave de API o no es válida.'
        '500':
          description: Error interno del servidor.
components:
  schemas:
    RecoveryOutreachRequest:
      type: object
      required:
        - customer
        - session
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
        session:
          $ref: '#/components/schemas/Session'
        cart:
          $ref: '#/components/schemas/Cart'
        engagement:
          $ref: '#/components/schemas/Engagement'
    Customer:
      type: object
      required:
        - full_name
        - phone_number
        - country_code
      properties:
        full_name:
          type: string
          description: Nombre completo del cliente.
          example: Jane Doe
        phone_number:
          type: string
          description: Número de teléfono del cliente en formato E.164.
          example: '+573001234567'
        email:
          type: string
          format: email
          description: Dirección de email del cliente.
          example: jane.doe@example.com
        country_code:
          type: string
          description: Código de país ISO 3166-1 alpha-2 (por ejemplo, "CO").
          example: CO
        language:
          type: string
          description: Idioma preferido para la comunicación (por ejemplo, "es", "en").
          example: es
    Session:
      type: object
      required:
        - abandonment_timestamp
        - flow_stage
        - platform
      properties:
        abandonment_timestamp:
          type: string
          format: date-time
          description: Marca de tiempo del momento en que el usuario abandonó el flujo.
          example: '2025-05-13T22:45:00Z'
        flow_stage:
          type: string
          description: Etapa en la que el usuario abandonó el flujo.
          enum:
            - product_selection
            - cart_review
            - checkout
            - payment
          example: checkout
        platform:
          type: string
          description: Plataforma del usuario.
          enum:
            - web
            - ios
            - android
          example: web
        session_id:
          type: string
          description: Identificador único de la sesión del usuario.
          example: sess_abc123xyz
    Cart:
      type: object
      properties:
        total_value:
          type: number
          format: float
          description: Valor total del carrito.
          example: 149.99
        currency:
          type: string
          description: Código de moneda (por ejemplo, "COP").
          example: COP
        items:
          type: array
          description: Lista de artículos del carrito.
          items:
            $ref: '#/components/schemas/CartItem'
    Engagement:
      type: object
      properties:
        preferred_channel:
          type: string
          description: Canal de comunicación preferido.
          enum:
            - call
            - whatsapp
            - auto
          default: auto
          example: auto
        reason:
          type: string
          description: Motivo del abandono, si se conoce.
          example: user_abandoned_checkout
        metadata:
          type: object
          description: >-
            Información contextual adicional (por ejemplo, parámetros UTM,
            últimas acciones del usuario).
          example:
            utm_campaign: spring_sale
            last_clicked_button: Proceed to Payment
    CartItem:
      type: object
      properties:
        name:
          type: string
          description: Nombre del artículo.
          example: Wireless Headphones
        sku:
          type: string
          description: Identificador de la unidad de mantenimiento de stock (SKU).
          example: WH-1000XM5
        quantity:
          type: integer
          description: Cantidad de unidades.
          example: 1
        price:
          type: number
          format: float
          description: Precio por unidad.
          example: 149.99
  securitySchemes:
    public_api_key:
      type: apiKey
      in: header
      name: public-api-key
      description: |
        Ejemplo: `<Your public-api-key>`
    private_secret_key:
      type: apiKey
      in: header
      name: private-secret-key
      description: |
        Ejemplo: `<Your private-secret-key>`      

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.