Skavio Agent Tools: submit an invoice extraction job with a stable idempotency key
A network timeout does not tell you whether an invoice extraction request reached the server. Skavio Agent Tools documents same-key submissions as protected against creating a second job and duplicate charging. To use that documented contract, create and durably store the request’s identity before sending it—not when a retry becomes necessary.
1. Prepare a fictional invoice and a server-side client
Start with a fictional invoice rather than customer financial records. Include an invoice number, supplier, dates, currency and clearly stated amounts so you can later compare the extracted fields with the source. The published catalogue lists invoice_extract as available, and the invoice-input documentation describes base64-encoded input. Keep authentication on your server. Agent Tools uses Authorization: Bearer <secret>; keys are company-scoped, and their secret is displayed once. Store the credential securely rather than placing it in browser code, source control or request logs. Protect the encoded invoice just as you protect the source document.
2. Persist the operation before making the request
Create one opaque identifier for the intended extraction and save it with the complete request before any network submission. A randomly generated identifier stored in a durable operation record is a useful client-design pattern; check the current documentation for accepted key formats. The critical distinction is between generating an identifier once and generating one inside the retry loop. After a timeout or process restart, reload the original record rather than constructing a new identity for the same work. Save both the key and the matching request so the client can recover exactly what it intended to submit.
- Record the idempotency key, tool name and unchanged arguments in protected durable storage.
- Link that record to your internal intake item without putting supplier details or invoice contents into the key.
- Store the returned job identifier and subsequent status observations against the same record.
3. Submit the documented envelope—not an invented header
The documented submission route is POST /agent-tools/api/jobs. Its JSON envelope contains tool, idempotency_key and arguments. The key belongs in the body; an Idempotency-Key header is not documented for this route. This documentation-derived example shows the request shape: ```json { "tool": "invoice_extract", "idempotency_key": "invoice-demo-0001", "arguments": { "data_base64": "<base64-encoded fictional invoice>" } } ``` The sample key and input are illustrative. The placeholder is not runnable invoice data, and a real new operation needs its own identifier. The published submission example returns 202 Accepted with state, job_id and quote. Save those details, but do not mark the extraction complete: HTTP 202 means the request was accepted for processing, not that processing succeeded. A quote returned after submission is not a separate pre-submission approval step; the reviewed Agent Tools contract does not specify a separate quote-and-confirm endpoint. No authenticated submission, replay, credit-ledger check or download was performed for this walkthrough. The reviewed documentation also contains a legacy API-host reference. Confirm and test the canonical submission host in an authorized integration test before relying on an executable client.
4. Reconcile a timeout using the original key
Suppose the connection closes before the submission response arrives. Keep the local operation unresolved: the server may have accepted it even though your client received no confirmation. The documented status route is GET /agent-tools/api/jobs/{idempotency_key}. Look up the operation using its persisted key. If the job is still underway, continue tracking it rather than submitting a new extraction. An inconclusive status response is not proof that the original submission never happened. If a submission retry is appropriate under the current contract, resend the original key and unchanged body. Ordinary HTTP POST requests are not inherently safe to repeat. RFC 9110 advises against automatically retrying non-idempotent requests unless the client knows their application semantics are idempotent or knows the original request was not applied. Skavio’s documented same-key behavior is the basis for this retry—not a general property of POST. Use bounded retries rather than an endless loop. The reviewed material does not establish the deduplication lifetime, changed-payload behavior, concurrent replay responses or resubmission rules after terminal failure. When those details matter, resolve them through current documentation or support rather than guessing or switching to a fresh key.
5. Download, review and keep invoice duplication separate
When the status response reports available as true, retrieve the listed results through the authenticated result route. Published result retention is seven days, so plan retrieval accordingly. That retention period does not establish how long an idempotency key remains protected. Published invoice output fields include supplier, invoice number, dates, currency, subtotal, tax and total. Compare them with the original document before allowing downstream accounting use. Successful processing is not approval of the financial data. Finally, distinguish retry protection from duplicate-invoice detection. An idempotency key identifies one intended processing operation; it does not establish whether a supplier invoice has already entered your accounts. Keep business checks—such as supplier identity, invoice number, currency and amount—in a separate review process. An explicitly authorized new extraction should have a new operation identity, even if its source document is unchanged.