DOCSEARCHbyAlgolia
Submit Docs

Kenar Documentation

website·Indexed 31 days ago

https://divar-ir.github.io/kenar-docs

Developer documentation for the Kenar open platform, providing APIs for post management (submission, editing, and statistics), payment services (pricing, balance transactions, and ad renewals), semantic data management for users and posts, and widget action configurations for the Divar ecosystem.

Tokens
55.7K
Snippets
246
Records
438
Agent score
74%

What's inside Kenar

  1. Overview of the Divar post submission process

    The post submission API allows for the programmatic creation of advertisements on Divar. The general workflow consists of five main steps:

    1. Upload Images: Upload images to Divar's image service to obtain their identifiers.
    2. Retrieve Category Schema: Fetch the specific fields required for the chosen category (e.g., Real Estate, Vehicles).
    3. Submit Post: Send general and category-specific information to create a post in the 'Pending Payment' state.
    4. Pay Publication Fee: Pay the cost using the application's credit.
    5. Review and Publish: The post enters a review queue and is published upon approval.

  2. Overview of Divar Touch Points

    Touch Points are specific locations within the Divar platform (web and apps) where an extension can be displayed to initiate user interaction. When a user clicks an extension at a touch point, they are redirected to the extension's web interface via a WebView or popup, depending on the platform (Android, iOS, or Web). Initial context data, such as ad IDs or chat IDs, is provided to the extension to ensure a seamless user experience.

  3. Understand the Divar location hierarchy

    The Divar platform uses a three-level hierarchical structure for locations: Province > City > District. For example: Tehran (Province) > Tehran (City) > Jannat Abad (District). In the 'Kenar' platform, most operations and searches are performed at the City level.

  4. Implement actions in Kenar widgets

    Kenar widgets can perform actions (such as redirecting a user to another website) when a specific part of the widget is clicked. To enable this, widgets that support actions accept a JSON field named action in their configuration.

    Supported actions are categorized into two types:

    1. External/App Redirection: Used to move the user to your own application or external links.

      • OpenDirectLink
      • OpenServerLink
      • DynamicAction

    2. Internal Divar Navigation: Used to move the user to specific internal pages within the Divar app.

      • OpenPostPage: Opens a specific post page.
      • OpenPostManagePage: Opens the post management page.

  5. Adhere to user privacy and data collection standards

    Developers must follow strict data privacy rules to avoid app suspension:

    • Data Minimization: Collect only the data strictly necessary for the service. Be transparent with users about how their data is used.
    • Storage Restrictions: Avoid storing sensitive personal information (e.g., addresses, national IDs, chat messages). If storage is required, keep data for the minimum time possible and delete it afterward.
    • Coordination: If sensitive data must be stored, you must coordinate with the Divar team regarding retention periods, security measures, and notification methods.
    • Transparency: Publicly disclose what data is stored, for how long, and why in an easily accessible location for users.

  6. Subscribe to Divar real-time events via Webhooks

    To receive real-time notifications about events occurring in Divar, you must create a subscription. Once successful, Divar will send an HTTP POST request (Webhook) to your configured event receiver URL whenever the specified event occurs.

    Requirements:

    1. Your application must have the EVENTS_REGISTER_SUBSCRIPTION permission assigned to your API key (this is a global API key permission, not an OAuth scope).
    2. You must have a valid event receiver URL configured in the Kenar panel.
    3. Your authentication token must contain the specific OAuth scope associated with the event type you are subscribing to.

    Note: Subscriptions are valid as long as your token is valid. If you refresh your token, you must send a new subscription request to extend the subscription.

  7. Post object schema for update events

    The post object provides details about the advertisement, mirroring the data returned by the /finder/post/{post-token} endpoint.
    interface Post {
  token: string; // Ad token
  category: string; // Ad category
  city: string; // City
  district: string; // District
  is_phone_hidden: boolean; // Whether the phone number is hidden
  supplier_chat_assistant_enabled: boolean; // Whether Divar sales assistant is active
  chat_enabled: boolean; // Whether Divar chat is active
  first_published_at: string; // ISO datetime of first publication
  data: Object; // Other ad fields
}

  8. Integrate your application as a service provider in Divar Chat

    Divar suggests service providers to users in chat based on criteria such as city or ad category. If your application belongs to these groups, it can be introduced as a service provider. Users can open your web application directly from the chat to submit requests or receive services. Your application will be opened as a webview within the Divar app or as a pop-up on the Divar web platform.

  9. Enforce peer review in source control

    Implement technical controls in your version control system to prevent code from being merged into the repository without approval from one or more other developers. This serves as a fundamental security control in the development lifecycle.

  10. Retrieve advertisement details by token

    Use this API to get detailed information about a specific Divar advertisement. The request requires a post token and an API key. Note that if a field is missing from the response, it indicates the value is zero or disabled (e.g., if chat_enabled is missing, chat is not active for that post).
    GET https://open-api.divar.ir/v1/open-platform/finder/post/{{token}}
x-api-key: {{apikey}}

  11. Transmit semantic data to Divar

    To transfer semantic information to Divar and its associated teams, use the semantic fields. These fields allow for the structured transmission of metadata related to users and posts.

  12. Interact with Divar APIs and manage permissions

    Applications interact with Divar for tasks such as retrieving ad info, adding content to ads, or sending chat messages. These interactions are handled via the 'Kenar Divar' APIs using API keys and, where necessary, user OAuth authorization.

    Access levels are configured via:

    • Permissions: Defines the general access rights of the application (maximum key permissions).
    • Widgets: Specifies the content elements usable within ads.