Tring for developers עברית

API reference

Generated from openapi.json, which holds every field and answer. Base address: https://sandbox.tring.co.il for the sandbox. Every request carries Authorization: Bearer <key>.

Businesses

The businesses of this client

http
GET /v1/issuers
SDK
JavaScripttring.listIssuers()
Pythontring.list_issuers()
Key scoperead
Parameterslimit, cursor
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Every business that gives this client a standing grant, and every business this client added that is still "invited".

Add a business

http
POST /v1/issuers
SDK
JavaScripttring.createIssuer()
Pythontring.create_issuer()
Key scopebusinesses
BodyCreateIssuerRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, ISSUER_ALREADY_EXISTS 409, ISSUER_REGISTERED 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Adds a business with its details. It joins as "invited" and can issue nothing. Its owner then activates it in the product's own portal and gives this client permission to act for it; until then every issuing call for it answers 404. Sending the same request again returns the same business ("replayed": true); the same registration number with other details, or a business this client already acts for, answers ISSUER_ALREADY_EXISTS. One registration number is one business, whoever adds it: when the register already holds the number for a business this client may not act for, nothing is added, the answer is ISSUER_REGISTERED, and the owner of that business is asked in the portal to give this client permission. Text is cleaned of invisible characters and repeated spaces before it is stored.

One business

http
GET /v1/issuers/{issuerId}
SDK
JavaScripttring.getIssuer()
Pythontring.get_issuer()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The business with the version of its details in force today. "status" and "granted" say whether documents can be issued for it.

The design of the business's documents

http
GET /v1/issuers/{issuerId}/design
SDK
JavaScripttring.getDocumentDesign()
Pythontring.get_document_design()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The template, accent colour, typeface and line of the business that its next document is printed with. The elements the law asks a document to show are printed by the service in every template and are not part of a design.

Choose the design of the business's documents

http
PUT /v1/issuers/{issuerId}/design
SDK
JavaScripttring.putDocumentDesign()
Pythontring.put_document_design()
Key scopebusinesses
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, DESIGN_REFUSED 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Stores the design as a new version. It applies to the documents produced after it; a document already issued keeps the design it was produced with, in every copy. Sending the design in force stores nothing and answers it with "created": false. A design that cannot be stored answers DESIGN_REFUSED, and details name the field and the reason ("unknown", "format", "contrast" with a "suggestion", "too-long", "reserved-word" with the "word", "mixed-word" for a Latin letter, digit or symbol between two Hebrew letters, "character", "long-number").

Issuing

Prepare a document

http
POST /v1/issuers/{issuerId}/drafts
SDK
JavaScripttring.prepareDraft()
Pythontring.prepare_draft()
Key scopeissue
ParametersIdempotency-Key (required)
BodyPrepareRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, IDEMPOTENCY_KEY_REUSED 409, ISSUER_NOT_ACTIVE 409, DRAFT_ABANDONED 410, DRAFT_EXPIRED 410, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, DOCUMENT_REFUSED 422, IDEMPOTENCY_KEY_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, REGISTRATION_NOT_IN_FORCE 503, UNAVAILABLE 503

Step one of two. The server validates the request, computes every amount and stores a pending draft that expires. Nothing is issued and no number is taken. The answer is the computed document and its warnings: show it, or its preview, before confirming.

Read a draft

http
GET /v1/drafts/{draftId}
SDK
JavaScripttring.getDraft()
Pythontring.get_draft()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, DRAFT_CORRUPT 500, INTERNAL 500, UNAVAILABLE 503

A draft this client prepared, in whatever state it is. A draft that became a document names it in "documentId".

The preview of a draft, as a PDF

http
GET /v1/drafts/{draftId}/preview
SDK
JavaScripttring.previewDraft()
Pythontring.preview_draft()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, DRAFT_CONFIRMED 409, DRAFT_STALE 409, ISSUER_NOT_ACTIVE 409, DRAFT_ABANDONED 410, DRAFT_EXPIRED 410, RATE_LIMITED 429, DRAFT_CORRUPT 500, INTERNAL 500, RENDER_FAILED 500, UNAVAILABLE 503

The page the document would be, marked "טיוטה", with no number [DOC-05]. It is not a document, is not signed and is never stored. Only a pending draft has a preview.

Confirm a draft: issue the document

http
POST /v1/drafts/{draftId}/confirm
SDK
JavaScripttring.confirmDraft()
Pythontring.confirm_draft()
Key scopeissue
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, DRAFT_STALE 409, ISSUER_NOT_ACTIVE 409, DRAFT_ABANDONED 410, DRAFT_EXPIRED 410, DOCUMENT_REFUSED 422, RATE_LIMITED 429, COUNTER_MISSING 500, DATABASE_REFUSED 500, DRAFT_CORRUPT 500, INTERNAL 500, RENDER_FAILED 500, SIGNATURE_NOT_VERIFIED 500, SIGNING_FAILED 500, SIGNING_KEY_UNAVAILABLE 500, ISSUE_TIMEOUT 503, REGISTRATION_NOT_IN_FORCE 503, UNAVAILABLE 503, OUTCOME_UNKNOWN 504

