{
  "info": {
    "name": "External API V1",
    "description": "Partner-ready External API V1 collection (v1.1.0, updated 2026-02-23) with async convert flow and error-path probes.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://invoice-converter.com"
    },
    {
      "key": "api_key",
      "value": ""
    },
    {
      "key": "correlation_id",
      "value": "11111111-1111-4111-8111-111111111111"
    },
    {
      "key": "idempotency_key",
      "value": "idem-convert-001"
    },
    {
      "key": "task_id",
      "value": ""
    },
    {
      "key": "bad_api_key",
      "value": "icp_live_invalid_key"
    }
  ],
  "item": [
    {
      "name": "Happy Path",
      "item": [
        {
          "name": "1) Convert Invoice (202)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test('convert accepted', function () {",
                  "  pm.expect(pm.response.code).to.eql(202);",
                  "});",
                  "var body = pm.response.json();",
                  "pm.test('task_id returned', function () {",
                  "  pm.expect(body.task_id).to.be.a('string').and.not.empty;",
                  "});",
                  "if (body.task_id) { pm.collectionVariables.set('task_id', body.task_id); }"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{idempotency_key}}"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": ""
                },
                {
                  "key": "format",
                  "type": "text",
                  "value": "XRECHNUNG"
                },
                {
                  "key": "profile",
                  "type": "text",
                  "value": "XRECHNUNG"
                },
                {
                  "key": "jurisdiction",
                  "type": "text",
                  "value": "DE"
                },
                {
                  "key": "transaction_scope",
                  "type": "text",
                  "value": "B2G"
                },
                {
                  "key": "delivery_channel",
                  "type": "text",
                  "value": "PEPPOL"
                },
                {
                  "key": "reasoning_effort",
                  "type": "text",
                  "value": "none"
                },
                {
                  "key": "extraction_preference",
                  "type": "text",
                  "value": "auto"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/invoices:convert",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "invoices:convert"
              ]
            }
          }
        },
        {
          "name": "2) Poll Task Status (200)",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/tasks/{{task_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "tasks",
                "{{task_id}}"
              ]
            }
          }
        },
        {
          "name": "3) Fetch Result XML (200 | 202 | 422)",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/tasks/{{task_id}}/result?download=xml",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "tasks",
                "{{task_id}}",
                "result"
              ],
              "query": [
                {
                  "key": "download",
                  "value": "xml"
                }
              ]
            }
          }
        },
        {
          "name": "4) Fetch Result PDF (200 | 202 | 422)",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/tasks/{{task_id}}/result?download=pdf",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "tasks",
                "{{task_id}}",
                "result"
              ],
              "query": [
                {
                  "key": "download",
                  "value": "pdf"
                }
              ]
            }
          }
        }
      ]
    },
    {
      "name": "Error Scenarios",
      "item": [
        {
          "name": "400 Missing Idempotency-Key",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test('missing key is rejected', function () {",
                  "  pm.expect(pm.response.code).to.eql(400);",
                  "});",
                  "var body = pm.response.json();",
                  "pm.test('error code is IDEMPOTENCY_KEY_REQUIRED', function () {",
                  "  pm.expect(body.code).to.eql('IDEMPOTENCY_KEY_REQUIRED');",
                  "});"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": ""
                },
                {
                  "key": "format",
                  "type": "text",
                  "value": "XRECHNUNG"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/invoices:convert",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "invoices:convert"
              ]
            }
          }
        },
        {
          "name": "400 Invalid Idempotency-Key Format",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test('invalid key format is rejected', function () {",
                  "  pm.expect(pm.response.code).to.eql(400);",
                  "});",
                  "var body = pm.response.json();",
                  "pm.test('error code is INVALID_IDEMPOTENCY_KEY', function () {",
                  "  pm.expect(body.code).to.eql('INVALID_IDEMPOTENCY_KEY');",
                  "});"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              },
              {
                "key": "Idempotency-Key",
                "value": "invalid key with spaces"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": ""
                },
                {
                  "key": "format",
                  "type": "text",
                  "value": "XRECHNUNG"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/invoices:convert",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "invoices:convert"
              ]
            }
          }
        },
        {
          "name": "401 Invalid API Key",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test('invalid api key returns 401', function () {",
                  "  pm.expect(pm.response.code).to.eql(401);",
                  "});",
                  "var body = pm.response.json();",
                  "pm.test('error code is INVALID_API_KEY or AUTHENTICATION_REQUIRED', function () {",
                  "  pm.expect(['INVALID_API_KEY', 'AUTHENTICATION_REQUIRED']).to.include(body.code);",
                  "});"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{bad_api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/tasks/11111111-1111-4111-8111-111111111111",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "tasks",
                "11111111-1111-4111-8111-111111111111"
              ]
            }
          }
        },
        {
          "name": "409 Idempotency Conflict (Seed)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              },
              {
                "key": "Idempotency-Key",
                "value": "idem-conflict-001"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": ""
                },
                {
                  "key": "format",
                  "type": "text",
                  "value": "XRECHNUNG"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/invoices:convert",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "invoices:convert"
              ]
            }
          }
        },
        {
          "name": "409 Idempotency Conflict (Different Payload)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test('conflict or in-progress response', function () {",
                  "  pm.expect(pm.response.code).to.eql(409);",
                  "});",
                  "var body = pm.response.json();",
                  "pm.test('idempotency error code', function () {",
                  "  pm.expect(['IDEMPOTENCY_CONFLICT', 'IDEMPOTENCY_IN_PROGRESS']).to.include(body.code);",
                  "});"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              },
              {
                "key": "Idempotency-Key",
                "value": "idem-conflict-001"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": ""
                },
                {
                  "key": "format",
                  "type": "text",
                  "value": "ZUGFERD"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/invoices:convert",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "invoices:convert"
              ]
            }
          }
        },
        {
          "name": "400 Invalid download query",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test('invalid download query rejected', function () {",
                  "  pm.expect(pm.response.code).to.eql(400);",
                  "});",
                  "var body = pm.response.json();",
                  "pm.test('BAD_REQUEST code', function () {",
                  "  pm.expect(body.code).to.eql('BAD_REQUEST');",
                  "});"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/tasks/{{task_id}}/result?download=zip",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "tasks",
                "{{task_id}}",
                "result"
              ],
              "query": [
                {
                  "key": "download",
                  "value": "zip"
                }
              ]
            }
          }
        },
        {
          "name": "413 Payload too large (attach file >20MB)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              },
              {
                "key": "Idempotency-Key",
                "value": "idem-large-001"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": ""
                },
                {
                  "key": "format",
                  "type": "text",
                  "value": "XRECHNUNG"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/invoices:convert",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "invoices:convert"
              ]
            },
            "description": "Attach a local file larger than 20 MB to validate 413 PAYLOAD_TOO_LARGE behavior."
          }
        },
        {
          "name": "429/503 Probe (status endpoint)",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/tasks/{{task_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "tasks",
                "{{task_id}}"
              ]
            },
            "description": "Repeat quickly to observe 429 RATE_LIMITED; if dependencies are down this can return 503."
          }
        },
        {
          "name": "500/502/504 Probe (result endpoint)",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{api_key}}"
              },
              {
                "key": "X-Correlation-ID",
                "value": "{{correlation_id}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/tasks/{{task_id}}/result?download=xml",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "tasks",
                "{{task_id}}",
                "result"
              ],
              "query": [
                {
                  "key": "download",
                  "value": "xml"
                }
              ]
            },
            "description": "Depending on state and infrastructure this endpoint can return 202, 422, 500, 502, or 504."
          }
        }
      ]
    }
  ]
}