POST /open-api/v1/forms/{formId}/delivery

curl -X POST "https://api.walla.my/open-api/v1/forms/form_abc/delivery" \
  -H "X-WALLA-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "customerKey": "customer_001",
        "name": "홍길동",
        "email": "john@example.com",
        "phoneNumber": "+821012345678"
      },
      {
        "customerKey": "customer_002",
        "email": "jane@example.com"
      }
    ],
    "subject": "We value your feedback!",
    "message": "Please take a moment to complete our survey.",
    "deliveryChannel": "emailFirst"
  }'

{
  "success": true,
  "data": {
    "totalRecipients": 2,
    "successfulDeliveries": [
      {
        "customerKey": "customer_001",
        "name": "홍길동",
        "email": "john@example.com",
        "phoneNumber": "+821012345678",
        "aliasId": "8c1a4e2b-7d3f-4a9b-9c2e-1a2b3c4d5e6f",
        "formUrl": "https://walla.my/a/8c1a4e2b-7d3f-4a9b-9c2e-1a2b3c4d5e6f"
      },
      {
        "customerKey": "customer_002",
        "name": null,
        "email": "jane@example.com",
        "phoneNumber": null,
        "aliasId": "2f5d6e1c-9a4b-4c3d-8e7f-0a1b2c3d4e5f",
        "formUrl": "https://walla.my/a/2f5d6e1c-9a4b-4c3d-8e7f-0a1b2c3d4e5f"
      }
    ],
    "failedDeliveries": []
  }
}

{
  "success": true,
  "data": {
    "totalRecipients": 3,
    "successfulDeliveries": [
      {
        "customerKey": "customer_001",
        "name": "홍길동",
        "email": "john@example.com",
        "phoneNumber": "+821012345678",
        "aliasId": "8c1a4e2b-7d3f-4a9b-9c2e-1a2b3c4d5e6f",
        "formUrl": "https://walla.my/a/8c1a4e2b-7d3f-4a9b-9c2e-1a2b3c4d5e6f"
      },
      {
        "customerKey": "customer_002",
        "name": null,
        "email": "jane@example.com",
        "phoneNumber": null,
        "aliasId": "2f5d6e1c-9a4b-4c3d-8e7f-0a1b2c3d4e5f",
        "formUrl": "https://walla.my/a/2f5d6e1c-9a4b-4c3d-8e7f-0a1b2c3d4e5f"
      }
    ],
    "failedDeliveries": [
      {
        "customerKey": "customer_003",
        "name": null,
        "email": "invalid-email",
        "phoneNumber": null,
        "error": "Invalid email format"
      }
    ]
  }
}

POST /open-api/v1/forms/{formId}/delivery/recipients

curl -X POST "https://api.walla.my/open-api/v1/forms/form_abc/delivery/recipients" \
  -H "X-WALLA-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "customerKey": "customer_003",
        "name": "김하늘",
        "email": "sky@example.com",
        "hiddenFieldValues": {
          "utm_source": "newsletter"
        }
      },
      {
        "customerKey": "customer_004"
      }
    ]
  }'

{
  "success": true,
  "data": {
    "totalRecipients": 2,
    "recipients": [
      {
        "customerKey": "customer_003",
        "created": true,
        "aliasId": "3a7b9c0d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
        "formUrl": "https://walla.my/a/3a7b9c0d-1e2f-4a5b-8c9d-0e1f2a3b4c5d"
      },
      {
        "customerKey": "customer_004",
        "created": false,
        "aliasId": "6b8c0d1e-2f3a-4b5c-9d0e-1f2a3b4c5d6e",
        "formUrl": "https://walla.my/a/6b8c0d1e-2f3a-4b5c-9d0e-1f2a3b4c5d6e"
      }
    ]
  }
}

PATCH /open-api/v1/forms/{formId}/delivery/recipients

curl -X PATCH "https://api.walla.my/open-api/v1/forms/form_abc/delivery/recipients" \
  -H "X-WALLA-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "customerKey": "customer_003",
        "email": "sky.kim@example.com",
        "hiddenFieldValues": {
          "utm_source": "campaign_q3"
        }
      },
      {
        "customerKey": "customer_005",
        "phoneNumber": "+821098765432"
      }
    ]
  }'

{
  "success": true,
  "data": {
    "totalRequested": 2,
    "updatedCustomerKeys": ["customer_003"],
    "notFoundCustomerKeys": ["customer_005"]
  }
}

POST /open-api/v1/forms/{formId}/delivery/send

curl -X POST "https://api.walla.my/open-api/v1/forms/form_abc/delivery/send" \
  -H "X-WALLA-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customerKeys": ["customer_001", "customer_003", "customer_004", "customer_005"],
    "subject": "We value your feedback!",
    "message": "Please take a moment to complete our survey.",
    "deliveryChannel": "both"
  }'

{
  "success": true,
  "data": {
    "totalRequested": 4,
    "successfulDeliveries": [
      {
        "customerKey": "customer_001"
      },
      {
        "customerKey": "customer_003"
      }
    ],
    "failedDeliveries": [
      {
        "customerKey": "customer_004",
        "error": "No contact information registered for this recipient"
      }
    ],
    "notFoundCustomerKeys": ["customer_005"]
  }
}