Step two of two, and the only call that issues. In one transaction the draft becomes a document: it takes the next number of its series, its original is rendered, signed with the key of the business and stored. The request has no body.

Documents

The documents of a business

http
GET /v1/issuers/{issuerId}/documents
SDK
JavaScripttring.listDocuments()
Pythontring.list_documents()
Key scoperead
Parameterslimit, cursor, from, to, docType, customerKey, number
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Issued documents, newest first by record number. Every filter is optional; they narrow together. Each call is written to the audit log of the business.

One document

http
GET /v1/documents/{documentId}
SDK
JavaScripttring.getDocument()
Pythontring.get_document()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The document as the permanent file holds it. Each read is written to the audit log of the business.

The file of a document, as a PDF

http
GET /v1/documents/{documentId}/pdf
SDK
JavaScripttring.downloadDocument()
Pythontring.download_document()
Key scoperead
Parametersform
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, REQUEST_INVALID 422, RATE_LIMITED 429, DATABASE_REFUSED 500, INTERNAL 500, RENDER_FAILED 500, SIGNATURE_NOT_VERIFIED 500, SIGNING_FAILED 500, SIGNING_KEY_UNAVAILABLE 500, DELIVER_TIMEOUT 503, UNAVAILABLE 503, OUTCOME_UNKNOWN 504

A client system is handed a "העתק" (copy) of the document, or the "מבוטל" view of a cancelled one, signed with the key of the business. It is never handed the "מקור": the original leaves once, to the customer, through a link or on paper. "form" chooses the computerized form (default) or the paper form, for printing.

Record the allocation number of a tax invoice

http
POST /v1/documents/{documentId}/allocation-number
SDK
JavaScripttring.recordAllocationNumber()
Pythontring.record_allocation_number()
Key scopeissue
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, DOCUMENT_CANCELLED 410, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, DATABASE_REFUSED 500, INTERNAL 500, DELIVER_TIMEOUT 503, UNAVAILABLE 503, OUTCOME_UNKNOWN 504

The business obtained an allocation number from the Tax Authority itself and the client system passes it on [ALC-05, ALC-06]. This service does not ask the Authority for a number. The number is recorded once, beside the document, and the document itself does not change: every copy rendered from then on prints it under "הקצאה מספר:", and so does the "מקור" while it has not left the business [ALC-08]. A document of type 305, 320 or 330 takes a number; a receipt and a transaction invoice never do.

Delivery

http
GET /v1/documents/{documentId}/links
SDK
JavaScripttring.listDocumentLinks()
Pythontring.list_document_links()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Every link that was made for the document, oldest first, with its state. Never a token. Each call is written to the audit log of the business.

http
POST /v1/documents/{documentId}/links
SDK
JavaScripttring.createDocumentLink()
Pythontring.create_document_link()
Key scopedelivery
BodyCreateLinkRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ALLOCATION_NUMBER_REQUIRED 409, CONSENT_WITHDRAWN 409, ISSUER_NOT_ACTIVE 409, PAYMENT_MEANS_NOT_ALLOWED 409, DOCUMENT_CANCELLED 410, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, MAILER_NOT_CONFIGURED 501, UNAVAILABLE 503

Makes a link through which the customer of the document opens a page of the issuing business and downloads the document. Opening the page hands out nothing; the recipient presses a button. The first download is the "מקור" and every later one a "העתק". A recipient who has not yet consented to computerized documents of this business is asked on the page, before any download.

http
POST /v1/issuers/{issuerId}/links/{linkId}/revocation
SDK
JavaScripttring.revokeLink()
Pythontring.revoke_link()
Key scopedelivery
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

From this moment the link answers its holder like a link that never existed. Repeating is safe: a link that was already revoked stays as it is and "alreadyRevoked" is true. The request has no body.

Ask the product to email a link

http
POST /v1/issuers/{issuerId}/links/{linkId}/email
SDK
JavaScripttring.sendLinkEmail()
Pythontring.send_link_email()
Key scopedelivery
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, CONSENT_WITHDRAWN 409, ISSUER_NOT_ACTIVE 409, LINK_NOT_ACTIVE 409, PAYMENT_MEANS_NOT_ALLOWED 409, DOCUMENT_CANCELLED 410, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, MAILER_NOT_CONFIGURED 501, MAIL_FAILED 502, UNAVAILABLE 503, MAIL_OUTCOME_UNKNOWN 504

Sends an existing link by email, in the name of the business. The token is stored nowhere, so the caller hands back the token it received when the link was made. The address is "to", or the address the link was made for. The message carries the link and never the file [STO-01].

The consent of a customer

http
GET /v1/issuers/{issuerId}/customers/{customerKey}/consent
SDK
JavaScripttring.getConsent()
Pythontring.get_consent()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Whether a consent of this customer toward this business stands, whether the last word was a withdrawal, and every record that led there [SIG-13].

