--- title: "Queue one validation" method: POST path: "/v2/einvoices/jobs" tags: ["jobs"] --- # Queue one validation `POST /v2/einvoices/jobs` ## Request - Base URL: `https://api.ironfang.com/finance` - URL: `https://api.ironfang.com/finance/v2/einvoices/jobs` - Auth: HTTP bearer Queues one validation: `document_base64` holds the document's bytes, `media_type` says what they are (the content must agree, as in synchronous validation) and `options` are the synchronous options. XML at most 5 MiB, a PDF at most 20 MiB; the envelope at most 28 MiB. **Acceptance.** Every decision synchronous validation makes before it validates is made now: the document's content and size, the scope, a PDF's inspection and its embedded invoice, and the release `latest` or the ruleset id resolves to. A document it would refuse is refused here with the same Problem, and nothing is queued or charged. An accepted job is pinned to that release and its engines, and one validation is reserved on the billing account until the job finishes: charged if it reaches a verdict, returned otherwise. A batch is admitted whole or not at all. **Running.** The job runs through the same validation as `POST /v2/einvoices/validate`. Its result is a V2 validation result, read at `result_url` once the job is `completed`; its usage and its webhook or S3 event (`ironfang/finance/einvoice/event/v2`, naming `job_id`) are a synchronous validation's. An unavailable engine or a timeout is retried, up to 3 attempts; then the job is `failed`, indeterminate and uncharged. The document is held encrypted until the job finishes, at most 24 hours (`expires_at`), then erased. **Queue.** An organisation holds at most 100 unfinished jobs and 25 MiB of their documents; more is `429 quota_exhausted`. **Idempotency.** As synchronous validation, with the request identified by the document's bytes, the options and the scope. Keys are V2's own, apart from V1 jobs and from synchronous validation. ## Headers - `Idempotency-Key` string ## Request body - JobRequest - `document_base64` string, byte, required: The document's bytes, standard padded base64 without line breaks. XML at most 5 MiB, a PDF at most 20 MiB decoded. - `media_type` 'application/xml' | 'text/xml' | 'application/pdf', required: What the document is. The content must agree, or the job is `415 unsupported_content_type`. - `options` ValidationOptions: The multipart `options` part. The same names as the query parameters. Unknown or repeated keys are `400`. - `document_type` 'invoice' | 'credit_note' | 'auto' - `family` 'peppol-bis-billing-3' | 'xrechnung' | 'zugferd-facturx': An invoice family. `zugferd-facturx` is one family: ZUGFeRD and Factur-X are corresponding release names of the same standard. - `ruleset` string - `scope` 'xml' | 'hybrid_pdf' - `variant` 'core' | 'extension' | 'cvd' | 'minimum' | 'basic-wl' | 'basic' | 'en16931' | 'extended' | 'xrechnung': A variant or profile within a family. XRechnung: `core`, `extension`, `cvd`. ZUGFeRD / Factur-X: `minimum`, `basic-wl`, `basic`, `en16931`, `extended`, `xrechnung` (the ZUGFeRD XRECHNUNG reference profile). Peppol BIS Billing 3 has none. Recognition is not support: the ruleset list is the only statement of what is validated. ## Response `200` The job this Idempotency-Key already names, unchanged. - Job: One durable job, V1's or V2's: metadata only, never its document. `outcome` appears once the job has finished: `valid` or `invalid` when completed, `indeterminate` when failed or cancelled, with `failure_code`. A queued job being retried keeps the last attempt's `failure_code`. `result_url` appears while the result can be read. - `api_version` 'v1' | 'v2', required: The API a result was made through. - `attempts` integer, required - `batch_id` string - `created_at` string, date-time, required - `engine_image_digest` string, required - `expires_at` string, date-time, required: When an unfinished job is failed as job_expired and its document erased. - `failure_code` 'validation_timeout' | 'validator_unavailable' | 'internal_error' | 'generation_failed' | 'job_cancelled' | 'job_expired' - `finished_at` string, date-time - `id` string, required - `operation` 'validate' | 'generate', required: V2 jobs validate; a V1 job may generate. - `operation_id` string, required - `outcome` 'valid' | 'invalid' | 'indeterminate' - `position` integer, required: The job's place in its batch; 0 outside one. - `result_available` boolean, required - `result_url` string - `ruleset_id` string, required - `schema` 'ironfang/finance/einvoice/job/v2', required - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required - `usage_charged` boolean, required ## Other responses - `202`: Accepted and queued. Location names the job. Cache-Control is no-store. - `400`: The request is malformed. - `401`: The credential is missing or not accepted. - `402`: The free allowance is used up and paid usage cannot continue until the billing account is put right: paused, no working payment method, a payment awaiting confirmation, or restricted. Nothing was accepted. - `403`: The key lacks the scope this operation needs, or paid Ironfang Finance usage needs an approved business and the free allowance is used up. Nothing was accepted. - `409`: The Idempotency-Key was used for a different request. - `410`: The release was withdrawn from every use, or the billing account is closed. Nothing was queued. - `413`: The body is over the limit for its media type. - `415`: The media type, encoding or content is not accepted. - `422`: The job cannot be validated as asked, for the reasons synchronous validation would refuse it. Nothing was queued or charged. - `429`: Rate limited, the queue full, or the billing account can admit no more of this work this month. Nothing was queued. - `500`: Ironfang Finance failed. Not a verdict on anything. - `503`: The release's engine is not available, durable jobs are not configured, or billing is briefly unavailable. Nothing was queued. - `504`: A PDF could not be inspected within the admission deadline. Nothing was queued. --- [API](https://skmtc.dev/ironfang/apis/ironfang-finance-e-invoicing-api-2.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-finance-e-invoicing-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-finance-e-invoicing-api-2/revisions/8140667e556b?raw)