{
  "openapi": "3.0.3",
  "info": {
    "title": "Nima3DPrint Partner API",
    "version": "1.4.0",
    "description": "Place made-to-order custom 3D figurine orders from your own shop. The API works the same way as ordering in your partner account: your discount applies, prices are always calculated by us, and the order follows the normal flow (design preview, approval, production, shipping under your sender label). The customer pays you in your own shop; we never touch that money.\n\nAuthenticate with a key from the API tab in your partner dashboard: `Authorization: Bearer n3dp_live_...`. Keys belong on a server, never in a browser. All requests use HTTPS. Errors are JSON `{ \"error\": { \"code\", \"message\" } }`. Requests are rate limited (HTTP 429 with a `Retry-After` header).\n\nPayment: choose a saved card or a prepaid balance in your dashboard (Account). `POST /v1/orders` charges it immediately and returns a `payment` object; an unpaid order stays `awaiting_payment` and can be retried with `POST /v1/orders/{id}/pay` (HTTP 402 if still unpaid). Invoices are not part of the API yet."
  },
  "servers": [
    {
      "url": "https://nima3dprint.com/api/nima3dprint/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "summary": "Who the key belongs to",
        "description": "Partner name, current discount tier and whether production is open. Needs the `read` permission.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/templates": {
      "get": {
        "summary": "Ordering templates",
        "description": "The products you can order, their options, your price for every combination (after your discount, before shipping) and the shipping costs. Needs `read`.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/capacity": {
      "get": {
        "summary": "This week's capacity per template",
        "description": "How many pieces of each template can still be ordered this week (Monday to Sunday, Berlin time), shared by all partners and by our own website sales. `available` is null when no limit is set; when `soldOut` is true, `POST /orders` for that template answers 409 `sold_out`. Read-only. Needs `read`.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/uploads": {
      "post": {
        "summary": "Start a photo upload",
        "description": "Step 1. Returns a one-time address. PUT the raw file bytes there with the given Content-Type. JPEG, PNG or WebP, up to 10 MB. Needs `orders`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contentType",
                  "sizeBytes"
                ],
                "properties": {
                  "contentType": {
                    "type": "string",
                    "enum": [
                      "image/jpeg",
                      "image/png",
                      "image/webp"
                    ]
                  },
                  "sizeBytes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10485760
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Upload prepared"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/uploads/complete": {
      "post": {
        "summary": "Finish a photo upload",
        "description": "Step 2. We read and inspect the real file. Only a confirmed upload can be used in an order. Needs `orders`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "uploadId"
                ],
                "properties": {
                  "uploadId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Photo confirmed"
          },
          "404": {
            "description": "Unknown upload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The file has not been uploaded yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The photo was rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/orders": {
      "post": {
        "summary": "Place an order",
        "description": "Only the documented fields are accepted; any other field is refused with 400. Safe to retry: the same `externalOrderId` with the same content returns the existing order (200); a new order is 201. The same `externalOrderId` with different content is 409. If production is closed the order is accepted and held (`on_hold`). Needs `orders`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "An order with this externalOrderId already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderEnvelope"
                }
              }
            }
          },
          "201": {
            "description": "Order created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "externalOrderId reused with different content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The order cannot be placed as sent (options, photos, country, acknowledgements)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "summary": "List your API orders",
        "description": "Newest first. `limit` 1 to 50 (default 20). `before`: an ISO time, the createdAt of the last order you saw. Needs `read`.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "summary": "One order",
        "description": "Status and, once shipped, the carrier and tracking number. Needs `read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from your partner dashboard, starting with n3dp_live_"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, invalid, revoked or expired API key (code unauthorized or key_expired)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The key does not have the required permission",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "OrderRequest": {
        "type": "object",
        "required": [
          "externalOrderId",
          "templateId",
          "displayName",
          "shipping",
          "photos"
        ],
        "properties": {
          "externalOrderId": {
            "type": "string",
            "maxLength": 100,
            "description": "Your shop's own order number. Unique per partner; makes retries safe."
          },
          "templateId": {
            "type": "string",
            "description": "An id from GET /templates"
          },
          "options": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "One option id per option group of the template, e.g. {\"size\": \"small\"}"
          },
          "displayName": {
            "type": "string",
            "maxLength": 80,
            "description": "Shown on the order, e.g. the customer's first name"
          },
          "notes": {
            "type": "string",
            "maxLength": 2000
          },
          "photos": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": {
              "type": "string"
            },
            "description": "Upload ids confirmed with POST /uploads/complete"
          },
          "shipping": {
            "type": "object",
            "required": [
              "name",
              "country",
              "street",
              "houseNumber",
              "postalCode",
              "city"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 80
              },
              "country": {
                "type": "string",
                "minLength": 2,
                "maxLength": 2,
                "description": "ISO 3166-1 alpha-2, e.g. DE. Europe only."
              },
              "street": {
                "type": "string",
                "maxLength": 200
              },
              "houseNumber": {
                "type": "string",
                "maxLength": 40
              },
              "postalCode": {
                "type": "string",
                "maxLength": 20
              },
              "city": {
                "type": "string",
                "maxLength": 100
              },
              "addressExtra": {
                "type": "string",
                "maxLength": 200
              }
            }
          },
          "sender": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "Optional. Send in your own shop's name. Needs senderAck true. Leave out to use our default sender."
          },
          "senderAck": {
            "type": "boolean",
            "description": "Accept the shipping conditions for sending in your own name"
          },
          "acknowledgements": {
            "type": "object",
            "properties": {
              "ukImportVat": {
                "type": "boolean",
                "description": "Required for the United Kingdom: import VAT, duties and courier fees may apply on delivery"
              },
              "chImport": {
                "type": "boolean",
                "description": "Required for Switzerland: import taxes and handling fees may apply"
              }
            }
          }
        }
      },
      "Address": {
        "type": "object",
        "required": [
          "name",
          "country",
          "street",
          "houseNumber",
          "postalCode",
          "city"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "ISO 3166-1 alpha-2, e.g. DE. Europe only."
          },
          "street": {
            "type": "string",
            "maxLength": 200
          },
          "houseNumber": {
            "type": "string",
            "maxLength": 40
          },
          "postalCode": {
            "type": "string",
            "maxLength": 20
          },
          "city": {
            "type": "string",
            "maxLength": 100
          },
          "addressExtra": {
            "type": "string",
            "maxLength": 200
          }
        }
      },
      "OrderEnvelope": {
        "type": "object",
        "properties": {
          "order": {
            "$ref": "#/components/schemas/Order"
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "externalOrderId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting_payment",
              "on_hold",
              "new",
              "in_design",
              "waiting_approval",
              "design_approved",
              "production",
              "in_delivery",
              "delivered",
              "cancelled"
            ]
          },
          "holdReason": {
            "type": "string",
            "nullable": true,
            "description": "capacity: production is closed this week"
          },
          "orderNumber": {
            "type": "string"
          },
          "templateId": {
            "type": "string"
          },
          "options": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "currency": {
            "type": "string",
            "enum": [
              "eur"
            ]
          },
          "pricing": {
            "type": "object",
            "properties": {
              "listPriceCents": {
                "type": "integer"
              },
              "discountPercent": {
                "type": "integer"
              },
              "productCents": {
                "type": "integer"
              },
              "shippingCents": {
                "type": "integer"
              },
              "totalCents": {
                "type": "integer"
              }
            }
          },
          "shipping": {
            "$ref": "#/components/schemas/Address"
          },
          "shipment": {
            "type": "object",
            "properties": {
              "carrier": {
                "type": "string",
                "nullable": true
              },
              "trackingNumber": {
                "type": "string",
                "nullable": true
              },
              "shippedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}
