> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Email a purchase order to the vendor (first send or revision send)
> Sends the purchase order to the vendor by email through the canonical
`sendDocument` helper (THE ONE RULE for document emails), stamps
`sent_at` on the order row, and syncs `last_notified_revision` to the
current `revision_count` so any amber revision banner on PO detail
clears.
Three send modes are supported:
- **First send** (default): no `template_key_override` set. Uses the
default purchase-order template and broadcasts `purchase_order.sent`.
- **Revision send**: set `template_key_override='po_revised'` plus
`revision_number` and `changed_fields` so the vendor receives the
dedicated revision template; broadcasts `purchase_order.revised_sent`.
Used by the revision-notification prompt's "Send" path -- the "Skip"
path is handled by `POST /purchase-orders/{id}/notify-revision`.
- **Stamp-only**: set `stamp_only=true` to record `sent_at` without
emitting an email (the email has already been sent through a
separate path, e.g. the dashboard's "Email to Vendor" dialog).
Guards:
- 422 `po_pending_approval` if the PO is awaiting approval.
- 422 `po_cancelled` if the PO is cancelled.
- 422 `vendor_email_missing` if no `to_email` is provided AND the
vendor account has no email on file (skipped when `stamp_only=true`).
Side effects: stamps `sent_at` + `last_notified_revision`, emits a
`purchase_order.sent` (or `purchase_order.revised_sent`) broadcast
(Rule 13), and writes a `po_sent` (or `po_revised_vendor_notified`)
activity entry (Rule 20).
Rule 25: this endpoint is wired in both the API-key dispatch and the
Cognito-JWT dispatch -- API key callers and dashboard callers reach
the same canonical handler.
Required API key scope: `purchasing:write`
## OpenAPI
````yaml /openapi.yaml post /purchase-orders/{id}/send-to-vendor
openapi: 3.1.0
info:
title: Arcus ERP Public API
version: 1.0.0
description: >
Arcus ERP public REST API. Designed for external integrations and data
migration.
**Authentication.** Bearer token (API key) via the `Authorization` header.
Format: `Authorization: Bearer ark_live_ent__` (or
`ark_test_*` for sandbox).
API keys are issued per-entity in **Settings > Developers > API Keys**.
**Entity scoping.** The entity is encoded in the API key prefix; routes are
flat
(e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform
endpoints
(migration, reconciliation, events, webhook endpoints, API keys) use the
`/v1/entities/{entity_id}/...` form -- those are noted in their tags.
**Key capabilities.**
- Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource).
- Cursor-based pagination (`starting_after` / `ending_before` / `limit`).
- Idempotency via the `Idempotency-Key` header.
- Webhook events for asynchronous notification.
- Conditional requests / ETag for cache validation.
servers:
- url: https://api.arcuserp.com/v1
description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys)
- url: https://dev-api.arcuserp.com/v1
description: >-
Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev
RDS)
security: []
paths:
/purchase-orders/{id}/send-to-vendor:
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
post:
tags:
- Purchasing
summary: Email a purchase order to the vendor (first send or revision send)
description: |
Sends the purchase order to the vendor by email through the canonical
`sendDocument` helper (THE ONE RULE for document emails), stamps
`sent_at` on the order row, and syncs `last_notified_revision` to the
current `revision_count` so any amber revision banner on PO detail
clears.
Three send modes are supported:
- **First send** (default): no `template_key_override` set. Uses the
default purchase-order template and broadcasts `purchase_order.sent`.
- **Revision send**: set `template_key_override='po_revised'` plus
`revision_number` and `changed_fields` so the vendor receives the
dedicated revision template; broadcasts `purchase_order.revised_sent`.
Used by the revision-notification prompt's "Send" path -- the "Skip"
path is handled by `POST /purchase-orders/{id}/notify-revision`.
- **Stamp-only**: set `stamp_only=true` to record `sent_at` without
emitting an email (the email has already been sent through a
separate path, e.g. the dashboard's "Email to Vendor" dialog).
Guards:
- 422 `po_pending_approval` if the PO is awaiting approval.
- 422 `po_cancelled` if the PO is cancelled.
- 422 `vendor_email_missing` if no `to_email` is provided AND the
vendor account has no email on file (skipped when `stamp_only=true`).
Side effects: stamps `sent_at` + `last_notified_revision`, emits a
`purchase_order.sent` (or `purchase_order.revised_sent`) broadcast
(Rule 13), and writes a `po_sent` (or `po_revised_vendor_notified`)
activity entry (Rule 20).
Rule 25: this endpoint is wired in both the API-key dispatch and the
Cognito-JWT dispatch -- API key callers and dashboard callers reach
the same canonical handler.
Required API key scope: `purchasing:write`
operationId: sendPurchaseOrderToVendorV1
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 255
description: Optional idempotency key for safe retries (Stripe-style).
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
to_email:
type: string
format: email
description: |
Override the destination email. When omitted, defaults to
the vendor account's `email`. Required (either here or on
the vendor) unless `stamp_only=true`.
stamp_only:
type: boolean
default: false
description: |
When `true`, stamps `sent_at` + `last_notified_revision`
without dispatching an email (the email has already been
sent through a separate path). Skips the `to_email` /
vendor-email guard.
template_key_override:
type: string
enum:
- po_revised
description: |
When set to `po_revised`, uses the revision-send template
instead of the default purchase-order template. Combine
with `revision_number` and `changed_fields` for context.
revision_number:
type: integer
description: |
The revision number being sent (e.g. `2` for the second
send after the initial first-send `1`). Used only when
`template_key_override='po_revised'`.
changed_fields:
type: string
description: |
Human-readable summary of what changed between revisions
(e.g. "line quantity, due date"). Rendered in the revision
email template. Used only when
`template_key_override='po_revised'`.
responses:
'200':
description: Purchase order sent (or stamped). Returns the canonical send result.
content:
application/json:
schema:
type: object
properties:
po_id:
type: string
format: uuid
po_number:
type: string
sent_to:
type: string
format: email
sent_at:
type: string
format: date-time
revision_send:
type: boolean
description: >-
Present and `true` only when
`template_key_override='po_revised'`.
revision_number:
type: integer
description: Echoes the request body when this was a revision send.
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'403':
$ref: '#/components/responses/Error'
'404':
description: Purchase order not found for this entity.
content:
application/json:
schema:
$ref: '#/components/responses/Error'
'422':
description: |
Vendor email missing (`vendor_email_missing`), PO awaiting approval
(`po_pending_approval`), or PO cancelled (`po_cancelled`).
content:
application/json:
schema:
$ref: '#/components/responses/Error'
security:
- ApiKeyAuth: []
components:
responses:
Error:
description: Error response (400/401/403/404/409/422/429/500)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
schemas:
ErrorEnvelope:
type: object
description: |
Canonical error response envelope. All API errors use this shape.
required:
- error
- code
properties:
error:
type: string
description: Machine-readable error key
example: not_found
code:
type: string
description: Machine-readable error code (often same as error)
example: not_found
type:
type: string
enum:
- validation_error
- permission_error
- not_found
- conflict
- rate_limit
- internal
- expand_error
- not_implemented
example: not_found
hint:
type: string
description: Human-readable one-sentence explanation (English)
example: >-
The requested order does not exist or does not belong to this
entity.
param:
type: string
description: The parameter that caused the error, if applicable
example: expand[0]
required:
type: string
description: The scope required (only on insufficient_scope errors)
example: accounts:read
request_id:
type: string
description: >-
Unique request ID for support tracing (maps to CloudWatch log
stream)
example: req_abc123
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: |
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent__
Test keys use ark_test_ent__. Both are issued per entity
via Settings > Developers > API Keys.
````