← Platform API v1.32.0

GET /api-client/sales/customers

apiSalesGetCustomers · 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.read

Ejemplo

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

curl --request GET \
  --url 'https://api.marky.ec/v1/api-client/sales/customers' \
  --header 'Authorization: Bearer <PlatformApiKey>'

Parámetros

Nombre En Tipo Descripción
limit query integermín. 1máx. 100por defecto 50
cursor query 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}$
status query stringuno de "ACTIVE", "ARCHIVED"por defecto ACTIVE

Respuestas

200 Success
  • Cache-Controlvalor fijo "no-store"
application/json
CustomerPage
objectsin otras propiedades
  • itemsobligatorio
    arrayelementos máx. 100
    Cada elemento
    Customer
    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
    • taxIdobligatorio
      string | nulllongitud máx. 64
    • emailobligatorio
      string | nulllongitud máx. 254
    • phoneobligatorio
      string | nulllongitud máx. 64
    • addressobligatorio
      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.

    • 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
    • profileobligatorio
      ContactProfile
      objectsin otras propiedades

      Extended record (CONTACTS-1), always whole: null or an empty list where nothing was stated. Descriptive only: it grants no credit and computes no charge or tax.

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

        Legal name.

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

        What the taxId of the record is.

      • taxIdTypeOtherobligatorio
        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.

      • websiteobligatorio
        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.

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

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

        • salutationobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 20
        • firstNameobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • lastNameobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • jobTitleobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • departmentobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
      • billingAddressobligatorio
        objectsin otras propiedades
        • attentionobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 200
        • countryCodeobligatorio
          string | nullpatrón ^[A-Za-z]{2}$

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

        • stateobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • cityobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • street1obligatorio
          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.

        • street2obligatorio
          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.

        • postalCodeobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 20
        • phoneobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
      • shippingAddressobligatorio
        objectsin otras propiedades

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

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

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

        • stateobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • cityobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • street1obligatorio
          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.

        • street2obligatorio
          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.

        • postalCodeobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 20
        • phoneobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
      • contactPersonsobligatorio
        arrayelementos máx. 20

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

        Cada elemento
        objectsin otras propiedades
        • firstNameobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • lastNameobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • jobTitleobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • departmentobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 100
        • emailobligatorio
          string | nullpatrón ^[^\s@]+@[^\s@]+\.[^\s@]+$longitud máx. 254
        • phoneobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
        • mobileobligatorio
          string | nullpatrón ^[^\u0000-\u001f\u007f-\u009f]*\S[^\u0000-\u001f\u007f-\u009f]*$longitud mín. 1longitud máx. 64
      • currencyCodeobligatorio
        string | nullpatrón ^[a-zA-Z]{3}$

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

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

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

      • notesobligatorio
        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.

      • tagsobligatorio
        arrayelementos 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
      • customFieldsobligatorio
        arrayelementos 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
  • nextCursorobligatorio
    string | nullformato 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}$
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.