Report a consent the client system collected

http
POST /v1/issuers/{issuerId}/customers/{customerKey}/consent
SDK
JavaScripttring.reportConsent()
Pythontring.report_consent()
Key scopedelivery
BodyReportConsentRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Records that this customer consented to receive computerized documents of this business, when the client system collected the consent itself [SIG-11, SIG-12]. The exact words the customer agreed to and the evidence are required and are kept with the moment and the request. A consent given on the page of a link needs no report: the page records it. Every report is a new record.

Report that a customer withdrew consent

http
POST /v1/issuers/{issuerId}/customers/{customerKey}/consent/withdrawal
SDK
JavaScripttring.withdrawConsent()
Pythontring.withdraw_consent()
Key scopedelivery
BodyWithdrawConsentRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Records a withdrawal the client system received. From this moment the product sends this customer nothing more of this business: no download through any link, no new link, no email [SIG-14]. Repeating is safe: a withdrawal that is already in force adds no record ("recorded": false, 200). The body may be left out.

Cancel a document

http
POST /v1/documents/{documentId}/cancellation
SDK
JavaScripttring.cancelDocument()
Pythontring.cancel_document()
Key scopeissue
BodyCancelRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ALREADY_CANCELLED 409, CORRECTION_NOT_CANCELLABLE 409, DOCUMENT_REFERENCED 409, ISSUER_NOT_ACTIVE 409, ORIGINAL_RELEASED 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, DECLARATION_REQUIRED 422, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, DATABASE_REFUSED 500, INTERNAL 500, DELIVER_TIMEOUT 503, UNAVAILABLE 503, OUTCOME_UNKNOWN 504

A document can be cancelled only while its "מקור" has not left the business, and only with the statement of the business that it was not yet reported [DOC-54]. The document keeps its number and its record; from then on only its "מבוטל" view is rendered, and nothing of it is sent to anyone. Nothing is deleted.

What happened to a document after it was issued

http
GET /v1/documents/{documentId}/delivery
SDK
JavaScripttring.getDeliveryRecord()
Pythontring.get_delivery_record()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The links of the document (never their tokens), the messages that carried them and what became of each, every file that was handed out and to whom, when the "מקור" left the business, and the cancellation [SIG-17]. Each read is written to the audit log of the business.

Customers

The customers of a business

http
GET /v1/issuers/{issuerId}/customers
SDK
JavaScripttring.listCustomers()
Pythontring.list_customers()
Key scoperead
Parameterslimit, cursor, externalRef
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

In the order of their keys. "externalRef" finds the customer this client created under that reference.

One customer

http
GET /v1/issuers/{issuerId}/customers/{customerKey}
SDK
JavaScripttring.getCustomer()
Pythontring.get_customer()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The record of the customer as it stands now. A document carries its own copy of the details as they were printed.

Uniform file

The stored productions of a business

http
GET /v1/issuers/{issuerId}/uniform-exports
SDK
JavaScripttring.listUniformExports()
Pythontring.list_uniform_exports()
Key scoperead
Parameterslimit, cursor
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Newest first. What each production is, without its files.

Produce the uniform-structure files for a date range

http
POST /v1/issuers/{issuerId}/uniform-exports
SDK
JavaScripttring.produceUniformExport()
Pythontring.produce_uniform_export()
Key scoperecords
ParametersIdempotency-Key (required)
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, DEALER_NUMBER_CHANGED_IN_RANGE 409, IDEMPOTENCY_KEY_REUSED 409, ISSUER_NOT_ACTIVE 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, IDEMPOTENCY_KEY_INVALID 422, INVALID_INPUT 422, REQUEST_INVALID 422, VALUE_REFUSED 422, RATE_LIMITED 429, CONSISTENCY_CHECK_FAILED 500, INTERNAL 500, DIRECTORY_UNAVAILABLE 503, UNAVAILABLE 503

Reads the permanent file of the business in one snapshot, writes INI.TXT and BKMVDATA.TXT, checks them, and stores the production. The answer describes the production and carries the two reports of the specification; the files themselves are the download of the production.

The files of a stored production, as one ZIP

http
GET /v1/issuers/{issuerId}/uniform-exports/{exportId}/download
SDK
JavaScripttring.downloadUniformExport()
Pythontring.download_uniform_export()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, STORED_PRODUCTION_DAMAGED 500, UNAVAILABLE 503

The directory tree of the specification in one download: OPENFRMT/<dealer>.<YY>/<MMDDhhmm>/INI.TXT and BKMVDATA.zip, byte for byte as they were produced. The stored bytes are checked against their hashes before they leave. Each download is written to the audit log of the business.

The 2.6 report: documents per type in a date range

http
GET /v1/issuers/{issuerId}/reports/documents
SDK
JavaScripttring.getDocumentsReport()
Pythontring.get_documents_report()
Key scoperead
Parametersfrom (required), to (required), format
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, INVALID_INPUT 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Count and total of the documents of every type in the range, without producing files. "format" chooses JSON (default), the plain text form, or one self-contained HTML page. Each call is written to the audit log of the business.

