Integrations API

Marketplaces, online shops, carriers, e-invoice and Google reviews, synced into your own orders, products, stock and customers.

Module code integrations · 22 actions · 8 data models · 22 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: integrations (everything), integrations:read (read only) or integrations:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

integrations.cancel_shipment

Cancel a parcel — Cancels a parcel the carrier has not picked up yet; the carrier is told in the background.

Needs integrations:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/integrations.cancel_shipment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.shipment_updated

What it writes: carrier_shipment (update) — Marks it cancelled

curl -X POST https://app.getera.io/api/v1/carrier_shipments/CARRIER_SHIPMENT_ID/actions/cancel_shipment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.shipment_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.carrierShipments.cancelShipment("CARRIER_SHIPMENT_ID")

era carrier_shipments cancel_shipment CARRIER_SHIPMENT_ID

{
  "name": "era__integrations__cancel_shipment",
  "arguments": {
    "id": "CARRIER_SHIPMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, not_cancellable · 429 slow down

integrations.connect

Connect an app for syncing — Links a connection (its sealed key) to what Era syncs it with: a sales channel and warehouse for a marketplace or shop.

Needs integrations:manage · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/integrations.connect

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.connected

What it writes: integration_account (insert) — The account, with a fresh inbound-webhook token

curl -X POST https://app.getera.io/api/v1/integration_accounts/actions/connect \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"App"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.connected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationAccounts.connect({
  provider: "App"
})

era integration_accounts connect \
  --provider "App"

{
  "name": "era__integrations__connect",
  "arguments": {
    "provider": "App"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_provider, credential_not_found, provider_mismatch, credential_taken, channel_required, channel_taken, bad_config, bad_setting · 429 slow down

integrations.create_shipment

Send with a carrier — Books a parcel for an order with a connected carrier (Yurtiçi, Aras, MNG, Sürat, HepsiJet); tracking follows by itself.

Needs integrations:write · changes data

• Canonical address: POST /api/v1/actions/integrations.create_shipment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.shipment_requested

What it writes: carrier_shipment (insert) — The parcel request; the worker books it at the carrier

curl -X POST https://app.getera.io/api/v1/carrier_shipments/actions/create_shipment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"orderId":"SALES_ORDER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.shipment_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.carrierShipments.createShipment({
  orderId: "SALES_ORDER_ID"
})

era carrier_shipments create_shipment \
  --order-id "SALES_ORDER_ID"

