Fiscal documents
Sales invoices, credit and debit notes as the tax authority issued them: number, date, tax, annulment and PDF.
Fiscal documents
Objects
FiscalDocument
idintegerrequiredID of the record, unique among records of its kind in the store.
typestringrequiredinvoice — sales invoice; credit_note — credit note: a refund, an order decrease or an invoice annulment; debit_note — debit note: an order increase after the invoice.
- Values:
invoicecredit_notedebit_note
statusstringrequiredissued — authorized by the tax authority; pending — waiting to be issued; failed — issuing failed and is retried automatically; rejected — refused by the tax authority, the data needs fixing; voided — issuing cancelled with the sale, no legal trace.
- Values:
pendingissuedrejectedfailedvoided
status_reasonmap of string or nullrequiredWhy the document is in this status (tax authority refusal, failure or cancellation) in the store languages; null for issued and pending documents.
legal_entity_idinteger or nullrequiredID of the issuing legal entity; null — a document from before sales were split by legal entity: its issuer is the default legal entity.
order_idintegerrequiredID of the order.
refund_idinteger or nullrequiredID of the refund the credit note documents; null for other documents.
numberstring or nullrequiredThe number as printed on the document, such as 0004-00000013; null until the document is issued.
issued_onstring (date) or nullrequiredAccounting date of the document, YYYY-MM-DD in the store time zone: it puts the document into a tax period. null until the document is issued.
issued_atstring (date-time) or nullrequiredWhen the tax authority authorized the document; null until it is issued.
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
totalinteger or nullrequiredDocument total including tax; null for documents created before the store kept the total.
tax_linesarray of object or nullrequiredTax authorized by the tax authority, the legally binding one: the regime of the issuing legal entity sets it, and it may differ from the order tax. null if the document is not issued, does not itemize tax (a monotributo invoice C) or the breakdown cannot be restored.
Fields · 6
regimestringrequiredWhich tax: vat — value added tax (IVA); income — income tax; turnover — gross receipts tax (Ingresos Brutos); municipal — a municipal levy; internal — excise; social — social security; other. Tax of a sale is vat: the tax class of a product classifies value added tax.
- Values:
vatincometurnovermunicipalinternalsocialother
kindstringrequiredtaxed — at the rate; exempt — exempt by law; untaxed — outside the scope of the tax. exempt and untaxed lines have rate_bps 0 and amount 0: the amount is in base.
- Values:
taxedexemptuntaxed
rate_bpsintegerrequiredRate in basis points: 2100 is 21 %.
baseintegerrequiredBase of the tax, without the tax. Prices include tax: base + amount is what the customer paid for this part.
amountintegerrequiredAmount of the tax. The tax of a sale is calculated per rate for the whole order, the base rounded to the nearest unit and the tax as the rest; items and delivery get shares of it, so their lines add up to the line of the order.
jurisdictionstring or nullrequiredProvince or municipality for taxes that need one (turnover, municipal); otherwise null.
annulmentobject or nullrequiredThe invoice is annulled by a note: it stays with the tax authority but no longer counts for the sale. null if not annulled.
Fields · 4
annulled_atstring (date-time)requiredWhen the invoice was annulled.
document_idinteger or nullrequiredID of the annulling credit note.
reasonstring or nullrequiredWhy it was annulled: order_cancelled — the sale was cancelled; advance_applied — a booking advance was applied to the check, and the check invoice documents it; manual — a decision of a person or an app, the reason in words is in comment. null when the annulling note is not found.
- Values:
order_cancelledadvance_appliedmanualnull
commentstring or nullrequiredThe reason in the words of whoever annulled the invoice, for manual; null when the system annulled it.
dismissalobject or nullrequiredThe document is dismissed: the tax authority rejected it (or refused its CAEA reporting), and it will not be issued. The document status does not change. null when not dismissed.
Fields · 2
dismissed_atstring (date-time)requiredWhen the document was dismissed.
reasonstringrequiredThe reason in the words of whoever dismissed it.
receptorobject or nullWho the document is issued to; null for a retail sale without tax details. Only with the customers:read scope.
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.
arobject or nullrequiredARCA details; null for a store in another country, for a document not issued yet and when the details cannot be restored from what the provider kept.
Fields · 7
document_type_codestring or nullrequiredARCA comprobante type code: 001 — invoice A, 006 — invoice B, 011 — invoice C; 003, 008, 013 — credit notes A, B, C.
point_of_saleinteger or nullrequiredPoint of sale (punto de venta).
sequence_numberstring or nullrequiredSequence number of the document in the point of sale, 8 digits.
authorization_kindstringrequiredCAE — the code was granted when issuing online; CAEA — a code granted in advance, issued in contingency.
- Values:
CAECAEA
authorization_codestring or nullrequiredAuthorization code: CAE or CAEA.
authorization_expires_onstring (date) or nullrequiredExpiry of the authorization code, YYYY-MM-DD; null if unknown.
testingbooleanrequiredtrue — issued by the ARCA testing environment (homologación): the document has no legal effect and must not be booked as a sale.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
List fiscal documents changed since a given moment: invoices, credit and debit notes in every status
get/fiscal-documents
Scope: fiscal:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
order_idintegerOnly records of this order.
- Minimum:
- 1
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
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
410The sync cursor is older than the deletion retention period or was issued before the database was restored
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
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
curl "https://api.saleya.app/v1/fiscal-documents" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"type": "invoice",
"status": "pending",
"status_reason": {
"key": "string"
},
"legal_entity_id": 0,
"order_id": 0,
"refund_id": 0,
"related_document_id": 0,
"number": "string",
"issued_on": "2026-01-15",
"issued_at": "2026-01-15T12:00:00Z",
"currency": "string",
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"annulment": {
"annulled_at": "2026-01-15T12:00:00Z",
"document_id": 0,
"reason": "order_cancelled",
"comment": "string"
},
"dismissal": {
"dismissed_at": "2026-01-15T12:00:00Z",
"reason": "string"
},
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"ar": {
"document_type_code": "string",
"point_of_sale": 0,
"sequence_number": "string",
"authorization_kind": "CAE",
"authorization_code": "string",
"authorization_expires_on": "2026-01-15",
"testing": true
},
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Get a fiscal document
get/fiscal-documents/{document}
Scope: fiscal:read
Parameters
Path
documentintegerrequiredID of the fiscal document.
Responses
200Success
application/json
Returns FiscalDocument
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/fiscal-documents/{document}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"type": "invoice",
"status": "pending",
"status_reason": {
"key": "string"
},
"legal_entity_id": 0,
"order_id": 0,
"refund_id": 0,
"related_document_id": 0,
"number": "string",
"issued_on": "2026-01-15",
"issued_at": "2026-01-15T12:00:00Z",
"currency": "string",
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"annulment": {
"annulled_at": "2026-01-15T12:00:00Z",
"document_id": 0,
"reason": "order_cancelled",
"comment": "string"
},
"dismissal": {
"dismissed_at": "2026-01-15T12:00:00Z",
"reason": "string"
},
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"ar": {
"document_type_code": "string",
"point_of_sale": 0,
"sequence_number": "string",
"authorization_kind": "CAE",
"authorization_code": "string",
"authorization_expires_on": "2026-01-15",
"testing": true
},
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Download the PDF of a fiscal document, the same file the customer receives
get/fiscal-documents/{document}/pdf
Scope: fiscal:read
Parameters
Path
documentintegerrequiredID of the fiscal document.
Responses
200Success
application/pdf
string (binary)
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
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
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
curl "https://api.saleya.app/v1/fiscal-documents/{document}/pdf" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"Issue the invoice of a closed sale: issuing runs in the background, the outcome comes as an event
post/orders/{order}/invoice
Scope: fiscal:write
Parameters
Path
orderintegerrequiredID of the order.
Header
Idempotency-KeystringrequiredRequired key of the attempt, for example a UUID: a duplicate of this command with the tax authority cannot be undone. A retry with the same key and body gets the saved response. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Responses
202Accepted: the outcome is at the Location URL
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns FiscalDocument
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
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
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
invoice_issue_refusedThe order invoice can't be issued now - 422
idempotency_key_requiredIdempotency key is required - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
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 POST "https://api.saleya.app/v1/orders/{order}/invoice" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324'{
"id": 0,
"type": "invoice",
"status": "pending",
"status_reason": {
"key": "string"
},
"legal_entity_id": 0,
"order_id": 0,
"refund_id": 0,
"related_document_id": 0,
"number": "string",
"issued_on": "2026-01-15",
"issued_at": "2026-01-15T12:00:00Z",
"currency": "string",
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"annulment": {
"annulled_at": "2026-01-15T12:00:00Z",
"document_id": 0,
"reason": "order_cancelled",
"comment": "string"
},
"dismissal": {
"dismissed_at": "2026-01-15T12:00:00Z",
"reason": "string"
},
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"ar": {
"document_type_code": "string",
"point_of_sale": 0,
"sequence_number": "string",
"authorization_kind": "CAE",
"authorization_code": "string",
"authorization_expires_on": "2026-01-15",
"testing": true
},
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Reissue a document after a failure or a rejection by the tax authority
post/fiscal-documents/{document}/reissue
Scope: fiscal:write
Parameters
Path
documentstringrequiredID of the fiscal document.
Header
Idempotency-KeystringrequiredRequired key of the attempt, for example a UUID: a duplicate of this command with the tax authority cannot be undone. A retry with the same key and body gets the saved response. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
receptorobjectCorrected recipient details of a rejected invoice; they also replace the details of the order. Invoices only: notes inherit the recipient of their invoice. Leave it out when the details do not change.
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
refresh_receptorbooleantrue — read the details again from the current tax profile of the order customer (PUT /v1/customers/{customer}/fiscal-profile). Not together with receptor.
Responses
202Accepted: the outcome is at the Location URL
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns FiscalDocument
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
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
Errors of this endpoint
- 409
fiscal_document_reissue_refusedThe document can't be reissued - 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_requiredIdempotency key is required - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
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 POST "https://api.saleya.app/v1/fiscal-documents/{document}/reissue" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
-H "Content-Type: application/json" \
-d @body.json{
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"refresh_receptor": true
}{
"id": 0,
"type": "invoice",
"status": "pending",
"status_reason": {
"key": "string"
},
"legal_entity_id": 0,
"order_id": 0,
"refund_id": 0,
"related_document_id": 0,
"number": "string",
"issued_on": "2026-01-15",
"issued_at": "2026-01-15T12:00:00Z",
"currency": "string",
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"annulment": {
"annulled_at": "2026-01-15T12:00:00Z",
"document_id": 0,
"reason": "order_cancelled",
"comment": "string"
},
"dismissal": {
"dismissed_at": "2026-01-15T12:00:00Z",
"reason": "string"
},
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"ar": {
"document_type_code": "string",
"point_of_sale": 0,
"sequence_number": "string",
"authorization_kind": "CAE",
"authorization_code": "string",
"authorization_expires_on": "2026-01-15",
"testing": true
},
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Dismiss a rejected document: it will not be issued
post/fiscal-documents/{document}/dismiss
Scope: fiscal:write
Parameters
Path
documentstringrequiredID of the fiscal document.
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
Request body application/json
reasonstringrequiredWhy the document will not be issued, in your own words, 3 to 500 characters: a tax audit will ask for it.
- Min length:
- 3
- Max length:
- 500
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns FiscalDocument
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
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
Errors of this endpoint
- 409
fiscal_document_dismiss_refusedThe document can't be dismissed - 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
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 POST "https://api.saleya.app/v1/fiscal-documents/{document}/dismiss" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"reason": "string"
}{
"id": 0,
"type": "invoice",
"status": "pending",
"status_reason": {
"key": "string"
},
"legal_entity_id": 0,
"order_id": 0,
"refund_id": 0,
"related_document_id": 0,
"number": "string",
"issued_on": "2026-01-15",
"issued_at": "2026-01-15T12:00:00Z",
"currency": "string",
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"annulment": {
"annulled_at": "2026-01-15T12:00:00Z",
"document_id": 0,
"reason": "order_cancelled",
"comment": "string"
},
"dismissal": {
"dismissed_at": "2026-01-15T12:00:00Z",
"reason": "string"
},
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"ar": {
"document_type_code": "string",
"point_of_sale": 0,
"sequence_number": "string",
"authorization_kind": "CAE",
"authorization_code": "string",
"authorization_expires_on": "2026-01-15",
"testing": true
},
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Annul an issued invoice with a credit note
post/fiscal-documents/{document}/annul
Scope: fiscal:annul
Parameters
Path
documentstringrequiredID of the fiscal document.
Header
Idempotency-KeystringrequiredRequired key of the attempt, for example a UUID: a duplicate of this command with the tax authority cannot be undone. A retry with the same key and body gets the saved response. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
reasonstringrequiredWhy the invoice is annulled, in your own words, 3 to 500 characters: it goes to the annulling note and the order history.
- Min length:
- 3
- Max length:
- 500
Responses
202Accepted: the outcome is at the Location URL
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns FiscalDocument
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
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
Errors of this endpoint
- 409
fiscal_document_annul_refusedThe invoice can't be annulled - 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_requiredIdempotency key is required - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
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 POST "https://api.saleya.app/v1/fiscal-documents/{document}/annul" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
-H "Content-Type: application/json" \
-d @body.json{
"reason": "string"
}{
"id": 0,
"type": "invoice",
"status": "pending",
"status_reason": {
"key": "string"
},
"legal_entity_id": 0,
"order_id": 0,
"refund_id": 0,
"related_document_id": 0,
"number": "string",
"issued_on": "2026-01-15",
"issued_at": "2026-01-15T12:00:00Z",
"currency": "string",
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"annulment": {
"annulled_at": "2026-01-15T12:00:00Z",
"document_id": 0,
"reason": "order_cancelled",
"comment": "string"
},
"dismissal": {
"dismissed_at": "2026-01-15T12:00:00Z",
"reason": "string"
},
"receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"ar": {
"document_type_code": "string",
"point_of_sale": 0,
"sequence_number": "string",
"authorization_kind": "CAE",
"authorization_code": "string",
"authorization_expires_on": "2026-01-15",
"testing": true
},
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}