Transmission

Where the transmission of a production stands

http
GET /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission
SDK
JavaScripttring.getTransmission()
Pythontring.get_transmission()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, AUTHORITY_NOT_CONFIGURED 503, UNAVAILABLE 503

Read from what was recorded: the status, what to do next, both files, the words of the Authority about a refusal or a rejection [TRX-18], and every step in order. Nothing is asked of the Authority by this call.

Transmit a stored production to the Tax Authority, or go on with its transmission

http
POST /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission
SDK
JavaScripttring.transmitUniformExport()
Pythontring.transmit_uniform_export()
Key scoperecords
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, SIGN_IN_REQUIRED 409, TRANSMISSION_IN_PROGRESS 409, AUTHORITY_REFUSED 422, FILE_TOO_LARGE 422, RATE_LIMITED 429, INTERNAL 500, STORED_PRODUCTION_DAMAGED 500, TOKEN_STORE_UNREADABLE 500, AUTHORITY_FAILED 502, AUTHORITY_NOT_CONFIGURED 503, AUTHORITY_UNREACHABLE 503, PRODUCTION_SWITCHED_OFF 503, UNAVAILABLE 503

Call it right after a production was stored [TRX-01]. The same call is "send", "send again" and "continue": what it does is decided from what was recorded. Never sent, or the last attempt ended: a new attempt. An attempt that has its links and not yet both files: it goes on from the file that is missing. Both files uploaded: nothing is sent again and the status is asked. Approved: nothing is requested. The stored files are sent as they are; nothing is ever produced again [TRX-18].

Ask the Tax Authority for the status of a transmitted production

http
POST /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission/status
SDK
JavaScripttring.checkTransmissionStatus()
Pythontring.check_transmission_status()
Key scoperecords
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, SIGN_IN_REQUIRED 409, TRANSMISSION_IN_PROGRESS 409, AUTHORITY_REFUSED 422, RATE_LIMITED 429, INTERNAL 500, TOKEN_STORE_UNREADABLE 500, AUTHORITY_FAILED 502, AUTHORITY_NOT_CONFIGURED 503, AUTHORITY_UNREACHABLE 503, PRODUCTION_SWITCHED_OFF 503, UNAVAILABLE 503

For a production whose two files were uploaded and that is not yet approved or rejected: asks the status service again and records its answer [TRX-11, TRX-12]. For a production that is not at that point nothing is requested and its state comes back. The service also asks by itself from time to time; this call is for a caller that wants the answer now.

Whether a business is connected to the Tax Authority

http
GET /v1/issuers/{issuerId}/authority-connection
SDK
JavaScripttring.getAuthorityConnection()
Pythontring.get_authority_connection()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, AUTHORITY_NOT_CONFIGURED 503, UNAVAILABLE 503

The allocation numbers and the checks of a received invoice need the long connection of the business: its owner signs in at the Tax Authority once, in the portal of the product, and again before the permission ends (three months). This call tells whether that connection stands and by when a new sign-in is needed. Sending a uniform file needs a second, short connection whose sign-in lasts two hours, made in the portal when the file is sent; this call does not describe it, and the state of a transmission says "sign-in" when it is needed. It never returns a token, and there is no call that takes one.

Allocation

Where the allocation number of a document stands

http
GET /v1/documents/{documentId}/allocation
SDK
JavaScripttring.getAllocation()
Pythontring.get_allocation()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, AUTHORITY_NOT_CONFIGURED 503, UNAVAILABLE 503

Read from what was recorded: whether the law requires a number, the number and its nine rightmost digits [ALC-09], a holding of the Authority and the alternatives after it, the choice and whether it was reported, the error list of the Authority word for word [ALC-15], and every request in order. Nothing is asked of the Authority by this call.

Ask the Tax Authority for the allocation number of a tax invoice

http
POST /v1/documents/{documentId}/allocation
SDK
JavaScripttring.requestAllocationNumber()
Pythontring.request_allocation_number()
Key scopeissue
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ALLOCATION_IN_PROGRESS 409, ISSUER_NOT_ACTIVE 409, SIGN_IN_REQUIRED 409, DOCUMENT_CANCELLED 410, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, AUTHORITY_REFUSED 422, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, TOKEN_STORE_UNREADABLE 500, AUTHORITY_FAILED 502, AUTHORITY_NOT_CONFIGURED 503, AUTHORITY_UNREACHABLE 503, PRODUCTION_SWITCHED_OFF 503, UNAVAILABLE 503

For an issued tax invoice (305, 320) of a business whose owner signed in at the Tax Authority in the portal of the product [ALC-11, ALC-19]. Also for a transaction invoice (300) of a licensed dealer that corrects nothing: it is asked about as the preliminary document "חשבון עסקה/פרופורמה" (code 332) whose "אישור הקצאה" the buyer may check before paying; the number is printed on it as "אישור הקצאה מספר:" with the sentence "לא ניתן לקזז מס תשומות בגין מסמך זה", and a held one offers every alternative but a reverse charge [ALC-25]. A tax invoice that names such a transaction invoice among its related documents is tied to it on its first request (action 4, the invoice_id of the preliminary document), as long as the tax invoices tied to it do not pass its amount without VAT together. The request carries the number and the amounts of the document as they stand in the permanent file; the caller sends nothing of them.

