Elocuenti Orders API

openapi: 3.2.0
info:
  title: Elocuenti Orders API
  version: 1.0.0
  description: 'The public REST API of Elocuenti: contacts, conversations, funnels, WhatsApp templates, knowledge base, automations, events, AI calls, webhooks and charges (Colombia).


    Authenticate every request with `Authorization: Bearer `. A key that starts with `eloc_live_` acts in production; one that starts with `eloc_sand_` is a sandbox key: it never messages or calls your customers, and the **Sandbox** line of each operation says what it does instead. Create keys in Settings → API Keys.


    Guides and reference: https://www.elocuenti.com/api/docs'
servers:
- url: https://www.elocuenti.com
tags:
- name: Orders
paths:
  /api/v1/ecommerce/orders/confirmation:
    post:
      tags:
      - Orders
      summary: Confirm a purchase
      description: 'Sends your purchase-confirmation template by WhatsApp. If the purchase closes an abandoned cart, the cart is marked as recovered; if you have an active «order created» automation, the automation writes instead of the template.


        It answers `202` with `purchase_confirmation_sent`, `purchase_queued_to_workflow` (your automation writes) or `purchase_saved_template_failed` (saved, the template failed). The same `idempotency_key` answers `200` with `purchase_already_confirmed` and never writes to the buyer twice. A `409` is a passing conflict: retry.


        **Permission:** `messages:write` · **Sandbox:** checked, nothing is saved or sent (`simulated: true`) · **Idempotency:** `idempotency_key` in the body · **Max body:** 5 MB'
      operationId: create_purchase_confirmation
      security:
      - ApiKey: []
      x-access:
        permission: messages:write
        sandbox: simulate
        idempotencyField: idempotency_key
        maxBody: 5 MB
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseConfirmationBody'
            examples:
              purchase:
                summary: Order paid
                value:
                  phone: '+573001234567'
                  template_name: order_confirmation
                  external_reference: order-1042
                  customer_name: Ana Gómez
                  order_total: 189900
                  currency: COP
                  template_params:
                    '1': Ana
                    '2': '1042'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseConfirmationResponse'
        '202':
          description: 'Accepted: the request is valid and the work finishes asynchronously. It does not mean the effect already happened.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseConfirmationResponse'
        '400':
          description: 'Malformed request: a rule the JSON Schema cannot express (between fields, a required signature header that is missing) or a body that is not UTF-8. Broken JSON in UTF-8 answers **422** `json_invalid` instead.'
        '401':
          description: 'Not authenticated: the API key is missing, invalid or expired.'
        '403':
          description: Authenticated, but without permission for this resource or business.
        '409':
          description: Conflicts with the current state of the resource.
        '422':
          description: The body or the parameters fail the schema's validation.
        '429':
          description: The API key or the IP went over its request limit.
        '500':
          description: 'Internal error: there is nothing the client can change to fix it.'
components:
  schemas:
    PurchaseConfirmationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PurchaseConfirmation'
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - 3f9a1c07d2b4
          title: Request Id
        simulated:
          description: '`true` only with a sandbox key: the request was checked in full and nothing was sent or saved.'
          type: boolean
          title: Simulated
      required:
      - data
      title: PurchaseConfirmationResponse
    PurchaseConfirmation:
      type: object
      properties:
        purchase_confirmation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Purchase Confirmation Id
        conversation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Conversation Id
        status:
          type: string
          enum:
          - purchase_confirmation_sent
          - purchase_queued_to_workflow
          - purchase_saved_template_failed
          - purchase_already_confirmed
          title: Status
        template_sent:
          type: boolean
          title: Template Sent
        contact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Id
        template_used:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Used
        used_fallback:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Used Fallback
        template_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Error
        warning:
          anyOf:
          - type: string
          - type: 'null'
          title: Warning
        workflow_delegated:
          anyOf:
          - type: boolean
          - type: 'null'
          description: An enabled order_created workflow sends the message instead.
          title: Workflow Delegated
        recovered_cart_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Abandoned cart this purchase closed, if any.
          title: Recovered Cart Id
        deduplicated:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Deduplicated
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
        existing_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Status
        existing_sent_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Sent At
        existing_reference:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Reference
        existing_created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Created At
        hint:
          anyOf:
          - type: string
          - type: 'null'
          title: Hint
        from:
          anyOf:
          - type: string
          - type: 'null'
          description: The business number the notice left from, in E.164. Present only when it already went out (not when it is queued, delegated to a workflow or saved without sending).
          title: From
      required:
      - purchase_confirmation_id
      - conversation_id
      - status
      - template_sent
      description: '`data` of the answer: 202 once sent, queued to a workflow or saved; 200 on dedup.'
      title: PurchaseConfirmation
    PurchaseConfirmationBody:
      type: object
      properties:
        phone:
          type: string
          minLength: 10
          description: Customer phone in E.164 format.
          title: Phone
        template_name:
          type: string
          minLength: 1
          description: WhatsApp template name to send.
          title: Template Name
        template_params:
          description: Optional template variables. Keys must match the template's `parameter_mapping` (e.g. `customer_name`, `order_id`) or be positional ("1", "2", ...). Merged with defaults (`customer_name`, `order_id`, `order_total`).
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          title: Template Params
        order_id:
          anyOf:
          - type: string
          - type: 'null'
          description: UUID of the confirmed order. Optional — omit for ticketing/marketplace flows that don't sync orders into Elocuenti.
          title: Order Id
        external_reference:
          description: Caller's own ID for the order (any string). Used for dedup when no order_id is available.
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: External Reference
        idempotency_key:
          description: 'Explicit dedup key. Defaults to order_id (as text) or external_reference. To send AGAIN for an order that already has a row (e.g. to re-deliver a corrected link), pass a different key such as `<external_reference>-resend-1`: dedup is per (tenant, idempotency_key) only.'
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Idempotency Key
        batch_id:
          description: Optional caller-supplied batch identifier. Echoed verbatim into the structured logs so a whole send can be reconciled per batch.
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Batch Id
        order_total:
          description: Order total; surfaced to templates as a formatted `order_total` variable.
          anyOf:
          - type: number
            minimum: 0
          - type: 'null'
          title: Order Total
        currency:
          description: ISO 4217 currency code for order_total (e.g. COP, MXN).
          anyOf:
          - type: string
            minLength: 3
            maxLength: 3
          - type: 'null'
          title: Currency
        customer_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Name
        customer_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Email
        fallback_template:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional fallback template name if the primary is not found.
          title: Fallback Template
        from:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional. The business WhatsApp number to send from, in E.164 (e.g. `+573001234567`). Omit it to send from the business default. A number that is not one of the business's active numbers is refused with 422 `from_number_not_available`.
          title: From
      required:
      - phone
      - template_name
      description: 'Send at least one of `order_id` (an order in Elocuenti) or `external_reference` (your own order number). `idempotency_key` is optional: without it the key is `order_id` (as text) or else `external_reference`, within your business, so a retry never writes to the buyer twice.'
      title: PurchaseConfirmationBody
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key