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
GET /v1/issuers| SDK | |
|---|---|
| JavaScript | tring.listIssuers() |
| Python | tring.list_issuers() |
| Key scope | read |
| Parameters | limit, cursor |
| Errors | UNAUTHENTICATED 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
POST /v1/issuers| SDK | |
|---|---|
| JavaScript | tring.createIssuer() |
| Python | tring.create_issuer() |
| Key scope | businesses |
| Body | CreateIssuerRequest |
| Errors | MALFORMED_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
GET /v1/issuers/{issuerId}| SDK | |
|---|---|
| JavaScript | tring.getIssuer() |
| Python | tring.get_issuer() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/design| SDK | |
|---|---|
| JavaScript | tring.getDocumentDesign() |
| Python | tring.get_document_design() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
PUT /v1/issuers/{issuerId}/design| SDK | |
|---|---|
| JavaScript | tring.putDocumentDesign() |
| Python | tring.put_document_design() |
| Key scope | businesses |
| Body | JSON |
| Errors | MALFORMED_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
POST /v1/issuers/{issuerId}/drafts| SDK | |
|---|---|
| JavaScript | tring.prepareDraft() |
| Python | tring.prepare_draft() |
| Key scope | issue |
| Parameters | Idempotency-Key (required) |
| Body | PrepareRequest |
| Errors | MALFORMED_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
GET /v1/drafts/{draftId}| SDK | |
|---|---|
| JavaScript | tring.getDraft() |
| Python | tring.get_draft() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
GET /v1/drafts/{draftId}/preview| SDK | |
|---|---|
| JavaScript | tring.previewDraft() |
| Python | tring.preview_draft() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
POST /v1/drafts/{draftId}/confirm| SDK | |
|---|---|
| JavaScript | tring.confirmDraft() |
| Python | tring.confirm_draft() |
| Key scope | issue |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/documents| SDK | |
|---|---|
| JavaScript | tring.listDocuments() |
| Python | tring.list_documents() |
| Key scope | read |
| Parameters | limit, cursor, from, to, docType, customerKey, number |
| Errors | UNAUTHENTICATED 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
GET /v1/documents/{documentId}| SDK | |
|---|---|
| JavaScript | tring.getDocument() |
| Python | tring.get_document() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
GET /v1/documents/{documentId}/pdf| SDK | |
|---|---|
| JavaScript | tring.downloadDocument() |
| Python | tring.download_document() |
| Key scope | read |
| Parameters | form |
| Errors | UNAUTHENTICATED 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
POST /v1/documents/{documentId}/allocation-number| SDK | |
|---|---|
| JavaScript | tring.recordAllocationNumber() |
| Python | tring.record_allocation_number() |
| Key scope | issue |
| Body | JSON |
| Errors | MALFORMED_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
The links of a document
GET /v1/documents/{documentId}/links| SDK | |
|---|---|
| JavaScript | tring.listDocumentLinks() |
| Python | tring.list_document_links() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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.
Make a personal link for the recipient of a document
POST /v1/documents/{documentId}/links| SDK | |
|---|---|
| JavaScript | tring.createDocumentLink() |
| Python | tring.create_document_link() |
| Key scope | delivery |
| Body | CreateLinkRequest |
| Errors | MALFORMED_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.
Revoke a link
POST /v1/issuers/{issuerId}/links/{linkId}/revocation| SDK | |
|---|---|
| JavaScript | tring.revokeLink() |
| Python | tring.revoke_link() |
| Key scope | delivery |
| Errors | UNAUTHENTICATED 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
POST /v1/issuers/{issuerId}/links/{linkId}/email| SDK | |
|---|---|
| JavaScript | tring.sendLinkEmail() |
| Python | tring.send_link_email() |
| Key scope | delivery |
| Body | JSON |
| Errors | MALFORMED_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
GET /v1/issuers/{issuerId}/customers/{customerKey}/consent| SDK | |
|---|---|
| JavaScript | tring.getConsent() |
| Python | tring.get_consent() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
POST /v1/issuers/{issuerId}/customers/{customerKey}/consent| SDK | |
|---|---|
| JavaScript | tring.reportConsent() |
| Python | tring.report_consent() |
| Key scope | delivery |
| Body | ReportConsentRequest |
| Errors | MALFORMED_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
POST /v1/issuers/{issuerId}/customers/{customerKey}/consent/withdrawal| SDK | |
|---|---|
| JavaScript | tring.withdrawConsent() |
| Python | tring.withdraw_consent() |
| Key scope | delivery |
| Body | WithdrawConsentRequest |
| Errors | MALFORMED_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
POST /v1/documents/{documentId}/cancellation| SDK | |
|---|---|
| JavaScript | tring.cancelDocument() |
| Python | tring.cancel_document() |
| Key scope | issue |
| Body | CancelRequest |
| Errors | MALFORMED_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
GET /v1/documents/{documentId}/delivery| SDK | |
|---|---|
| JavaScript | tring.getDeliveryRecord() |
| Python | tring.get_delivery_record() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/customers| SDK | |
|---|---|
| JavaScript | tring.listCustomers() |
| Python | tring.list_customers() |
| Key scope | read |
| Parameters | limit, cursor, externalRef |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/customers/{customerKey}| SDK | |
|---|---|
| JavaScript | tring.getCustomer() |
| Python | tring.get_customer() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/uniform-exports| SDK | |
|---|---|
| JavaScript | tring.listUniformExports() |
| Python | tring.list_uniform_exports() |
| Key scope | read |
| Parameters | limit, cursor |
| Errors | UNAUTHENTICATED 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
POST /v1/issuers/{issuerId}/uniform-exports| SDK | |
|---|---|
| JavaScript | tring.produceUniformExport() |
| Python | tring.produce_uniform_export() |
| Key scope | records |
| Parameters | Idempotency-Key (required) |
| Body | JSON |
| Errors | MALFORMED_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
GET /v1/issuers/{issuerId}/uniform-exports/{exportId}/download| SDK | |
|---|---|
| JavaScript | tring.downloadUniformExport() |
| Python | tring.download_uniform_export() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/reports/documents| SDK | |
|---|---|
| JavaScript | tring.getDocumentsReport() |
| Python | tring.get_documents_report() |
| Key scope | read |
| Parameters | from (required), to (required), format |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission| SDK | |
|---|---|
| JavaScript | tring.getTransmission() |
| Python | tring.get_transmission() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
POST /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission| SDK | |
|---|---|
| JavaScript | tring.transmitUniformExport() |
| Python | tring.transmit_uniform_export() |
| Key scope | records |
| Errors | UNAUTHENTICATED 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
POST /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission/status| SDK | |
|---|---|
| JavaScript | tring.checkTransmissionStatus() |
| Python | tring.check_transmission_status() |
| Key scope | records |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/authority-connection| SDK | |
|---|---|
| JavaScript | tring.getAuthorityConnection() |
| Python | tring.get_authority_connection() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
GET /v1/documents/{documentId}/allocation| SDK | |
|---|---|
| JavaScript | tring.getAllocation() |
| Python | tring.get_allocation() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
POST /v1/documents/{documentId}/allocation| SDK | |
|---|---|
| JavaScript | tring.requestAllocationNumber() |
| Python | tring.request_allocation_number() |
| Key scope | issue |
| Body | JSON |
| Errors | MALFORMED_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
POST /v1/documents/{documentId}/allocation-decision| SDK | |
|---|---|
| JavaScript | tring.reportAllocationDecision() |
| Python | tring.report_allocation_decision() |
| Key scope | issue |
| Body | JSON |
| Errors | MALFORMED_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
POST /v1/issuers/{issuerId}/allocation-requests| SDK | |
|---|---|
| JavaScript | tring.requestAllocationNumbers() |
| Python | tring.request_allocation_numbers() |
| Key scope | issue |
| Body | JSON |
| Errors | MALFORMED_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
GET /v1/issuers/{issuerId}/allocation-minimum-amount| SDK | |
|---|---|
| JavaScript | tring.readAllocationMinimumAmount() |
| Python | tring.read_allocation_minimum_amount() |
| Key scope | read |
| Parameters | date |
| Errors | 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, 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
POST /v1/issuers/{issuerId}/received-invoices/details| SDK | |
|---|---|
| JavaScript | tring.lookupReceivedInvoice() |
| Python | tring.lookup_received_invoice() |
| Key scope | read |
| Body | JSON |
| Errors | MALFORMED_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
POST /v1/issuers/{issuerId}/received-invoices/confirmation-number| SDK | |
|---|---|
| JavaScript | tring.lookupReceivedConfirmationNumber() |
| Python | tring.lookup_received_confirmation_number() |
| Key scope | read |
| Body | JSON |
| Errors | MALFORMED_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
GET /v1/issuers/{issuerId}/backups| SDK | |
|---|---|
| JavaScript | tring.listBackups() |
| Python | tring.list_backups() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
POST /v1/issuers/{issuerId}/backups| SDK | |
|---|---|
| JavaScript | tring.startBackup() |
| Python | tring.start_backup() |
| Key scope | records |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/finance| SDK | |
|---|---|
| JavaScript | tring.getFinanceYear() |
| Python | tring.get_finance_year() |
| Key scope | finance |
| Parameters | year (required) |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/expenses| SDK | |
|---|---|
| JavaScript | tring.listExpenses() |
| Python | tring.list_expenses() |
| Key scope | finance |
| Parameters | limit, cursor, year, month, category |
| Errors | UNAUTHENTICATED 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
POST /v1/issuers/{issuerId}/expenses| SDK | |
|---|---|
| JavaScript | tring.createExpense() |
| Python | tring.create_expense() |
| Key scope | expenses |
| Parameters | Idempotency-Key (required) |
| Body | ExpenseRequest |
| Errors | MALFORMED_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
GET /v1/issuers/{issuerId}/expenses/{expenseId}| SDK | |
|---|---|
| JavaScript | tring.getExpense() |
| Python | tring.get_expense() |
| Key scope | finance |
| Errors | UNAUTHENTICATED 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
PATCH /v1/issuers/{issuerId}/expenses/{expenseId}| SDK | |
|---|---|
| JavaScript | tring.updateExpense() |
| Python | tring.update_expense() |
| Key scope | expenses |
| Body | ExpenseChange |
| Errors | MALFORMED_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
DELETE /v1/issuers/{issuerId}/expenses/{expenseId}| SDK | |
|---|---|
| JavaScript | tring.removeExpense() |
| Python | tring.remove_expense() |
| Key scope | expenses |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/expenses/{expenseId}/receipt| SDK | |
|---|---|
| JavaScript | tring.getExpenseReceipt() |
| Python | tring.get_expense_receipt() |
| Key scope | finance |
| Errors | UNAUTHENTICATED 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
PUT /v1/issuers/{issuerId}/expenses/{expenseId}/receipt| SDK | |
|---|---|
| JavaScript | tring.putExpenseReceipt() |
| Python | tring.put_expense_receipt() |
| Key scope | expenses |
| Parameters | fileName |
| Body | The file itself, raw bytes, with its media type: application/pdf, image/jpeg, image/png |
| Errors | 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 |
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
GET /v1/issuers/{issuerId}/pos/items| SDK | |
|---|---|
| JavaScript | tring.listPosItems() |
| Python | tring.list_pos_items() |
| Key scope | pos |
| Errors | UNAUTHENTICATED 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
PUT /v1/issuers/{issuerId}/pos/items/{itemCode}| SDK | |
|---|---|
| JavaScript | tring.putPosItem() |
| Python | tring.put_pos_item() |
| Key scope | pos |
| Body | PosItemRequest |
| Errors | MALFORMED_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
DELETE /v1/issuers/{issuerId}/pos/items/{itemCode}| SDK | |
|---|---|
| JavaScript | tring.removePosItem() |
| Python | tring.remove_pos_item() |
| Key scope | pos |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/pos/registers| SDK | |
|---|---|
| JavaScript | tring.listPosRegisters() |
| Python | tring.list_pos_registers() |
| Key scope | pos |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/pos/closes| SDK | |
|---|---|
| JavaScript | tring.listPosCloses() |
| Python | tring.list_pos_closes() |
| Key scope | pos |
| Parameters | registerId |
| Errors | UNAUTHENTICATED 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
GET /v1/issuers/{issuerId}/pos/closes/{closeId}| SDK | |
|---|---|
| JavaScript | tring.getPosClose() |
| Python | tring.get_pos_close() |
| Key scope | pos |
| Errors | UNAUTHENTICATED 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
GET /v1/reference| SDK | |
|---|---|
| JavaScript | tring.getReference() |
| Python | tring.get_reference() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
GET /v1/webhook-endpoints| SDK | |
|---|---|
| JavaScript | tring.listWebhookEndpoints() |
| Python | tring.list_webhook_endpoints() |
| Key scope | read |
| Parameters | includeDeleted |
| Errors | UNAUTHENTICATED 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
POST /v1/webhook-endpoints| SDK | |
|---|---|
| JavaScript | tring.createWebhookEndpoint() |
| Python | tring.create_webhook_endpoint() |
| Key scope | webhooks |
| Body | CreateWebhookEndpointRequest |
| Errors | MALFORMED_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
GET /v1/webhook-endpoints/{endpointId}| SDK | |
|---|---|
| JavaScript | tring.getWebhookEndpoint() |
| Python | tring.get_webhook_endpoint() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
POST /v1/webhook-endpoints/{endpointId}| SDK | |
|---|---|
| JavaScript | tring.updateWebhookEndpoint() |
| Python | tring.update_webhook_endpoint() |
| Key scope | webhooks |
| Body | UpdateWebhookEndpointRequest |
| Errors | MALFORMED_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
POST /v1/webhook-endpoints/{endpointId}/deletion| SDK | |
|---|---|
| JavaScript | tring.deleteWebhookEndpoint() |
| Python | tring.delete_webhook_endpoint() |
| Key scope | webhooks |
| Errors | UNAUTHENTICATED 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
POST /v1/webhook-endpoints/{endpointId}/secret-rotation| SDK | |
|---|---|
| JavaScript | tring.rotateWebhookSecret() |
| Python | tring.rotate_webhook_secret() |
| Key scope | webhooks |
| Body | JSON |
| Errors | MALFORMED_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
POST /v1/webhook-endpoints/{endpointId}/test| SDK | |
|---|---|
| JavaScript | tring.sendWebhookTest() |
| Python | tring.send_webhook_test() |
| Key scope | webhooks |
| Errors | UNAUTHENTICATED 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
GET /v1/webhook-endpoints/{endpointId}/deliveries| SDK | |
|---|---|
| JavaScript | tring.listWebhookDeliveries() |
| Python | tring.list_webhook_deliveries() |
| Key scope | read |
| Parameters | limit, cursor, status |
| Errors | UNAUTHENTICATED 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
GET /v1/webhook-deliveries/{deliveryId}| SDK | |
|---|---|
| JavaScript | tring.getWebhookDelivery() |
| Python | tring.get_webhook_delivery() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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
POST /v1/webhook-deliveries/{deliveryId}/redelivery| SDK | |
|---|---|
| JavaScript | tring.redeliverWebhook() |
| Python | tring.redeliver_webhook() |
| Key scope | webhooks |
| Errors | UNAUTHENTICATED 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
GET /v1/events| SDK | |
|---|---|
| JavaScript | tring.listEvents() |
| Python | tring.list_events() |
| Key scope | read |
| Parameters | after, type, issuerId, limit |
| Errors | UNAUTHENTICATED 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
GET /v1/events/{eventId}| SDK | |
|---|---|
| JavaScript | tring.getEvent() |
| Python | tring.get_event() |
| Key scope | read |
| Errors | UNAUTHENTICATED 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.