Report what the business chose after the Tax Authority held its invoice

http
POST /v1/documents/{documentId}/allocation-decision
SDK
JavaScripttring.reportAllocationDecision()
Pythontring.report_allocation_decision()
Key scopeissue
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ALLOCATION_IN_PROGRESS 409, ISSUER_NOT_ACTIVE 409, SIGN_IN_REQUIRED 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, AUTHORITY_REFUSED 422, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, DATABASE_REFUSED 500, INTERNAL 500, RENDER_FAILED 500, SIGNATURE_NOT_VERIFIED 500, SIGNING_FAILED 500, SIGNING_KEY_UNAVAILABLE 500, TOKEN_STORE_UNREADABLE 500, AUTHORITY_FAILED 502, ALLOCATE_TIMEOUT 503, AUTHORITY_NOT_CONFIGURED 503, AUTHORITY_UNREACHABLE 503, PRODUCTION_SWITCHED_OFF 503, UNAVAILABLE 503, OUTCOME_UNKNOWN 504

Only the business chooses; the client system passes the choice on [ALC-21]. It is stored first and then reported to the Authority, so a report that met a fault is not lost: state.decision.report is "pending", the service sends it again by itself, and the same call may be repeated. A call that answers AUTHORITY_UNREACHABLE or AUTHORITY_FAILED has stored the choice all the same: read the state. The same choice sent twice stores one row.

Ask the Tax Authority for the allocation numbers of several invoices in one request

http
POST /v1/issuers/{issuerId}/allocation-requests
SDK
JavaScripttring.requestAllocationNumbers()
Pythontring.request_allocation_numbers()
Key scopeissue
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ALLOCATION_IN_PROGRESS 409, ISSUER_NOT_ACTIVE 409, SIGN_IN_REQUIRED 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, AUTHORITY_REFUSED 422, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, TOKEN_STORE_UNREADABLE 500, AUTHORITY_FAILED 502, AUTHORITY_NOT_CONFIGURED 503, AUTHORITY_UNREACHABLE 503, PRODUCTION_SWITCHED_OFF 503, UNAVAILABLE 503

Up to 100 issued documents of the business in one request to the MultiApproval service of the Authority (edition 2.0, 2.5 to 2.7) [ALC-26]: tax invoices, and transaction invoices asked about as preliminary documents. Each document is checked as the call for one document checks it, and one that cannot travel is answered for in its item without stopping the others (a document that has its number answers sent false with no error). Every document that travelled is recorded as if it had been asked about alone, and what the answer says of it is acted on in the same way: a number is stored, with the further original; a holding offers the four alternatives in its state; wrong data is the error AUTHORITY_REFUSED of its item. An invoice the answer refuses for its data is corrected and asked about again by itself, with the call for one document, as the Authority instructs; one the answer leaves out, and every invoice of a request that met a fault, is asked about again by itself by the service, with the same invoice_id.

The amount above which a tax invoice needs an allocation number, as the Tax Authority states it

http
GET /v1/issuers/{issuerId}/allocation-minimum-amount
SDK
JavaScripttring.readAllocationMinimumAmount()
Pythontring.read_allocation_minimum_amount()
Key scoperead
Parametersdate
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ALLOCATION_IN_PROGRESS 409, ISSUER_NOT_ACTIVE 409, SIGN_IN_REQUIRED 409, AUTHORITY_REFUSED 422, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, TOKEN_STORE_UNREADABLE 500, AUTHORITY_FAILED 502, AUTHORITY_NOT_CONFIGURED 503, AUTHORITY_UNREACHABLE 503, PRODUCTION_SWITCHED_OFF 503, UNAVAILABLE 503

