← Platform API v1.32.0

POST /api-client/sales/customers

apiSalesPostCustomers · Sales

Tenant-scoped sales with fresh USER RBAC or API_CLIENT scopes and PUBLIC_API entitlement. Customers require customers.read/write. Orders require sales.read; draft writes require sales.create (machine sales.write) plus pricing.read. Confirmation adds inventory.adjust (machine inventory.write), refreshes current prices, freezes snapshots and reserves all stock/selected unit UUIDs. Completion requires sales.create+inventory.adjust (machine sales.write+inventory.write) and atomically consumes reservations and appends SALE movements; serialized units become SOLD without custody. Cancellation requires sales.cancel+inventory.adjust (machine sales.write+inventory.write) and releases reservations without reversing physical movements. State DRAFT→CONFIRMED→COMPLETED or cancellation before completion; expectedVersion mandatory. Single legal entity, warehouse and price-list currency per order; at most100 distinct lines and100 serial units. Decimal quantities/prices scale6, unrounded commercial totals scale12. All writes require Idempotency-Key; replay is denied after permission/scope/entitlement revocation. Machine pricing accepts public lists and published active variants. No anonymous access, purchase costs/margins, serial identities, payment, tax, invoice, return or UI in the Sales endpoints; cash checkout composes delivery through POS.

Autenticación
PlatformApiKey · http bearer
required-scopes
suppliers.write

Ejemplo

Los valores entre <> y {} son marcadores: sustitúyelos por los tuyos antes de ejecutarlo. 

curl --request POST \
  --url 'https://api.marky.ec/v1/api-client/sales/customers' \
  --header 'Authorization: Bearer <PlatformApiKey>' \
  --header 'Idempotency-Key: <Idempotency-Key>' \
  --header 'Content-Type: application/json' \
  --data @body.json

Parámetros

Nombre En Tipo Descripción
Idempotency-Keyobligatorio header stringformato uuid UUIDv4/v7; replay24h under fresh authorization, input fingerprint bound to aggregate ID.

Cuerpo (obligatorio)

application/json
CustomerInput
objectsin otras propiedades
  • codeobligatorio
    stringpatrón ^[a-zA-Z][a-zA-Z0-9_.-]*$longitud mín. 1longitud máx. 64
  • nameobligatorio
    stringlongitud mín. 1longitud máx. 200
  • taxId
    string | nulllongitud máx. 64
  • email
    string | nulllongitud máx. 254
  • phone
    string | nulllongitud máx. 64
  • address
    string | nulllongitud máx. 1000

    Free text of up to 1000 characters. May hold several lines (CRLF is stored as LF); any other control character is refused.

  • profile
    ContactProfileInput
    object | nullsin otras propiedades

    Extended record (CONTACTS-1), replaced whole when sent: a key left out or null is not stated. Null or {} clears it. Left out of an update, the stored profile is kept; left out of a creation, the profile starts empty. Strings are trimmed and never blank; unknown keys are refused.

    • contactType
      string | nulluno de "COMPANY", "PERSON", null
    • companyName
      string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200

      Legal name.

    • tradeName
      string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200
    • taxIdType
      string | nulluno de "RUC", "CEDULA", "PASSPORT", "OTHER", null

      What the taxId of the record is.

    • taxIdTypeOther
      string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 40

      Names the identification. Accepted only with taxIdType OTHER.

    • website
      string | nullpatrón ^[hH][tT][tT][pP][sS]?://[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?(:[0-9]{1,5})?([/?#][^\s\\]*)?$longitud máx. 500

      http or https only, with a host and without credentials.

    • mobile
      string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
    • language
      string | nulluno de "es", "en", "pt", "fr", "other", null
    • primaryContact
      object | nullsin otras propiedades

      The person the record is addressed to. Their email and phone are the email and phone of the record.

      • salutation
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 20
      • firstName
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • lastName
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • jobTitle
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • department
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
    • billingAddress
      object | nullsin otras propiedades
      • attention
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200
      • countryCode
        string | nullpatrón ^[A-Za-z]{2}$

        ISO 3166-1 alpha-2. Stored in capitals.

      • state
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • city
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • street1
        string | nullpatrón ^[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*\S[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200

        May hold several lines.

      • street2
        string | nullpatrón ^[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*\S[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200

        May hold several lines.

      • postalCode
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 20
      • phone
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
    • shippingAddress
      object | nullsin otras propiedades

      Its own values: it is never linked to the billing address.

      • attention
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200
      • countryCode
        string | nullpatrón ^[A-Za-z]{2}$

        ISO 3166-1 alpha-2. Stored in capitals.

      • state
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • city
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • street1
        string | nullpatrón ^[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*\S[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200

        May hold several lines.

      • street2
        string | nullpatrón ^[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*\S[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200

        May hold several lines.

      • postalCode
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 20
      • phone
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
    • contactPersons
      array | nullelementos máx. 20

      Further people, at most 20. Written, each one states at least one value.

      Cada elemento
      objectpropiedades mín. 1sin otras propiedades
      • firstName
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • lastName
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • jobTitle
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • department
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • email
        string | nullpatrón ^[^\s@]+@[^\s@]+\.[^\s@]+$longitud máx. 254
      • phone
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
      • mobile
        string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
    • currencyCode
      string | nullpatrón ^[a-zA-Z]{3}$

      Preferred ISO 4217 currency among the supported ones, stored in capitals. Documents keep stating their own.

    • paymentTermsDays
      integer | nullmín. 0máx. 3650

      Informative: no due date, credit or charge is derived from it.

    • notes
      string | nullpatrón ^[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*\S[^\u0000-\u0009\u000b-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 4000

      May hold several lines.

    • tags
      array | nullelementos máx. 20

      At most 20, unique without regard to case.

      Cada elemento
      stringpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 40
    • customFields
      array | nullelementos máx. 20

      At most 20 name/value pairs with unique names.

      Cada elemento
      objectsin otras propiedades
      • nameobligatorio
        stringpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
      • valueobligatorio
        stringpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 500

Respuestas

201 Success
  • Cache-Controlvalor fijo "no-store"
application/json
CustomerReceipt
objectsin otras propiedades
  • idobligatorio
    stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
  • statusobligatorio
    stringuno de "ACTIVE", "ARCHIVED"
  • createdAtobligatorio
    stringformato date-time
  • updatedAtobligatorio
    stringformato date-time
400 Invalid request
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

401 Missing or invalid access token
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

403 Identity, membership or permission denied
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

404 Unknown resource
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

409 Duplicate permanent identity/IMEI, stale unit version, reserved/illegal unit state, custody/legal entity constraint or idempotency conflict.
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

413 Payload too large
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

429 Per-minute rate or monthly quota exceeded; authenticated API clients require PUBLIC_API entitlement.
  • Retry-Afterintegermín. 1 Seconds before retrying; quota reset is UTC next month.
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

500 Internal failure
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

503 Auth/database/governance unavailable; no memory fallback for Redis.
application/problem+json
ProblemDetails
objectsin otras propiedades
  • typeobligatorio
    valor fijo "about:blank"
  • statusobligatorio
    integer
  • codeobligatorio
    string
  • titleobligatorio
    string
  • detailobligatorio
    string
  • requestIdobligatorio
    stringformato uuid
  • errors
    arrayelementos máx. 200

    Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.

    Cada elemento
    objectsin otras propiedades
    • pointerobligatorio
      string
    • codeobligatorio
      string
    • required
      integermín. 0máx. 1000

      For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.

    • identified
      integermín. 0máx. 1000

      For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.