Fiscal documents

Sales invoices, credit and debit notes as the tax authority issued them: number, date, tax, annulment and PDF.

Loading the search index…

Fiscal documents

Objects

FiscalDocument

  • idintegerrequired

    ID of the record, unique among records of its kind in the store.

  • typestringrequired

    invoice — 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
  • statusstringrequired

    issued — 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 nullrequired

    Why 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 nullrequired

    ID of the issuing legal entity; null — a document from before sales were split by legal entity: its issuer is the default legal entity.

  • order_idintegerrequired

    ID of the order.

  • refund_idinteger or nullrequired

    ID of the refund the credit note documents; null for other documents.

  • related_document_idinteger or nullrequired

    ID of the invoice the note corrects; null for an invoice.

  • numberstring or nullrequired

    The number as printed on the document, such as 0004-00000013; null until the document is issued.

  • issued_onstring (date) or nullrequired

    Accounting 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 nullrequired

    When the tax authority authorized the document; null until it is issued.

  • currencystringrequired

    Currency of the amounts, an ISO 4217 code: the currency of the store.

  • totalinteger or nullrequired

    Document total including tax; null for documents created before the store kept the total.

  • tax_linesarray of object or nullrequired

    Tax 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
    • regimestringrequired

      Which 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
    • kindstringrequired

      taxed — 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_bpsintegerrequired

      Rate in basis points: 2100 is 21 %.

    • baseintegerrequired

      Base of the tax, without the tax. Prices include tax: base + amount is what the customer paid for this part.

    • amountintegerrequired

      Amount 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 nullrequired

      Province or municipality for taxes that need one (turnover, municipal); otherwise null.

  • annulmentobject or nullrequired

    The 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)required

      When the invoice was annulled.

    • document_idinteger or nullrequired

      ID of the annulling credit note.

    • reasonstring or nullrequired

      Why 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 nullrequired

      The reason in the words of whoever annulled the invoice, for manual; null when the system annulled it.

  • dismissalobject or nullrequired

    The 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)required

      When the document was dismissed.

    • reasonstringrequired

      The reason in the words of whoever dismissed it.

  • receptorobject or null

    Who the document is issued to; null for a retail sale without tax details. Only with the customers:read scope.

    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.

  • arobject or nullrequired

    ARCA 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 nullrequired

      ARCA comprobante type code: 001 — invoice A, 006 — invoice B, 011 — invoice C; 003, 008, 013 — credit notes A, B, C.

    • point_of_saleinteger or nullrequired

      Point of sale (punto de venta).

    • sequence_numberstring or nullrequired

      Sequence number of the document in the point of sale, 8 digits.

    • authorization_kindstringrequired

      CAE — the code was granted when issuing online; CAEA — a code granted in advance, issued in contingency.

      Values:
      CAECAEA
    • authorization_codestring or nullrequired

      Authorization code: CAE or CAEA.

    • authorization_expires_onstring (date) or nullrequired

      Expiry of the authorization code, YYYY-MM-DD; null if unknown.

    • testingbooleanrequired

      true — 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)required

    When the record was created.

  • updated_atstring (date-time)required

    When 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

  • limitinteger

    Page size: up to 250 records; 50 by default.

    Minimum:
    1
    Maximum:
    250
  • cursorstring

    Opaque 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_deletedboolean

    true — 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_idinteger

    Only records of this order.

    Minimum:
    1

Responses

200Success

application/json

  • dataarray of FiscalDocumentrequired

    Records of the page.

  • deletedarray of objectrequired

    Records erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.

    Fields · 2
    • idintegerrequired

      ID of the erased record.

    • deleted_atstring (date-time)required

      When the record was erased.

  • next_cursorstring or nullrequired

    Cursor of the next page; null on the last page.

  • has_morebooleanrequired

    true when there is a next page.

  • sync_cursorstring or nullrequired

    On 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-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

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-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 "https://api.saleya.app/v1/fiscal-documents" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • documentintegerrequired

    ID of the fiscal document.

Responses

200Success

application/json

Returns FiscalDocument

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/fiscal-documents/{document}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • documentintegerrequired

    ID of the fiscal document.

Responses

200Success

application/pdf

string (binary)

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

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

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 "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

  • orderintegerrequired

    ID of the order.

Header

  • Idempotency-Keystringrequired

    Required 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-Replayedstring

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

    Values:
    true
  • Locationstring (uri)required

    Address 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-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

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

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 POST "https://api.saleya.app/v1/orders/{order}/invoice" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324'
Example response · 202
{
  "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

  • documentstringrequired

    ID of the fiscal document.

Header

  • Idempotency-Keystringrequired

    Required 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

  • receptorobject

    Corrected 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_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
  • refresh_receptorboolean

    true — 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-Replayedstring

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

    Values:
    true
  • Locationstring (uri)required

    Address 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-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

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

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 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
Request body — body.json
{
  "receptor": {
    "id_type": "tax_id",
    "id_number": "string",
    "name": "string",
    "tax_status": "registered",
    "address": "string"
  },
  "refresh_receptor": true
}
Example response · 202
{
  "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

  • documentstringrequired

    ID of the fiscal document.

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

Request body application/json

  • reasonstringrequired

    Why 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-Replayedstring

    true 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-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

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

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 POST "https://api.saleya.app/v1/fiscal-documents/{document}/dismiss" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "reason": "string"
}
Example response · 200
{
  "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

  • documentstringrequired

    ID of the fiscal document.

Header

  • Idempotency-Keystringrequired

    Required 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

  • reasonstringrequired

    Why 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-Replayedstring

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

    Values:
    true
  • Locationstring (uri)required

    Address 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-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

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

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 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
Request body — body.json
{
  "reason": "string"
}
Example response · 202
{
  "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"
}