Asks the MinimumAmount service of the Authority (addendum 8.2025 to edition 2.0) for a date, with the connection of the business, and sets its answer beside the amount this product holds for that date [ALC-17, ALC-02]. The service answers a VAT amount ("סכום המע"מ המינימלי המחייב הקצאת חשבונית"; its example, 3600 in 2025, is 18% of the 20,000 of that year): impliedThreshold is that VAT turned into the amount without VAT by the rate in force on the date. The product's own table, which rests on the law, stays the one that decides whether a number is required; agrees false says that the two differ, for the operator to look at. Nothing is stored in the table by this call.

The details of a received invoice, by the allocation number printed on it

http
POST /v1/issuers/{issuerId}/received-invoices/details
SDK
JavaScripttring.lookupReceivedInvoice()
Pythontring.lookup_received_invoice()
Key scoperead
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ALLOCATION_IN_PROGRESS 409, ISSUER_NOT_ACTIVE 409, SIGN_IN_REQUIRED 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, AUTHORITY_REFUSED 422, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, TOKEN_STORE_UNREADABLE 500, AUTHORITY_FAILED 502, AUTHORITY_NOT_CONFIGURED 503, AUTHORITY_UNREACHABLE 503, PRODUCTION_SWITCHED_OFF 503, UNAVAILABLE 503

For a business that received a tax invoice: asks invoice-information/details of the Authority (version 2, addendum 6.2026) with the connection of the business, which asks as the buyer [ALC-20]. The allocation number may be the whole one or its nine rightmost digits. found false: the Authority holds no invoice with this number from this supplier to this business (code 472). Nothing is stored beside an audit row.

The allocation number of a received invoice, by its details

http
POST /v1/issuers/{issuerId}/received-invoices/confirmation-number
SDK
JavaScripttring.lookupReceivedConfirmationNumber()
Pythontring.lookup_received_confirmation_number()
Key scoperead
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ALLOCATION_IN_PROGRESS 409, ISSUER_NOT_ACTIVE 409, SIGN_IN_REQUIRED 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, AUTHORITY_REFUSED 422, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, TOKEN_STORE_UNREADABLE 500, AUTHORITY_FAILED 502, AUTHORITY_NOT_CONFIGURED 503, AUTHORITY_UNREACHABLE 503, PRODUCTION_SWITCHED_OFF 503, UNAVAILABLE 503

For a business that received a tax invoice without a number, or wants to check the one on it: asks invoice-information/confirmationNumber of the Authority (version 2, addendum 6.2026) with the connection of the business, as the buyer, with the amounts and the date printed on the invoice [ALC-20]. found false: the Authority holds no such invoice (code 472).

Backup

The backups of a business

http
GET /v1/issuers/{issuerId}/backups
SDK
JavaScripttring.listBackups()
Pythontring.list_backups()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The record of every backup that was made of the business, newest first: its date, how far the permanent file reached, and whether the business took its files. At most the newest 100.

Start a backup of a business now

http
POST /v1/issuers/{issuerId}/backups
SDK
JavaScripttring.startBackup()
Pythontring.start_backup()
Key scoperecords
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, BACKUP_IN_PROGRESS 409, ISSUER_NOT_ACTIVE 409, BACKUP_LIMIT 429, RATE_LIMITED 429, BACKUP_FAILED 500, INTERNAL 500, UNAVAILABLE 503

Makes a backup of everything the accounts system holds for the business at this moment (its documents with their signed files, its consents, its customers and the other lists, its uniform-structure files) and records its date. The files of the backup are taken by the business itself, in the portal of the product: this API never hands them out. A request sent again within a minute of a finished backup answers 200 with that backup and "repeated": true, so a request whose answer was lost can simply be sent again. A business makes at most three backups on request in 24 hours (BACKUP_LIMIT).

Finances

Income, expenses and profit of a year

http
GET /v1/issuers/{issuerId}/finance
SDK
JavaScripttring.getFinanceYear()
Pythontring.get_finance_year()
Key scopefinance
Parametersyear (required)
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The year as the portal's screen "כספים" shows it: the three sums, the twelve months, the income by customer and the expenses by kind, and the years that hold anything. Income is read from the documents the business issued and nothing of them changes. Each call is written to the audit log of the business: the answer holds the names of customers and their sums.

The expenses of a business

http
GET /v1/issuers/{issuerId}/expenses
SDK
JavaScripttring.listExpenses()
Pythontring.list_expenses()
Key scopefinance
Parameterslimit, cursor, year, month, category
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Newest first, by the date of the expense. A removed expense is never listed. "month" needs "year".

Record an expense

http
POST /v1/issuers/{issuerId}/expenses
SDK
JavaScripttring.createExpense()
Pythontring.create_expense()
Key scopeexpenses
ParametersIdempotency-Key (required)
BodyExpenseRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, IDEMPOTENCY_KEY_REUSED 409, ISSUER_NOT_ACTIVE 409, EXPENSE_REMOVED 410, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, EXPENSE_REFUSED 422, IDEMPOTENCY_KEY_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Records an expense of the business for the owner's own view of income and profit. It enters no document, series, uniform file or transmission. Each field is checked as the portal checks it; a refusal names every field at fault (EXPENSE_REFUSED) and stores nothing.

One expense

http
GET /v1/issuers/{issuerId}/expenses/{expenseId}
SDK
JavaScripttring.getExpense()
Pythontring.get_expense()
Key scopefinance
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

An expense as it stands now. A removed expense is not found.

Correct an expense

http
PATCH /v1/issuers/{issuerId}/expenses/{expenseId}
SDK
JavaScripttring.updateExpense()
Pythontring.update_expense()
Key scopeexpenses
BodyExpenseChange
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, EXPENSE_REFUSED 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Changes the fields sent and keeps the others; "note": null removes the note. The whole expense, as it would stand, is checked again. Sent twice, the same change is the same expense: the second answers "replayed": true and changes nothing. A removed expense is not found.

Remove an expense

http
DELETE /v1/issuers/{issuerId}/expenses/{expenseId}
SDK
JavaScripttring.removeExpense()
Pythontring.remove_expense()
Key scopeexpenses
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The expense is shown nowhere and counted in no total from now on. Its row is kept, with the moment and the client system that removed it, and nothing deletes it; a removal is final. Sent again, the answer is the same removal ("replayed": true) and nothing changes.

The file of the receipt

http
GET /v1/issuers/{issuerId}/expenses/{expenseId}/receipt
SDK
JavaScripttring.getExpenseReceipt()
Pythontring.get_expense_receipt()
Key scopefinance
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The file of the supplier's receipt in force, byte for byte as it was sent. Each download is written to the audit log of the business. An expense without a file, and a removed expense, are not found.

Attach the file of the receipt

http
PUT /v1/issuers/{issuerId}/expenses/{expenseId}/receipt
SDK
JavaScripttring.putExpenseReceipt()
Pythontring.put_expense_receipt()
Key scopeexpenses
ParametersfileName
BodyThe file itself, raw bytes, with its media type: application/pdf, image/jpeg, image/png
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, EXPENSE_REFUSED 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The picture (JPEG, PNG) or PDF of the supplier's receipt, sent as the body itself with its media type, at most 5242880 bytes (5 MiB; larger: PAYLOAD_TOO_LARGE). Its kind is read from its first bytes and must be the media type it was sent as. It takes the place of the file in force; the earlier file is kept and is no longer shown. The same file sent again stores nothing ("replayed": true, 200).

Register

The catalog of the register

http
GET /v1/issuers/{issuerId}/pos/items
SDK
JavaScripttring.listPosItems()
Pythontring.list_pos_items()
Key scopepos
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Every item in use, in the order of the tiles. An item taken out of the catalog is not listed.

Keep an item by its code

http
PUT /v1/issuers/{issuerId}/pos/items/{itemCode}
SDK
JavaScripttring.putPosItem()
Pythontring.put_pos_item()
Key scopepos
BodyPosItemRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, POS_ITEM_REFUSED 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Makes the item of this code (201) or changes it to what was sent (200); the fields left out take their defaults. Sent again with the same body it changes nothing ("replayed": true). A change never reaches a document already issued. Each field is checked as the portal checks it; a refusal names every field at fault (POS_ITEM_REFUSED: required, too-long, invalid, too-many) and stores nothing. At most 500 items in use per business.

Take an item out of the catalog

http
DELETE /v1/issuers/{issuerId}/pos/items/{itemCode}
SDK
JavaScripttring.removePosItem()
Pythontring.remove_pos_item()
Key scopepos
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The item is archived: no tile, no sale. Its row is kept and nothing deletes it; its code is free for another item. A code with no item in use is not found.

The registers

http
GET /v1/issuers/{issuerId}/pos/registers
SDK
JavaScripttring.listPosRegisters()
Pythontring.list_pos_registers()
Key scopepos
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The registers in use of the business, oldest first, each with whether a shift is open and the number of its last close.

The closes of the registers

http
GET /v1/issuers/{issuerId}/pos/closes
SDK
JavaScripttring.listPosCloses()
Pythontring.list_pos_closes()
Key scopepos
ParametersregisterId
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Newest first, at most 200; of one register with "registerId". Each answer is written to the audit log of the business.

One close

http
GET /v1/issuers/{issuerId}/pos/closes/{closeId}
SDK
JavaScripttring.getPosClose()
Pythontring.get_pos_close()
Key scopepos
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, ISSUER_NOT_ACTIVE 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

A close with its figures as they were stored. Written to the audit log of the business.

Reference

The VAT rate and the allocation amount in force today

http
GET /v1/reference
SDK
JavaScripttring.getReference()
Pythontring.get_reference()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The standard VAT rate [DOC-61] and the amount above which a tax invoice needs an allocation number [ALC-02], as the server applies them to a document dated today. A caller never sends either: the server fills them.

Webhooks

Your webhook addresses

http
GET /v1/webhook-endpoints
SDK
JavaScripttring.listWebhookEndpoints()
Pythontring.list_webhook_endpoints()
Key scoperead
ParametersincludeDeleted
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Every address of your system that is not deleted, oldest first; with includeDeleted=true the deleted ones too.

Register a webhook address

http
POST /v1/webhook-endpoints
SDK
JavaScripttring.createWebhookEndpoint()
Pythontring.create_webhook_endpoint()
Key scopewebhooks
BodyCreateWebhookEndpointRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, WEBHOOK_ENDPOINT_LIMIT 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503, WEBHOOKS_NOT_CONFIGURED 503

Registers an address of your system to be told of events by a signed HTTPS POST (see the webhooks section of this file, and INTEGRATION 13). The answer holds the signing secret, once. Events are posted from the moment of registration; nothing earlier is sent, and GET /v1/events holds the earlier ones. At most 16 addresses per client system. The address must be https on port 443 or 8443, and its host a public name or address: an address of a private, loopback, link-local or reserved range is refused, also when a name resolves to one later.

One webhook address

http
GET /v1/webhook-endpoints/{endpointId}
SDK
JavaScripttring.getWebhookEndpoint()
Pythontring.get_webhook_endpoint()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The address, its state and when its secrets were made and end. Never a secret.

Change a webhook address

http
POST /v1/webhook-endpoints/{endpointId}
SDK
JavaScripttring.updateWebhookEndpoint()
Pythontring.update_webhook_endpoint()
Key scopewebhooks
BodyUpdateWebhookEndpointRequest
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, WEBHOOK_ENDPOINT_DELETED 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503, WEBHOOKS_NOT_CONFIGURED 503

Changes the address, its description or the kinds of events it takes, or switches it off ("enabled": false: what waited for it is dropped, and can be sent again by hand from the delivery log) and on again ("enabled": true, also after the service switched it off for failing). What is left out stays.

Delete a webhook address

http
POST /v1/webhook-endpoints/{endpointId}/deletion
SDK
JavaScripttring.deleteWebhookEndpoint()
Pythontring.delete_webhook_endpoint()
Key scopewebhooks
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Deletes the address for good: nothing more is posted to it, what waited is dropped, its secrets stop signing at once. Its delivery log stays readable. Sending it again answers the same.

Rotate the signing secret

http
POST /v1/webhook-endpoints/{endpointId}/secret-rotation
SDK
JavaScripttring.rotateWebhookSecret()
Pythontring.rotate_webhook_secret()
Key scopewebhooks
BodyJSON
ErrorsMALFORMED_JSON 400, UNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, WEBHOOK_ENDPOINT_DELETED 409, PAYLOAD_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503, WEBHOOKS_NOT_CONFIGURED 503

Makes a new signing secret and answers it, once. The secrets that signed until now go on signing beside it for overlapSeconds (24 hours by default): during that time every notice carries two v1 signatures, so your receiver takes the new secret in without missing one. 0 ends the old secrets at once, for a secret that leaked.

Post a test notice now

http
POST /v1/webhook-endpoints/{endpointId}/test
SDK
JavaScripttring.sendWebhookTest()
Pythontring.send_webhook_test()
Key scopewebhooks
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, WEBHOOK_ENDPOINT_DELETED 409, RATE_LIMITED 429, WEBHOOK_TEST_TOO_SOON 429, INTERNAL 500, UNAVAILABLE 503, WEBHOOKS_NOT_CONFIGURED 503

Posts an "endpoint.test" notice to the address now, signed like every notice, and answers how it went: whether your address answered 2xx, its status, or why it could not be reached. Use it to try your check of the signature. A switched-off address takes it too. One test per address every 5 seconds, and ten per client system in a minute over all its addresses, counted before the notice leaves.

The delivery log of an address

http
GET /v1/webhook-endpoints/{endpointId}/deliveries
SDK
JavaScripttring.listWebhookDeliveries()
Pythontring.list_webhook_deliveries()
Key scoperead
Parameterslimit, cursor, status
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

Every delivery to the address, newest first: the event, where its sending stands, how many tries, the last status and why it failed. status narrows it (for example "failed").

One delivery, with every try

http
GET /v1/webhook-deliveries/{deliveryId}
SDK
JavaScripttring.getWebhookDelivery()
Pythontring.get_webhook_delivery()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The delivery and every try of it: when, the status your address answered, how long it took, and why it failed. The body of your answers is never kept.

Send a delivery again

http
POST /v1/webhook-deliveries/{deliveryId}/redelivery
SDK
JavaScripttring.redeliverWebhook()
Pythontring.redeliver_webhook()
Key scopewebhooks
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, WEBHOOK_DELIVERY_PENDING 409, WEBHOOK_ENDPOINT_DELETED 409, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503, WEBHOOKS_NOT_CONFIGURED 503

Sends a delivery that succeeded, failed or was dropped once more, within seconds: one try, the same event and the same event id. It does not count toward switching the address off. Read the delivery to see how it went. A delivery that is still waiting or being sent answers WEBHOOK_DELIVERY_PENDING.

The events meant for your system

http
GET /v1/events
SDK
JavaScripttring.listEvents()
Pythontring.list_events()
Key scoperead
Parametersafter, type, issuerId, limit
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, INPUT_INVALID 422, REQUEST_INVALID 422, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The events meant for your system, oldest first: every event of the businesses that give it a standing grant, and those about your system itself. Keep the id of the last event you handled and ask with after=<that id>: you miss nothing, also while your address was down or when you have none. Works without any webhook address.

One event

http
GET /v1/events/{eventId}
SDK
JavaScripttring.getEvent()
Pythontring.get_event()
Key scoperead
ErrorsUNAUTHENTICATED 401, KEY_ADDRESS_NOT_ALLOWED 403, KEY_SCOPE_MISSING 403, NOT_FOUND 404, RATE_LIMITED 429, INTERNAL 500, UNAVAILABLE 503

The event, when it was meant for your system. A receiver that wants to be sure a notice is true reads the event, or the thing it names, with its own key.