Customer tax details

Tax details of a customer: receipts and invoices of new orders of the customer are issued under them.

Loading the search index…

Customer tax details

Objects

CustomerFiscalProfile

  • customer_idintegerrequired

    ID of the customer.

  • receptorobject or nullrequired

    Tax details documents of new orders are issued under; null — a retail customer without tax details. A placed order keeps its own copy (fiscal_receptor of the order).

    Fields · 5
    • id_typestringrequired

      Kind of ID: tax_id — tax ID of a business (CUIT in Argentina); personal_id — tax ID of a person (CUIL); national_id — national identity document (DNI); passport; none — no ID.

      Values:
      tax_idpersonal_idnational_idpassportnone
    • id_numberstring or nullrequired

      Number of the ID; null when id_type is none.

    • namestring or nullrequired

      Legal or full name for the document; null when not given.

    • tax_statusstringrequired

      Tax status: registered — registered for VAT (Responsable Inscripto in Argentina); small_taxpayer — a simplified regime (Monotributo); exempt — exempt from VAT; final_consumer — a final consumer; not_categorized — not categorized; foreign — a foreign customer.

      Values:
      registeredsmall_taxpayerexemptfinal_consumernot_categorizedforeign
    • addressstring or nullrequired

      Fiscal address in one line; null when not given.

Endpoints

Get a customer's tax details

get/customers/{customer}/fiscal-profile

Scope: customers:read

Parameters

Path

  • customerintegerrequired

    ID of the customer.

Responses

200Success

Headers

  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"

application/json

Returns CustomerFiscalProfile

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

404The object does not exist or is not available to the app

application/problem+json

Returns Problem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl "https://api.saleya.app/v1/customers/{customer}/fiscal-profile" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "customer_id": 0,
  "receptor": {
    "id_type": "tax_id",
    "id_number": "string",
    "name": "string",
    "tax_status": "registered",
    "address": "string"
  }
}

Replace a customer's tax details; null makes them a retail customer

put/customers/{customer}/fiscal-profile

Scope: customers:write

Parameters

Path

  • customerintegerrequired

    ID of the customer.

Header

  • Idempotency-Keystring

    Unique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.

    Min length:
    1
    Max length:
    255
    Example:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstringrequired

    ETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.

    Example:
    "7"

Request body application/json

  • receptorobject or nullrequired

    Tax details documents of new orders are issued under; null — a retail customer without tax details. A placed order keeps its own copy (fiscal_receptor of the order).

    Fields · 5
    • id_typestring

      Kind of ID: tax_id — tax ID of a business (CUIT in Argentina); personal_id — tax ID of a person (CUIL); national_id — national identity document (DNI); passport; none — no ID.

      Values:
      tax_idpersonal_idnational_idpassportnone
    • id_numberstring or null

      Number of the ID; null when id_type is none.

      Max length:
      32
    • namestring or null

      Legal or full name for the document; null when not given.

      Max length:
      255
    • tax_statusstring

      Tax status: registered — registered for VAT (Responsable Inscripto in Argentina); small_taxpayer — a simplified regime (Monotributo); exempt — exempt from VAT; final_consumer — a final consumer; not_categorized — not categorized; foreign — a foreign customer.

      Values:
      registeredsmall_taxpayerexemptfinal_consumernot_categorizedforeign
    • addressstring or null

      Fiscal address in one line; null when not given.

      Max length:
      255

Responses

200Success

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"

application/json

Returns CustomerFiscalProfile

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

404The object does not exist or is not available to the app

application/problem+json

Returns Problem

409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns ConflictProblem

412The record changed after it was read: the version in If-Match is not current

application/problem+json

Returns Problem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

428The request needs If-Match with the ETag of the record

application/problem+json

Returns Problem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl -X PUT "https://api.saleya.app/v1/customers/{customer}/fiscal-profile" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "receptor": {
    "id_type": "tax_id",
    "id_number": "string",
    "name": "string",
    "tax_status": "registered",
    "address": "string"
  }
}
Example response · 200
{
  "customer_id": 0,
  "receptor": {
    "id_type": "tax_id",
    "id_number": "string",
    "name": "string",
    "tax_status": "registered",
    "address": "string"
  }
}