GET /open-api/v1/forms/{formId}/delivery

curl -X GET "https://api.walla.my/open-api/v1/forms/form_abc/delivery" \
  -H "X-WALLA-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "delivery_123",
      "formId": "form_abc",
      "customerKey": "customer_001",
      "name": "홍길동",
      "email": "john@example.com",
      "phone": "+821012345678",
      "aliasId": "8c1a4e2b-7d3f-4a9b-9c2e-1a2b3c4d5e6f",
      "formUrl": "https://walla.my/a/8c1a4e2b-7d3f-4a9b-9c2e-1a2b3c4d5e6f",
      "hiddenFieldValues": {
        "utm_source": "newsletter"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:45:00Z"
    },
    {
      "id": "delivery_456",
      "formId": "form_abc",
      "customerKey": "customer_002",
      "name": null,
      "email": "jane@example.com",
      "phone": null,
      "aliasId": null,
      "formUrl": null,
      "hiddenFieldValues": {},
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

POST /open-api/v1/forms/{formId}/delivery/status

curl -X POST "https://api.walla.my/open-api/v1/forms/form_abc/delivery/status" \
  -H "X-WALLA-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customerKeys": ["customer_001", "customer_002", "customer_003"]
  }'

{
  "success": true,
  "data": [
    {
      "id": "delivery_123",
      "formId": "form_abc",
      "customerKey": "customer_001",
      "name": "홍길동",
      "email": "john@example.com",
      "phone": "+821012345678",
      "status": "RESPONDED",
      "lastSentAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T14:20:00Z"
    },
    {
      "id": "delivery_456",
      "formId": "form_abc",
      "customerKey": "customer_002",
      "name": null,
      "email": "jane@example.com",
      "phone": null,
      "status": "OPENED",
      "lastSentAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:15:00Z"
    },
    {
      "id": "delivery_789",
      "formId": "form_abc",
      "customerKey": "customer_003",
      "name": null,
      "email": "bob@example.com",
      "phone": null,
      "status": "SENT",
      "lastSentAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

interface Recipient {
  customerKey: string;
  name?: string;
  email?: string;
  phoneNumber?: string;
  hiddenFieldValues?: Record<string, string>;
}

interface DeliveryOptions {
  subject?: string;
  message?: string;
  deliveryChannel?: 'emailFirst' | 'phoneFirst' | 'both';
}

async function sendForm(
  formId: string,
  recipients: Recipient[],
  options?: DeliveryOptions
) {
  const response = await fetch(
    `https://api.walla.my/open-api/v1/forms/${formId}/delivery`,
    {
      method: 'POST',
      headers: {
        'X-WALLA-API-KEY': process.env.WALLA_API_KEY!,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        recipients,
        subject: options?.subject || '설문이 도착했습니다.',
        message: options?.message || '설문 링크를 확인하세요.',
        deliveryChannel: options?.deliveryChannel || 'emailFirst'
      })
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

async function registerRecipients(formId: string, recipients: Recipient[]) {
  const response = await fetch(
    `https://api.walla.my/open-api/v1/forms/${formId}/delivery/recipients`,
    {
      method: 'POST',
      headers: {
        'X-WALLA-API-KEY': process.env.WALLA_API_KEY!,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ recipients })
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

async function sendToRegistered(
  formId: string,
  customerKeys: string[],
  options?: DeliveryOptions
) {
  const response = await fetch(
    `https://api.walla.my/open-api/v1/forms/${formId}/delivery/send`,
    {
      method: 'POST',
      headers: {
        'X-WALLA-API-KEY': process.env.WALLA_API_KEY!,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customerKeys,
        subject: options?.subject,
        message: options?.message,
        deliveryChannel: options?.deliveryChannel
      })
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

async function getDeliveryStatus(formId: string, customerKeys: string[]) {
  const response = await fetch(
    `https://api.walla.my/open-api/v1/forms/${formId}/delivery/status`,
    {
      method: 'POST',
      headers: {
        'X-WALLA-API-KEY': process.env.WALLA_API_KEY!,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ customerKeys })
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();
  return data.data;
}

// Usage example
const result = await sendForm('form_abc', [
  {
    customerKey: 'customer_001',
    email: 'john@example.com'
  },
  {
    customerKey: 'customer_002',
    email: 'jane@example.com',
    phoneNumber: '+821012345678'
  }
], {
  subject: 'We need your feedback!',
  message: 'Please help us improve our services.'
});

console.log(`Successfully sent to ${result.data.successfulDeliveries.length} recipients`);

// Register only, then distribute the links through your own channel
const registered = await registerRecipients('form_abc', [
  { customerKey: 'customer_003' }
]);
registered.data.recipients.forEach(r => pushToOwnChannel(r.customerKey, r.formUrl));

// Send (or resend) later with customerKey only
await sendToRegistered('form_abc', ['customer_003'], { deliveryChannel: 'both' });

// Check status
const statuses = await getDeliveryStatus('form_abc', ['customer_001', 'customer_002']);
statuses.forEach(status => {
  console.log(`${status.customerKey}: ${status.status}`);
});

import requests
import os
from typing import List, Dict, Any, Optional

class WallaDeliveryAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.walla.my/open-api/v1"
        self.headers = {
            "X-WALLA-API-KEY": api_key,
            "Content-Type": "application/json"
        }

    def send_form(
        self,
        form_id: str,
        recipients: List[Dict[str, Any]],
        subject: Optional[str] = None,
        message: Optional[str] = None,
        delivery_channel: Optional[str] = None
    ) -> Dict[str, Any]:
        """Send form to recipients"""
        url = f"{self.base_url}/forms/{form_id}/delivery"
        payload: Dict[str, Any] = {
            "recipients": recipients,
            "subject": subject or "설문이 도착했습니다.",
            "message": message or "설문 링크를 확인하세요."
        }
        if delivery_channel:
            payload["deliveryChannel"] = delivery_channel

        response = requests.post(url, headers=self.headers, json=payload)
        response.raise_for_status()
        return response.json()

    def register_recipients(
        self,
        form_id: str,
        recipients: List[Dict[str, Any]]
    ) -> Dict[str, Any]:
        """Register recipients without sending"""
        url = f"{self.base_url}/forms/{form_id}/delivery/recipients"
        payload = {"recipients": recipients}

        response = requests.post(url, headers=self.headers, json=payload)
        response.raise_for_status()
        return response.json()

    def update_recipients(
        self,
        form_id: str,
        updates: List[Dict[str, Any]]
    ) -> Dict[str, Any]:
        """Update already registered recipients"""
        url = f"{self.base_url}/forms/{form_id}/delivery/recipients"
        payload = {"updates": updates}

        response = requests.patch(url, headers=self.headers, json=payload)
        response.raise_for_status()
        return response.json()

    def send_to_registered(
        self,
        form_id: str,
        customer_keys: List[str],
        subject: Optional[str] = None,
        message: Optional[str] = None,
        delivery_channel: Optional[str] = None
    ) -> Dict[str, Any]:
        """Send form to already registered recipients"""
        url = f"{self.base_url}/forms/{form_id}/delivery/send"
        payload: Dict[str, Any] = {"customerKeys": customer_keys}
        if subject:
            payload["subject"] = subject
        if message:
            payload["message"] = message
        if delivery_channel:
            payload["deliveryChannel"] = delivery_channel

        response = requests.post(url, headers=self.headers, json=payload)
        response.raise_for_status()
        return response.json()

    def get_all_deliveries(self, form_id: str) -> List[Dict[str, Any]]:
        """Get all delivery recipients for a form"""
        url = f"{self.base_url}/forms/{form_id}/delivery"
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()["data"]

    def get_delivery_status(
        self,
        form_id: str,
        customer_keys: List[str]
    ) -> List[Dict[str, Any]]:
        """Get delivery status for specific recipients"""
        url = f"{self.base_url}/forms/{form_id}/delivery/status"
        payload = {"customerKeys": customer_keys}

        response = requests.post(url, headers=self.headers, json=payload)
        response.raise_for_status()
        return response.json()["data"]

    def get_response_rate(self, form_id: str) -> float:
        """Calculate response rate for a form"""
        deliveries = self.get_all_deliveries(form_id)
        if not deliveries:
            return 0.0

        customer_keys = [d["customerKey"] for d in deliveries]
        statuses = self.get_delivery_status(form_id, customer_keys)

        responded = sum(1 for s in statuses if s["status"] == "RESPONDED")
        return (responded / len(statuses)) * 100

# Usage
api = WallaDeliveryAPI(os.getenv("WALLA_API_KEY"))

# Send form
result = api.send_form(
    "form_abc",
    [
        {"customerKey": "customer_001", "email": "john@example.com"},
        {"customerKey": "customer_002", "email": "jane@example.com"}
    ],
    subject="Your feedback matters!",
    message="Please take 2 minutes to complete our survey."
)

print(f"Sent to {len(result['data']['successfulDeliveries'])} recipients")

# Register first, send later
registered = api.register_recipients(
    "form_abc",
    [{"customerKey": "customer_003", "email": "sky@example.com"}]
)
for recipient in registered["data"]["recipients"]:
    print(f"{recipient['customerKey']}: {recipient['formUrl']}")

send_result = api.send_to_registered(
    "form_abc",
    ["customer_003"],
    delivery_channel="both"
)
print(f"Sent to {len(send_result['data']['successfulDeliveries'])} recipients")

# Check response rate
response_rate = api.get_response_rate("form_abc")
print(f"Response rate: {response_rate:.2f}%")

// 캠페인에 따른 맞춤화
const campaigns = {
  feedback: {
    subject: 'We value your feedback!',
    message: 'Help us improve our services by completing this quick survey.'
  },
  nps: {
    subject: 'How likely are you to recommend us?',
    message: 'Your opinion matters. Please share your thoughts.'
  }
};

await sendForm(formId, recipients, campaigns.feedback);