{
  "openapi": "3.1.0",
  "info": {
    "title": "InvoiceCraftly Developer Document API",
    "version": "1.0.0-beta",
    "description": "Beta API for generating invoice PDFs, checking EN16931-core readiness, and returning EN16931-core UBL/XML. Structured output is not a Peppol BIS artifact and does not perform network delivery.",
    "contact": {
      "name": "InvoiceCraftly",
      "url": "https://invoicecraftly.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://invoicecraftly.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer documentation",
    "url": "https://invoicecraftly.com/developers/"
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Documents",
      "description": "Invoice document generation."
    },
    {
      "name": "Structured invoicing",
      "description": "EN16931-core readiness and structured XML."
    }
  ],
  "paths": {
    "/api/v1/documents/pdf": {
      "post": {
        "tags": [
          "Documents"
        ],
        "summary": "Generate an invoice PDF",
        "description": "Generate a print-ready invoice PDF using the currently supported Ledger template. The beta supports invoice documents only.",
        "operationId": "generateInvoicePdf",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicDocumentV1"
              },
              "examples": {
                "invoice": {
                  "$ref": "#/components/examples/InvoiceDocument"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Print-ready invoice PDF.",
            "headers": {
              "X-Render-Duration-Ms": {
                "description": "Render duration when supplied by the rendering service.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Request body is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "invalidRequest": {
                    "$ref": "#/components/examples/InvalidRequest"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthenticationFailed"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/TargetNotSupported"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/RenderTimeout"
          }
        }
      }
    },
    "/api/v1/invoices/readiness": {
      "post": {
        "tags": [
          "Structured invoicing"
        ],
        "summary": "Check EN16931-core readiness",
        "description": "Return deterministic EN16931-core readiness diagnostics. This endpoint does not generate XML.",
        "operationId": "checkInvoiceReadiness",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicStructuredArtifactRequestV1"
              },
              "examples": {
                "notReady": {
                  "$ref": "#/components/examples/ReadinessRequestNotReady"
                },
                "ready": {
                  "$ref": "#/components/examples/ReadinessRequestReady"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Readiness result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessResponse"
                },
                "examples": {
                  "notReady": {
                    "$ref": "#/components/examples/ReadinessNotReady"
                  },
                  "ready": {
                    "$ref": "#/components/examples/ReadinessReady"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "invalidRequest": {
                    "$ref": "#/components/examples/InvalidStructuredRequest"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthenticationFailed"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/TargetNotSupported"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/v1/documents/structured": {
      "post": {
        "tags": [
          "Structured invoicing"
        ],
        "summary": "Generate EN16931-core structured XML",
        "description": "Return readiness diagnostics and, when ready, an EN16931-core UBL/XML artifact. This is not a Peppol BIS artifact and does not perform network delivery.",
        "operationId": "generateStructuredInvoice",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicStructuredArtifactRequestV1"
              },
              "examples": {
                "invoice": {
                  "$ref": "#/components/examples/StructuredInvoiceRequest"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Readiness result plus XML artifact when ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StructuredArtifactResponse"
                },
                "examples": {
                  "ready": {
                    "$ref": "#/components/examples/StructuredArtifactReady"
                  },
                  "notReady": {
                    "$ref": "#/components/examples/StructuredArtifactNotReady"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "invalidRequest": {
                    "$ref": "#/components/examples/InvalidStructuredRequest"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthenticationFailed"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/TargetNotSupported"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "dk_live_*"
      }
    },
    "responses": {
      "AuthenticationFailed": {
        "description": "API key is missing, invalid, or unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "authenticationFailed": {
                "$ref": "#/components/examples/AuthenticationFailed"
              }
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "Request body exceeds the accepted size.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "PDF generation requires application/json.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "TargetNotSupported": {
        "description": "The requested document type or template is recognized but not currently supported.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Monthly or service quota reached.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "string"
            },
            "description": "Retry delay in seconds when supplied."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "A required service is unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "RenderTimeout": {
        "description": "The PDF render exceeded its time budget.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "PublicDocumentV1": {
        "type": "object",
        "description": "Invoice document accepted by the Developer Document API. Invoice type and the Ledger template only.",
        "additionalProperties": false,
        "required": [
          "type",
          "issueDate",
          "currency",
          "seller",
          "buyer",
          "items"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "invoice"
            ],
            "description": "Only invoice is currently supported."
          },
          "number": {
            "type": "string"
          },
          "issueDate": {
            "type": "string",
            "format": "date"
          },
          "dueDate": {
            "type": "string",
            "format": "date"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "examples": [
              "USD",
              "EUR",
              "DKK",
              "NOK"
            ]
          },
          "locale": {
            "type": "string",
            "examples": [
              "en-US",
              "da-DK",
              "nb-NO"
            ]
          },
          "template": {
            "type": "string",
            "enum": [
              "ledger"
            ],
            "description": "Only Ledger is currently supported."
          },
          "seller": {
            "$ref": "#/components/schemas/Party"
          },
          "buyer": {
            "$ref": "#/components/schemas/Party"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/LineItem"
            }
          },
          "payment": {
            "$ref": "#/components/schemas/Payment"
          },
          "notes": {
            "type": "string"
          },
          "branding": {
            "$ref": "#/components/schemas/Branding"
          }
        }
      },
      "Party": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "addressLines"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "addressLines": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "LineItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "description",
          "quantity",
          "unitPrice",
          "taxRate"
        ],
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "unitPrice": {
            "type": "number",
            "minimum": 0
          },
          "taxRate": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "taxLabel": {
            "type": "string"
          }
        }
      },
      "Payment": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "bankName": {
            "type": "string"
          },
          "iban": {
            "type": "string"
          },
          "bic": {
            "type": "string"
          },
          "accountNumber": {
            "type": "string"
          },
          "routingNumber": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "poNumber": {
            "type": "string"
          },
          "terms": {
            "type": "string"
          },
          "dueText": {
            "type": "string"
          },
          "qrMode": {
            "type": "string",
            "enum": [
              "",
              "contact",
              "epc",
              "paymentLink"
            ]
          }
        }
      },
      "Branding": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "accentColor": {
            "type": "string",
            "pattern": "^#[0-9a-fA-F]{3,8}$"
          },
          "stampStyle": {
            "type": "string",
            "enum": [
              "round",
              "square",
              "none"
            ]
          },
          "logo": {
            "$ref": "#/components/schemas/Logo"
          }
        }
      },
      "Logo": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "mimeType"
        ],
        "properties": {
          "data": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "Base64 image data. Decoded size is limited to 512 KiB."
          },
          "mimeType": {
            "type": "string",
            "enum": [
              "image/png",
              "image/jpeg"
            ]
          }
        }
      },
      "PublicStructuredArtifactRequestV1": {
        "type": "object",
        "description": "A PublicDocumentV1 invoice plus an optional EN16931-core compliance supplement.",
        "additionalProperties": false,
        "required": [
          "document"
        ],
        "properties": {
          "document": {
            "$ref": "#/components/schemas/PublicDocumentV1"
          },
          "supplement": {
            "$ref": "#/components/schemas/ComplianceSupplementV1"
          }
        }
      },
      "ComplianceSupplementV1": {
        "type": "object",
        "description": "Optional EN16931-core metadata. Unknown nested fields are ignored by the current normalizer; listed fields are the supported public surface.",
        "properties": {
          "version": {
            "type": "integer",
            "enum": [
              1
            ]
          },
          "buyerReference": {
            "type": "string",
            "maxLength": 256
          },
          "seller": {
            "$ref": "#/components/schemas/ComplianceParty"
          },
          "buyer": {
            "$ref": "#/components/schemas/ComplianceParty"
          },
          "lines": {
            "type": "array",
            "maxItems": 250,
            "items": {
              "$ref": "#/components/schemas/ComplianceLine"
            }
          }
        }
      },
      "ComplianceParty": {
        "type": "object",
        "properties": {
          "postalAddress": {
            "$ref": "#/components/schemas/PostalAddress"
          },
          "electronicAddressSchemeId": {
            "type": "string"
          },
          "taxId": {
            "$ref": "#/components/schemas/TaxIdMetadata"
          },
          "vatIdentifier": {
            "type": "string",
            "maxLength": 256
          },
          "taxRegistrationIdentifier": {
            "$ref": "#/components/schemas/TaxRegistrationIdentifier"
          }
        }
      },
      "PostalAddress": {
        "type": "object",
        "properties": {
          "countryCode": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$"
          },
          "city": {
            "type": "string",
            "maxLength": 128
          },
          "postalCode": {
            "type": "string",
            "maxLength": 128
          },
          "region": {
            "type": "string",
            "maxLength": 128
          }
        }
      },
      "TaxIdMetadata": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "seller-id",
              "legal-registration",
              "tax-registration",
              "vat"
            ]
          },
          "schemeId": {
            "type": "string",
            "maxLength": 32
          },
          "taxSchemeId": {
            "type": "string",
            "maxLength": 32
          }
        }
      },
      "TaxRegistrationIdentifier": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "maxLength": 256
          },
          "taxSchemeId": {
            "type": "string",
            "maxLength": 32
          }
        }
      },
      "ComplianceLine": {
        "type": "object",
        "required": [
          "sourceIndex"
        ],
        "properties": {
          "sourceIndex": {
            "type": "integer",
            "minimum": 0
          },
          "unitCode": {
            "type": "string",
            "maxLength": 8
          },
          "vatCategoryCode": {
            "type": "string",
            "enum": [
              "AE",
              "B",
              "E",
              "G",
              "K",
              "L",
              "M",
              "O",
              "S",
              "Z"
            ]
          },
          "vatExemptionReason": {
            "type": "string",
            "maxLength": 256
          },
          "vatExemptionReasonCode": {
            "type": "string",
            "maxLength": 64
          }
        }
      },
      "ReadinessResponse": {
        "type": "object",
        "description": "Deterministic EN16931-core readiness diagnostics. Not an official conformance result.",
        "required": [
          "apiVersion",
          "profileId",
          "specificationIdentifier",
          "ready",
          "gaps"
        ],
        "properties": {
          "apiVersion": {
            "type": "string",
            "const": "v1"
          },
          "profileId": {
            "type": "string",
            "examples": [
              "en16931-core"
            ]
          },
          "specificationIdentifier": {
            "type": "string",
            "examples": [
              "urn:cen.eu:en16931:2017"
            ]
          },
          "ready": {
            "type": "boolean"
          },
          "gaps": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "StructuredArtifactResponse": {
        "description": "Readiness diagnostics plus the EN16931-core UBL/XML artifact when the invoice is ready. Not a Peppol BIS artifact.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ReadinessResponse"
          },
          {
            "type": "object",
            "required": [
              "artifact"
            ],
            "properties": {
              "artifact": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "mediaType",
                      "content"
                    ],
                    "properties": {
                      "mediaType": {
                        "type": "string",
                        "const": "application/xml"
                      },
                      "content": {
                        "type": "string",
                        "description": "EN16931-core UBL/XML when ready."
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "ErrorEnvelope": {
        "type": "object",
        "description": "Stable error envelope used by every non-2xx JSON response.",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message",
              "requestId",
              "details"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "AUTHENTICATION_FAILED",
                  "INVALID_REQUEST",
                  "TARGET_NOT_SUPPORTED",
                  "RATE_LIMITED",
                  "RENDER_TIMEOUT",
                  "PDF_RENDER_FAILED"
                ]
              },
              "message": {
                "type": "string"
              },
              "requestId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "details": {
                "type": "array",
                "items": {}
              }
            }
          }
        }
      }
    },
    "examples": {
      "InvoiceDocument": {
        "summary": "Invoice PDF request (Ledger template)",
        "value": {
          "type": "invoice",
          "number": "INV-1042",
          "issueDate": "2026-09-05",
          "dueDate": "2026-09-19",
          "currency": "USD",
          "seller": {
            "name": "Fixture Seller Studio",
            "addressLines": [
              "12 Render Way",
              "Austin, TX 73301",
              "United States"
            ]
          },
          "buyer": {
            "name": "Fixture Buyer Co",
            "addressLines": [
              "400 Client Ave",
              "Denver, CO 80202",
              "United States"
            ]
          },
          "items": [
            {
              "description": "Brand design retainer",
              "quantity": 2,
              "unitPrice": 150,
              "taxRate": 8.25,
              "taxLabel": "Sales Tax"
            }
          ],
          "payment": {
            "iban": "DE89370400440532013000",
            "reference": "INV-1042",
            "terms": "Net 14"
          }
        }
      },
      "ReadinessRequestNotReady": {
        "summary": "Readiness request without EN16931-core supplement",
        "value": {
          "document": {
            "type": "invoice",
            "number": "INV-1042",
            "issueDate": "2026-09-05",
            "dueDate": "2026-09-19",
            "currency": "USD",
            "seller": {
              "name": "Fixture Seller Studio",
              "addressLines": [
                "12 Render Way",
                "Austin, TX 73301",
                "United States"
              ]
            },
            "buyer": {
              "name": "Fixture Buyer Co",
              "addressLines": [
                "400 Client Ave",
                "Denver, CO 80202",
                "United States"
              ]
            },
            "items": [
              {
                "description": "Brand design retainer",
                "quantity": 2,
                "unitPrice": 150,
                "taxRate": 8.25,
                "taxLabel": "Sales Tax"
              }
            ],
            "payment": {
              "iban": "DE89370400440532013000",
              "reference": "INV-1042",
              "terms": "Net 14"
            }
          }
        }
      },
      "ReadinessRequestReady": {
        "summary": "Readiness request with EN16931-core supplement",
        "value": {
          "document": {
            "type": "invoice",
            "number": "INV-1042",
            "issueDate": "2026-09-05",
            "dueDate": "2026-09-19",
            "currency": "NOK",
            "seller": {
              "name": "Fixture Seller Studio AS",
              "addressLines": [
                "Karl Johans gate 1",
                "0154 Oslo",
                "Norway"
              ]
            },
            "buyer": {
              "name": "Fixture Buyer AS",
              "addressLines": [
                "Storgata 10",
                "0184 Oslo",
                "Norway"
              ]
            },
            "items": [
              {
                "description": "Brand design retainer",
                "quantity": 2,
                "unitPrice": 1500,
                "taxRate": 25,
                "taxLabel": "MVA"
              }
            ],
            "payment": {
              "iban": "DE89370400440532013000",
              "reference": "INV-1042",
              "terms": "Net 14"
            }
          },
          "supplement": {
            "version": 1,
            "seller": {
              "postalAddress": {
                "countryCode": "NO",
                "city": "Oslo",
                "postalCode": "0154"
              },
              "taxId": {
                "role": "legal-registration",
                "schemeId": "0192"
              },
              "vatIdentifier": "NO123456785MVA"
            },
            "buyer": {
              "postalAddress": {
                "countryCode": "NO",
                "city": "Oslo",
                "postalCode": "0184"
              }
            },
            "lines": [
              {
                "sourceIndex": 0,
                "unitCode": "HUR",
                "vatCategoryCode": "S"
              }
            ]
          }
        }
      },
      "StructuredInvoiceRequest": {
        "summary": "Structured invoice request with EN16931-core supplement",
        "value": {
          "document": {
            "type": "invoice",
            "number": "INV-1042",
            "issueDate": "2026-09-05",
            "dueDate": "2026-09-19",
            "currency": "NOK",
            "seller": {
              "name": "Fixture Seller Studio AS",
              "addressLines": [
                "Karl Johans gate 1",
                "0154 Oslo",
                "Norway"
              ]
            },
            "buyer": {
              "name": "Fixture Buyer AS",
              "addressLines": [
                "Storgata 10",
                "0184 Oslo",
                "Norway"
              ]
            },
            "items": [
              {
                "description": "Brand design retainer",
                "quantity": 2,
                "unitPrice": 1500,
                "taxRate": 25,
                "taxLabel": "MVA"
              }
            ],
            "payment": {
              "iban": "DE89370400440532013000",
              "reference": "INV-1042",
              "terms": "Net 14"
            }
          },
          "supplement": {
            "version": 1,
            "seller": {
              "postalAddress": {
                "countryCode": "NO",
                "city": "Oslo",
                "postalCode": "0154"
              },
              "taxId": {
                "role": "legal-registration",
                "schemeId": "0192"
              },
              "vatIdentifier": "NO123456785MVA"
            },
            "buyer": {
              "postalAddress": {
                "countryCode": "NO",
                "city": "Oslo",
                "postalCode": "0184"
              }
            },
            "lines": [
              {
                "sourceIndex": 0,
                "unitCode": "HUR",
                "vatCategoryCode": "S"
              }
            ]
          }
        }
      },
      "ReadinessNotReady": {
        "summary": "Invoice is not ready; gaps explain why",
        "value": {
          "apiVersion": "v1",
          "profileId": "en16931-core",
          "specificationIdentifier": "urn:cen.eu:en16931:2017",
          "ready": false,
          "gaps": [
            {
              "id": "BR-09-SELLER-COUNTRY",
              "message": "Seller country code is required and must not be inferred from a free-form address or route locale."
            },
            {
              "id": "BR-11-BUYER-COUNTRY",
              "message": "Buyer country code is required and must not be inferred from a free-form address or route locale."
            },
            {
              "id": "BR-CO-26-SELLER-IDENTIFIER",
              "message": "EN16931 requires a seller identifier, seller legal registration identifier, or seller VAT identifier."
            },
            {
              "id": "BR-23-LINE-1",
              "message": "Invoice line 1 needs an explicit UN/ECE unit code; the free-form unit label is not converted automatically."
            },
            {
              "id": "BR-CO-04-LINE-1",
              "message": "Invoice line 1 needs an explicit EN16931 VAT category code; a numeric tax rate alone is not enough to choose the legal tax treatment."
            },
            {
              "id": "BR-CO-18-VAT-BREAKDOWN",
              "message": "No EN16931 VAT breakdown can be formed until invoice lines have explicit VAT categories and rates."
            }
          ]
        }
      },
      "ReadinessReady": {
        "summary": "Invoice is ready",
        "value": {
          "apiVersion": "v1",
          "profileId": "en16931-core",
          "specificationIdentifier": "urn:cen.eu:en16931:2017",
          "ready": true,
          "gaps": []
        }
      },
      "StructuredArtifactReady": {
        "summary": "Ready invoice with EN16931-core UBL/XML artifact",
        "value": {
          "apiVersion": "v1",
          "profileId": "en16931-core",
          "specificationIdentifier": "urn:cen.eu:en16931:2017",
          "ready": true,
          "gaps": [],
          "artifact": {
            "mediaType": "application/xml",
            "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\" xmlns:cac=\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\" xmlns:cbc=\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\"><cbc:CustomizationID>urn:cen.eu:en16931:2017</cbc:CustomizationID><cbc:ID>INV-1042</cbc:ID><cbc:IssueDate>2026-09-05</cbc:IssueDate><cbc:DueDate>2026-09-19</cbc:DueDate><cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode><cbc:DocumentCurrencyCode>NOK</cbc:DocumentCurrencyCode><cac:AccountingSupplierParty><cac:Party><cac:PostalAddress><cbc:StreetName>Karl Johans gate 1</cbc:StreetName><cbc:AdditionalStreetName>0154 Oslo</cbc:AdditionalStreetName><cbc:CityName>Oslo</cbc:CityName><cbc:PostalZone>0154</cbc:PostalZone><cac:AddressLine><cbc:Line>Norway</cbc:Line></cac:AddressLine><cac:Country><cbc:IdentificationCode>NO</cbc:IdentificationCode></cac:Country></cac:PostalAddress><cac:PartyTaxScheme><cbc:CompanyID>NO123456785MVA</cbc:CompanyID><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:PartyTaxScheme><cac:PartyLegalEntity><cbc:RegistrationName>Fixture Seller Studio AS</cbc:RegistrationName></cac:PartyLegalEntity></cac:Party></cac:AccountingSupplierParty><cac:AccountingCustomerParty><cac:Party><cac:PostalAddress><cbc:StreetName>Storgata 10</cbc:StreetName><cbc:AdditionalStreetName>0184 Oslo</cbc:AdditionalStreetName><cbc:CityName>Oslo</cbc:CityName><cbc:PostalZone>0184</cbc:PostalZone><cac:AddressLine><cbc:Line>Norway</cbc:Line></cac:AddressLine><cac:Country><cbc:IdentificationCode>NO</cbc:IdentificationCode></cac:Country></cac:PostalAddress><cac:PartyLegalEntity><cbc:RegistrationName>Fixture Buyer AS</cbc:RegistrationName></cac:PartyLegalEntity></cac:Party></cac:AccountingCustomerParty><cac:PaymentMeans><cbc:PaymentMeansCode>30</cbc:PaymentMeansCode><cbc:PaymentID>INV-1042</cbc:PaymentID><cac:PayeeFinancialAccount><cbc:ID>DE89370400440532013000</cbc:ID></cac:PayeeFinancialAccount></cac:PaymentMeans><cac:PaymentTerms><cbc:Note>Net 14</cbc:Note></cac:PaymentTerms><cac:TaxTotal><cbc:TaxAmount currencyID=\"NOK\">750</cbc:TaxAmount><cac:TaxSubtotal><cbc:TaxableAmount currencyID=\"NOK\">3000</cbc:TaxableAmount><cbc:TaxAmount currencyID=\"NOK\">750</cbc:TaxAmount><cac:TaxCategory><cbc:ID>S</cbc:ID><cbc:Percent>25</cbc:Percent><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:TaxCategory></cac:TaxSubtotal></cac:TaxTotal><cac:LegalMonetaryTotal><cbc:LineExtensionAmount currencyID=\"NOK\">3000</cbc:LineExtensionAmount><cbc:TaxExclusiveAmount currencyID=\"NOK\">3000</cbc:TaxExclusiveAmount><cbc:TaxInclusiveAmount currencyID=\"NOK\">3750</cbc:TaxInclusiveAmount><cbc:PayableAmount currencyID=\"NOK\">3750</cbc:PayableAmount></cac:LegalMonetaryTotal><cac:InvoiceLine><cbc:ID>1</cbc:ID><cbc:InvoicedQuantity unitCode=\"HUR\">2</cbc:InvoicedQuantity><cbc:LineExtensionAmount currencyID=\"NOK\">3000</cbc:LineExtensionAmount><cac:Item><cbc:Name>Brand design retainer</cbc:Name><cac:ClassifiedTaxCategory><cbc:ID>S</cbc:ID><cbc:Percent>25</cbc:Percent><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:ClassifiedTaxCategory></cac:Item><cac:Price><cbc:PriceAmount currencyID=\"NOK\">1500</cbc:PriceAmount></cac:Price></cac:InvoiceLine></Invoice>"
          }
        }
      },
      "StructuredArtifactNotReady": {
        "summary": "Not-ready invoice: no artifact is returned",
        "value": {
          "apiVersion": "v1",
          "profileId": "en16931-core",
          "specificationIdentifier": "urn:cen.eu:en16931:2017",
          "ready": false,
          "gaps": [
            {
              "id": "BR-09-SELLER-COUNTRY",
              "message": "Seller country code is required and must not be inferred from a free-form address or route locale."
            },
            {
              "id": "BR-11-BUYER-COUNTRY",
              "message": "Buyer country code is required and must not be inferred from a free-form address or route locale."
            },
            {
              "id": "BR-CO-26-SELLER-IDENTIFIER",
              "message": "EN16931 requires a seller identifier, seller legal registration identifier, or seller VAT identifier."
            },
            {
              "id": "BR-23-LINE-1",
              "message": "Invoice line 1 needs an explicit UN/ECE unit code; the free-form unit label is not converted automatically."
            },
            {
              "id": "BR-CO-04-LINE-1",
              "message": "Invoice line 1 needs an explicit EN16931 VAT category code; a numeric tax rate alone is not enough to choose the legal tax treatment."
            },
            {
              "id": "BR-CO-18-VAT-BREAKDOWN",
              "message": "No EN16931 VAT breakdown can be formed until invoice lines have explicit VAT categories and rates."
            }
          ],
          "artifact": null
        }
      },
      "InvalidRequest": {
        "summary": "Invalid PDF request",
        "value": {
          "error": {
            "code": "INVALID_REQUEST",
            "message": "Request could not be processed.",
            "requestId": null,
            "details": []
          }
        }
      },
      "InvalidStructuredRequest": {
        "summary": "Invalid structured or readiness request",
        "value": {
          "error": {
            "code": "INVALID_REQUEST",
            "message": "The request body is not a valid structured artifact request.",
            "requestId": null,
            "details": []
          }
        }
      },
      "AuthenticationFailed": {
        "summary": "Missing or incorrect API key",
        "value": {
          "error": {
            "code": "AUTHENTICATION_FAILED",
            "message": "Missing or incorrect API key.",
            "requestId": null,
            "details": []
          }
        }
      }
    }
  }
}