Customer tax details
Tax details of a customer: receipts and invoices of new orders of the customer are issued under them.
Customer tax details
Objects
CustomerFiscalProfile
customer_idintegerrequiredID of the customer.
receptorobject or nullrequiredTax 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_typestringrequiredKind 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 nullrequiredNumber of the ID; null when id_type is none.
namestring or nullrequiredLegal or full name for the document; null when not given.
tax_statusstringrequiredTax 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 nullrequiredFiscal 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
customerintegerrequiredID of the customer.
Responses
200Success
Headers
ETagstringrequiredVersion 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-AuthenticatestringrequiredAuthentication 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-AuthenticatestringAuthentication 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-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds 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
curl "https://api.saleya.app/v1/customers/{customer}/fiscal-profile" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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
customerintegerrequiredID of the customer.
Header
Idempotency-KeystringUnique 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-MatchstringrequiredETag 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 nullrequiredTax 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_typestringKind 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 nullNumber of the ID; null when id_type is none.
- Max length:
- 32
namestring or nullLegal or full name for the document; null when not given.
- Max length:
- 255
tax_statusstringTax 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 nullFiscal address in one line; null when not given.
- Max length:
- 255
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion 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-AuthenticatestringrequiredAuthentication 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-AuthenticatestringAuthentication 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-AfterintegerSeconds 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-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
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{
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
}
}{
"customer_id": 0,
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
}
}