{
  "name": "era__integrations__create_shipment",
  "arguments": {
    "orderId": "SALES_ORDER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 order_not_found, no_shipping_account, not_shipping_account, order_not_shippable, shipment_exists, no_address · 429 slow down

integrations.disconnect

Disconnect an app — Stops syncing for good. Orders, products and history stay; the key is removed with the connection itself (apps.disconnect).

Needs integrations:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/integrations.disconnect

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.disconnected

What it writes: integration_account (update) — Marks it disconnected; drops the webhook token

curl -X POST https://app.getera.io/api/v1/integration_accounts/INTEGRATION_ACCOUNT_ID/actions/disconnect \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.disconnected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationAccounts.disconnect("INTEGRATION_ACCOUNT_ID")

era integration_accounts disconnect INTEGRATION_ACCOUNT_ID

{
  "name": "era__integrations__disconnect",
  "arguments": {
    "id": "INTEGRATION_ACCOUNT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_disconnected · 429 slow down

integrations.issue_einvoice

Invoice an order (e-Arşiv / e-Fatura) — Asks the connected e-invoice provider (Paraşüt, Uyumsoft or Logo eLogo) to invoice an order: e-Fatura for a registered taxpayer, e-Arşiv otherwise.

Needs integrations:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/integrations.issue_einvoice

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.einvoice_requested

What it writes: einvoice_document (insert) — The request; the worker sends it to the provider

curl -X POST https://app.getera.io/api/v1/einvoice_documents/actions/issue_einvoice \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"orderId":"SALES_ORDER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.einvoice_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.einvoiceDocuments.issueEinvoice({
  orderId: "SALES_ORDER_ID"
})

era einvoice_documents issue_einvoice \
  --order-id "SALES_ORDER_ID"

{
  "name": "era__integrations__issue_einvoice",
  "arguments": {
    "orderId": "SALES_ORDER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 order_not_found, no_einvoice_account, not_einvoice_account, order_not_invoiceable, already_invoiced · 429 slow down

integrations.map_listing

Tie a listing to a product — Says which Era variant a marketplace listing is, so its orders take stock and Era’s stock reaches it.

Needs integrations:write · changes data

• Canonical address: POST /api/v1/actions/integrations.map_listing

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.listing_mapped

What it writes: channel_listing (update) — Sets (or clears) the variant; the next push sends its stock

curl -X POST https://app.getera.io/api/v1/channel_listings/CHANNEL_LISTING_ID/actions/map_listing \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"itemVariantId":"ITEM_VARIANT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.listing_mapped"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.channelListings.mapListing("CHANNEL_LISTING_ID", {
  itemVariantId: "ITEM_VARIANT_ID"
})

era channel_listings map_listing CHANNEL_LISTING_ID \
  --item-variant-id "ITEM_VARIANT_ID"

{
  "name": "era__integrations__map_listing",
  "arguments": {
    "listingId": "CHANNEL_LISTING_ID",
    "itemVariantId": "ITEM_VARIANT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, variant_not_found · 429 slow down

integrations.publish_listings

Publish product variants to a marketplace — After catalog.set_options and catalog.save_variant, publish the variants to Trendyol. Give each catalogue variant a SKU with catalog.save_variant, then supply variantId, barcode, images and Trendyol category/brand/attribute ids. The SKU keeps the approved listing mapped to the same Era variant. Prices come from the catalogue in minor units. Asynchronous: queued does not mean published; read integrations_status for the batch result.

Needs integrations:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/integrations.publish_listings

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.listing_publish_requested

What it writes: integration_run (insert) — Track the asynchronous publication request

curl -X POST https://app.getera.io/api/v1/integration_runs/actions/publish_listings \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"accountId":"INTEGRATION_ACCOUNT_ID","listings":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.listing_publish_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationRuns.publishListings({
  accountId: "INTEGRATION_ACCOUNT_ID",
  listings: {}
})

era integration_runs publish_listings --data '{"accountId":"INTEGRATION_ACCOUNT_ID","listings":{}}'

{
  "name": "era__integrations__publish_listings",
  "arguments": {
    "accountId": "INTEGRATION_ACCOUNT_ID",
    "listings": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 listing_account_unavailable, invalid_listing_request · 429 slow down

integrations.raise_issue

Raise a sync issue — Something a person has to look at, in Turkish. The same thing again counts up instead of repeating.

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.raise_issue

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.issue_raised

What it writes: integration_issue (upsert) — One open issue per (account, kind, thing)

curl -X POST https://app.getera.io/api/v1/integration_issues/actions/raise_issue \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"accountId":"INTEGRATION_ACCOUNT_ID","kind":"Kind","message":"Message"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.issue_raised"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationIssues.raiseIssue({
  accountId: "INTEGRATION_ACCOUNT_ID",
  kind: "Kind",
  message: "Message"
})

era integration_issues raise_issue \
  --account-id "INTEGRATION_ACCOUNT_ID" \
  --kind "Kind" \
  --message "Message"

{
  "name": "era__integrations__raise_issue",
  "arguments": {
    "accountId": "INTEGRATION_ACCOUNT_ID",
    "kind": "Kind",
    "message": "Message"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, bad_kind · 429 slow down

integrations.record_einvoice

Record an e-invoice answer — What the e-invoice provider did with the request.

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.record_einvoice

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.einvoice_updated

What it writes: einvoice_document (update) — The provider’s answer

curl -X POST https://app.getera.io/api/v1/einvoice_documents/EINVOICE_DOCUMENT_ID/actions/record_einvoice \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"status":"Status"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.einvoice_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.einvoiceDocuments.recordEinvoice("EINVOICE_DOCUMENT_ID", {
  status: "Status"
})

era einvoice_documents record_einvoice EINVOICE_DOCUMENT_ID \
  --status "Status"

{
  "name": "era__integrations__record_einvoice",
  "arguments": {
    "id": "EINVOICE_DOCUMENT_ID",
    "status": "Status"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

integrations.record_inbound

Record a webhook delivery — Each delivery once; an accepted one nudges a sync (its body is never trusted as data).

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.record_inbound

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.webhook_received

What it writes: integration_inbound (insert) — The delivery, deduped on its id

curl -X POST https://app.getera.io/api/v1/integration_inbounds/actions/record_inbound \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"accountId":"INTEGRATION_ACCOUNT_ID","externalId":"Delivery","accepted":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.webhook_received"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationInbounds.recordInbound({
  accountId: "INTEGRATION_ACCOUNT_ID",
  externalId: "Delivery",
  accepted: true
})

era integration_inbounds record_inbound \
  --account-id "INTEGRATION_ACCOUNT_ID" \
  --external-id "Delivery" \
  --accepted true

{
  "name": "era__integrations__record_inbound",
  "arguments": {
    "accountId": "INTEGRATION_ACCOUNT_ID",
    "externalId": "Delivery",
    "accepted": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

integrations.record_review_reply

Record a review reply answer — Whether the review provider published the reply.

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.record_review_reply

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.review_replied

What it writes: integration_review (update) — The provider’s answer

curl -X POST https://app.getera.io/api/v1/integration_reviews/INTEGRATION_REVIEW_ID/actions/record_review_reply \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ok":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.review_replied"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationReviews.recordReviewReply("INTEGRATION_REVIEW_ID", {
  ok: true
})

era integration_reviews record_review_reply INTEGRATION_REVIEW_ID \
  --ok true

{
  "name": "era__integrations__record_review_reply",
  "arguments": {
    "id": "INTEGRATION_REVIEW_ID",
    "ok": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

integrations.record_reviews

Record reviews — The reviews a connected review provider holds now: new ones, edited ones, and replies made outside Era.

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.record_reviews

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.reviews_synced

What it writes: integration_review (insert) — One row per review, updated in place on the next sync

curl -X POST https://app.getera.io/api/v1/integration_reviews/actions/record_reviews \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"accountId":"INTEGRATION_ACCOUNT_ID","reviews":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.reviews_synced"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationReviews.recordReviews({
  accountId: "INTEGRATION_ACCOUNT_ID",
  reviews: {}
})

era integration_reviews record_reviews --data '{"accountId":"INTEGRATION_ACCOUNT_ID","reviews":{}}'

{
  "name": "era__integrations__record_reviews",
  "arguments": {
    "accountId": "INTEGRATION_ACCOUNT_ID",
    "reviews": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, not_reviews_account, invalid_reviews · 429 slow down

integrations.record_run

Record a sync run — Opens a run, or closes it with its counts and one Turkish sentence; moves the account’s cursors and health.

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.record_run

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.run_finished

What it writes: integration_run (upsert) — The run row; integration_account (update) — Last sync times, cursors, health

curl -X POST https://app.getera.io/api/v1/integration_accounts/INTEGRATION_ACCOUNT_ID/actions/record_run \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"runId":"RUN_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.run_finished"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationAccounts.recordRun("INTEGRATION_ACCOUNT_ID", {
  runId: "RUN_ID"
})

era integration_accounts record_run INTEGRATION_ACCOUNT_ID \
  --run-id "RUN_ID"

{
  "name": "era__integrations__record_run",
  "arguments": {
    "accountId": "INTEGRATION_ACCOUNT_ID",
    "runId": "RUN_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

integrations.record_shipment

Record a carrier answer — The carrier’s booking, tracking number, label or latest movement — or its refusal.

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.record_shipment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.shipment_updated

What it writes: carrier_shipment (update) — What the carrier said

curl -X POST https://app.getera.io/api/v1/carrier_shipments/CARRIER_SHIPMENT_ID/actions/record_shipment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"status":"Status"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.shipment_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.carrierShipments.recordShipment("CARRIER_SHIPMENT_ID", {
  status: "Status"
})

era carrier_shipments record_shipment CARRIER_SHIPMENT_ID \
  --status "Status"

{
  "name": "era__integrations__record_shipment",
  "arguments": {
    "id": "CARRIER_SHIPMENT_ID",
    "status": "Status"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

integrations.record_stock_push

Record a stock push — What each listing was told and whether the channel took it.

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.record_stock_push

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.stock_pushed

What it writes: channel_listing (update) — Last pushed quantity, or the refusal; integration_account (update) — Last push time

curl -X POST https://app.getera.io/api/v1/integration_accounts/INTEGRATION_ACCOUNT_ID/actions/record_stock_push \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"results":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.stock_pushed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationAccounts.recordStockPush("INTEGRATION_ACCOUNT_ID", {
  results: {}
})

era integration_accounts record_stock_push INTEGRATION_ACCOUNT_ID --data '{"results":{}}'

{
  "name": "era__integrations__record_stock_push",
  "arguments": {
    "accountId": "INTEGRATION_ACCOUNT_ID",
    "results": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, malformed_results · 429 slow down

integrations.record_test

Record a connection test — Keeps the result of one harmless call to the provider on the account.

Needs integrations:manage · changes data

• Canonical address: POST /api/v1/actions/integrations.record_test

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.tested

What it writes: integration_account (update) — Last test time and result; integration_run (insert) — The test in the run history

curl -X POST https://app.getera.io/api/v1/integration_accounts/INTEGRATION_ACCOUNT_ID/actions/record_test \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ok":true,"message":"What happened"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.tested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationAccounts.recordTest("INTEGRATION_ACCOUNT_ID", {
  ok: true,
  message: "What happened"
})

era integration_accounts record_test INTEGRATION_ACCOUNT_ID \
  --ok true \
  --message "What happened"

{
  "name": "era__integrations__record_test",
  "arguments": {
    "accountId": "INTEGRATION_ACCOUNT_ID",
    "ok": true,
    "message": "What happened"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

integrations.reply_review

Reply to a review — Posts the business’s public reply to a Google review (replaces an earlier reply); sent in the background.

Needs integrations:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/integrations.reply_review

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.review_reply_requested

What it writes: integration_review (update) — Keeps the reply and marks it on its way

curl -X POST https://app.getera.io/api/v1/integration_reviews/INTEGRATION_REVIEW_ID/actions/reply_review \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"text":"Reply"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.review_reply_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationReviews.replyReview("INTEGRATION_REVIEW_ID", {
  text: "Reply"
})

era integration_reviews reply_review INTEGRATION_REVIEW_ID \
  --text "Reply"

{
  "name": "era__integrations__reply_review",
  "arguments": {
    "id": "INTEGRATION_REVIEW_ID",
    "text": "Reply"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, reply_empty, reply_too_long, account_inactive, reply_in_flight · 429 slow down

integrations.request_sync

Sync now — Fetches new orders and products from a marketplace or shop and sends Era’s stock back — in the background, in seconds.

Needs integrations:write · changes data

• Canonical address: POST /api/v1/actions/integrations.request_sync

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.sync_requested

What it writes: integration_run (insert) — The run, which the worker picks up

curl -X POST https://app.getera.io/api/v1/integration_runs/actions/request_sync \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"INTEGRATION_ACCOUNT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.sync_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationRuns.requestSync({
  id: "INTEGRATION_ACCOUNT_ID"
})

era integration_runs request_sync \
  --id "INTEGRATION_ACCOUNT_ID"

{
  "name": "era__integrations__request_sync",
  "arguments": {
    "id": "INTEGRATION_ACCOUNT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, ambiguous_account, not_syncable, disconnected, paused, sync_running · 429 slow down

integrations.resolve_issue

Close a sync issue — Marks it resolved (fixed) or ignored (not a problem).

Needs integrations:write · changes data

• Canonical address: POST /api/v1/actions/integrations.resolve_issue

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.issue_resolved

What it writes: integration_issue (update) — Closes it

curl -X POST https://app.getera.io/api/v1/integration_issues/INTEGRATION_ISSUE_ID/actions/resolve_issue \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"status":"resolved"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.issue_resolved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationIssues.resolveIssue("INTEGRATION_ISSUE_ID", {
  status: "resolved"
})

era integration_issues resolve_issue INTEGRATION_ISSUE_ID \
  --status "resolved"

{
  "name": "era__integrations__resolve_issue",
  "arguments": {
    "id": "INTEGRATION_ISSUE_ID",
    "status": "resolved"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_closed · 429 slow down

integrations.set_paused

Pause or resume syncing — A paused account keeps everything; nothing is fetched or pushed until it is resumed.

Needs integrations:manage · changes data

• Canonical address: POST /api/v1/actions/integrations.set_paused

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.paused, integrations.resumed

What it writes: integration_account (update) — Flips paused / active

curl -X POST https://app.getera.io/api/v1/integration_accounts/INTEGRATION_ACCOUNT_ID/actions/set_paused \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"paused":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.paused",
    "integrations.resumed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationAccounts.setPaused("INTEGRATION_ACCOUNT_ID", {
  paused: true
})

era integration_accounts set_paused INTEGRATION_ACCOUNT_ID \
  --paused true

{
  "name": "era__integrations__set_paused",
  "arguments": {
    "id": "INTEGRATION_ACCOUNT_ID",
    "paused": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, disconnected · 429 slow down

integrations.update_settings

Change what an app syncs — Orders in, products in, stock out, the stock buffer, how far back to look.

Needs integrations:manage · changes data

• Canonical address: POST /api/v1/actions/integrations.update_settings

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.settings_changed

What it writes: integration_account (update) — Merges the settings

curl -X POST https://app.getera.io/api/v1/integration_accounts/INTEGRATION_ACCOUNT_ID/actions/update_settings \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"settings":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.settings_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.integrationAccounts.updateSettings("INTEGRATION_ACCOUNT_ID", {
  settings: {}
})

era integration_accounts update_settings INTEGRATION_ACCOUNT_ID --data '{"settings":{}}'

{
  "name": "era__integrations__update_settings",
  "arguments": {
    "id": "INTEGRATION_ACCOUNT_ID",
    "settings": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, disconnected, bad_setting · 429 slow down

integrations.upsert_listings

Record listings — Stores what a channel sells and ties each listing to an Era variant by SKU, barcode or external key.

Needs integrations:handle · changes data

• Canonical address: POST /api/v1/actions/integrations.upsert_listings

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: integrations.listings_synced

What it writes: channel_listing (upsert) — One row per listing; a match is never undone by a re-read

curl -X POST https://app.getera.io/api/v1/channel_listings/actions/upsert_listings \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"accountId":"INTEGRATION_ACCOUNT_ID","listings":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "integrations.listings_synced"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.channelListings.upsertListings({
  accountId: "INTEGRATION_ACCOUNT_ID",
  listings: {}
})

era channel_listings upsert_listings --data '{"accountId":"INTEGRATION_ACCOUNT_ID","listings":{}}'

{
  "name": "era__integrations__upsert_listings",
  "arguments": {
    "accountId": "INTEGRATION_ACCOUNT_ID",
    "listings": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold integrations:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, malformed_listings · 429 slow down

Data models

CarrierShipment

Table carrier_shipment · Resource carrier_shipments

• GET /api/v1/carrier_shipments
• GET /api/v1/carrier_shipments/{id}

Primary key: id

Unique: account_id, reference

Checks:

• CHECK (((cod_amount IS NULL) OR (cod_amount >= 0)))
• CHECK ((pieces >= 1))
• CHECK ((reference ~ '^[A-Za-z0-9-]{4,40}$'::text))

ChannelListing

Table channel_listing · Resource channel_listings

• GET /api/v1/channel_listings
• GET /api/v1/channel_listings/{id}

Primary key: id

Unique: account_id, external_key

Checks:

• CHECK ((length(external_key) > 0))
• CHECK (((remote_price IS NULL) OR (remote_price >= 0)))

EinvoiceDocument

Table einvoice_document · Resource einvoice_documents

• GET /api/v1/einvoice_documents
• GET /api/v1/einvoice_documents/{id}

Primary key: id

IntegrationAccount

Table integration_account · Resource integration_accounts

• GET /api/v1/integration_accounts
• GET /api/v1/integration_accounts/{id}

Primary key: id

Unique: webhook_token

Checks:

• CHECK ((consecutive_failures >= 0))
• CHECK ((length(TRIM(BOTH FROM label)) > 0))
• CHECK ((provider ~ '^[a-z][a-z0-9_]{1,40}$'::text))

IntegrationInbound

Table integration_inbound · Resource integration_inbounds

• GET /api/v1/integration_inbounds
• GET /api/v1/integration_inbounds/{id}

Primary key: id

Unique: account_id, external_id

IntegrationIssue

Table integration_issue · Resource integration_issues

• GET /api/v1/integration_issues
• GET /api/v1/integration_issues/{id}

Primary key: id

Checks:

• CHECK ((occurrences >= 1))

IntegrationReview

Table integration_review · Resource integration_reviews

• GET /api/v1/integration_reviews
• GET /api/v1/integration_reviews/{id}

Primary key: id

Checks:

• CHECK (((length(external_id) >= 1) AND (length(external_id) <= 500)))
• CHECK ((provider ~ '^[a-z][a-z0-9_]{1,40}$'::text))
• CHECK (((rating >= 1) AND (rating <= 5)))

IntegrationRun

Table integration_run · Resource integration_runs

• GET /api/v1/integration_runs
• GET /api/v1/integration_runs/{id}