{
  "openapi": "3.1.0",
  "info": {
    "title": "GetBrazilDocs API (preview)",
    "version": "1.0.0-preview",
    "summary": "Plan FBI checks, apostilles and sworn translations backwards from a Brazil deadline, get itemized quotes (partner cost at cost + our service fee), and start a draft request that the customer submits (self-service: no approval step; concierge: Camila Mota approves before any payment).",
    "description": "GetBrazilDocs plans the documents for a Brazil visa or residence filing (Polícia Federal, MigranteWeb, consulates): criminal record (FBI check), apostille, sworn translation and work contract, backwards from the submit date, and coordinates licensed partners.\n\nPREVIEW: every figure is a test, partner-stated or assumed figure, nothing is charged, and no order service is live in production. Timings are estimates; nobody can promise authority decisions.\n\nPRICING: each sellable service is priced at partner cost, shown at cost line by line (partner fee, courier, and any official fee we pass through), plus our service fee = max(US$30, 10% × that service's partner cost). Kits are bundles: their total is the sum of the computed service prices. Two service levels: self-service (the services only, online, with NO checks: you choose, confirm that nobody from GetBrazilDocs checks your documents, pay and upload; we forward your documents to the providers as they are) or concierge (+ US$99 flat per order, not marked up: Camila Mota checks your documents and approves before you pay, replying within 24 hours; then we manage everything, with calendar invites and requests for action). Price on request: other document types (for example a criminal record from another country) are described in a text box, never priced in the total, and quoted by hand by Camila Mota within 24 hours at either level. Price one service at a time with /api/v1/pricing/services/{serviceId} (same engine as quotes).\n\nDIGITAL COPY (included): A color PDF scan of the apostilled FBI check, emailed on the day the apostilled paper is collected from the State Department. No extra line, no extra fee. Use it to file on MigranteWeb (the Polícia Federal online residence filing) and to start the sworn translation. This is a convenience scan, not an official e-apostille: the US State Department apostilles paper only. The Polícia Federal may still ask for the paper original (especially at the CRNM registration appointment), and consulates may require originals.\n\nPAPER ORIGINAL (recommended add-on for criminal records, item paper-original or paperOriginal: true): DHL courier at cost (US$95 on the default route) plus our service fee (max(US$30, 10%)). 2–5 days after collection (partner estimate). The planner recommends it on every channel, including MigranteWeb (most filings end at a PF appointment where the original must be shown); digital PDF only is cheaper, but the PF may ask to see the original at your appointment. Plain /estimates without a plan price exactly the items given. The apostilled work contract needs no physical copy: its DHL original (90 EUR at cost + our fee) is an optional add-on, off by default (item contract-courier or contractPaperOriginal: true).\n\nValidity: criminal records are planned on one 90-day window everywhere (from the issue date to the filing day; we treat day 90 as too old and keep margins). A few consulates ask for records issued within 60 days — check your consulate's page. The window is an information note, not a choice. The old validityOverride / validityDays / o inputs are accepted and ignored (planner responses list them under ignoredFields).\n\nPLANNER MILESTONES: digital-copy (digital copy ready, file on MigranteWeb) and paper-original (paper original in Brazil; recommended, in the critical path only for a PF appointment or a consulate). quickSubmission explains filing on MigranteWeb without waiting for the paper. Every timing is labelled partner-stated, verified or assumption; no timing is guaranteed.\n\nWHITE-LABEL: We place and pay every partner order ourselves, under the GetBrazilDocs name (white-label: no partner payment links, and provider names are never shown). At both levels you deal only with GetBrazilDocs (hello@getbrazildocs.com). Quotes, status, emails and calendar files never name providers.\n\nORDER FLOW: an order intent creates a DRAFT. The customer adds key dates, nationality and the passport photo page (required) and submits it themselves. SELF-SERVICE: submit also needs noCheckConsent: true (the customer confirms nobody from GetBrazilDocs checks their documents; stored with a timestamp; the server refuses submit and checkout without it); the quote is then LOCKED at once (stage approved, decision auto_locked) with no approval step. CONCIERGE: the request is submitted to Camila Mota (OAB/CE 50.065), who checks the documents and approves, requests changes (changes_requested → the customer updates and resubmits) or declines, replying within 24 hours; no checkout exists before her approval. A locked quote has a Stripe test-mode pay link valid 7 days (approved → expired if unpaid). Only payment (paid) opens provider work. Statuses: draft, submitted, changes_requested, declined, approved, expired, paid, edo_submitted, prints_pending, card_mailed, fingerprints_rejected_new_card_needed, fbi_result, apostille_in_progress, scan_ready, translation_in_progress, notary_session_booked, awaiting_predelivery_check, courier_to_brazil, delivered, completed, on_hold, cancelled.\n\nSERVICE LEVELS: self-service or concierge (US$99 flat per order, part of the single locked quote). After payment, at both levels, the client uploads documents and answers requests for action on the request page (POST /api/v1/requests/{token}/inputs, human only). Self-service: we forward them to the providers as they are. Concierge: Camila checks them, we send them, book appointments, email calendar invites (.ics), and Camila checks the finished documents (awaiting_predelivery_check → delivered). The order calendar (RFC 5545) is at GET /api/v1/requests/{token}/calendar.ics (private request link).\n\nAgents may read, plan, estimate and start a draft request (order intent) for a human. Agents may NOT submit, upload documents, accept terms, give consent or pay: the order intent returns a requestUrl that the customer must open and complete themselves.\n\nRate limits per IP: tools and quotes 60/minute, order intents 10/hour, MCP 120/minute. Send X-Agent-Name to identify your agent. Policy: https://getbrazildocs.com/agent-policy/",
    "contact": {
      "name": "Camila Mota",
      "email": "hello@getbrazildocs.com",
      "url": "https://getbrazildocs.com/agent-policy/"
    },
    "termsOfService": "https://getbrazildocs.com/terms/"
  },
  "servers": [
    {
      "url": "https://getbrazildocs.com",
      "description": "Production domain placeholder (not live)"
    },
    {
      "url": "http://127.0.0.1:8787",
      "description": "Local dev (npm run api:dev or wrangler dev)"
    }
  ],
  "externalDocs": {
    "description": "For agents: API, MCP and policy",
    "url": "https://getbrazildocs.com/for-agents/"
  },
  "tags": [
    {
      "name": "planning",
      "description": "Stateless planning tools. Nothing is stored."
    },
    {
      "name": "catalog",
      "description": "Services, the fee policy and per-service pricing."
    },
    {
      "name": "orders",
      "description": "Order intents (draft requests a human submits; Camila Mota approves before payment) and read-only status."
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "health",
        "tags": [
          "catalog"
        ],
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/planner": {
      "post": {
        "operationId": "planDeadline",
        "tags": [
          "planning"
        ],
        "summary": "Plan backwards from a submit date",
        "description": "Returns dated steps (FBI request, prints, card mailing, apostille, digital copy, optional paper original, translation), two milestones (digital copy ready / paper original in Brazil), the quick-submission path, the paper recommendation, the start-by date, validity window, recommended services and a quote for them at test prices. Dates are planning estimates.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlannerRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlannerResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/estimates": {
      "post": {
        "operationId": "estimateQuote",
        "tags": [
          "planning"
        ],
        "summary": "Itemized quote for a selection (test prices)",
        "description": "Stateless. Give items (bundles) or a planner input to use the recommended items. Each service shows its at-cost lines (partner fee, courier, passed-through official fees) and our service fee line; serviceLevel=concierge adds the flat concierge fee (default self-service; legacy lawyerReview: true = concierge); paperOriginal adds the paper original by courier (its own service; recommended for criminal records), contractPaperOriginal the optional contract original by DHL; price-on-request items are never priced. FBI services always include the digital copy at no extra fee. Nothing is stored or charged.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/fbi-validity-clock": {
      "get": {
        "operationId": "fbiValidityClockGet",
        "tags": [
          "planning"
        ],
        "summary": "Is an FBI result still in date on the submit date?",
        "parameters": [
          {
            "name": "issueDate",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Issue date printed on the FBI result"
          },
          {
            "name": "submitDate",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pf",
                "migranteweb",
                "consulate"
              ]
            }
          },
          {
            "name": "consulate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "chicago",
                "san-francisco",
                "washington",
                "other"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidityResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "fbiValidityClock",
        "tags": [
          "planning"
        ],
        "summary": "Is an FBI result still in date on the submit date?",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidityRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidityResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/fbi-route-checker": {
      "get": {
        "operationId": "fbiRouteCheckerGet",
        "tags": [
          "planning"
        ],
        "summary": "Which FBI route, prints, apostille and mail legs apply",
        "parameters": [
          {
            "name": "citizenship",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "us-citizen",
                "green-card",
                "other"
              ]
            }
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "brazil",
                "us",
                "elsewhere"
              ]
            }
          },
          {
            "name": "destination",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pf",
                "migranteweb",
                "consulate"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RouteResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "fbiRouteChecker",
        "tags": [
          "planning"
        ],
        "summary": "Which FBI route, prints, apostille and mail legs apply",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RouteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RouteResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/translation-cost": {
      "get": {
        "operationId": "translationCostGet",
        "tags": [
          "planning"
        ],
        "summary": "Count sworn-translation pages and estimate cost in BRL",
        "parameters": [
          {
            "name": "fbi",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            }
          },
          {
            "name": "apostille",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            }
          },
          {
            "name": "birth",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            }
          },
          {
            "name": "marriage",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            }
          },
          {
            "name": "contract",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            }
          },
          {
            "name": "other",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslationResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "translationCost",
        "tags": [
          "planning"
        ],
        "summary": "Count sworn-translation pages and estimate cost in BRL",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranslationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslationResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/order-intents": {
      "post": {
        "operationId": "createOrderIntent",
        "tags": [
          "orders"
        ],
        "summary": "Start a draft request (quote + order intent) for a human to submit",
        "description": "Stores a quote and an order in status draft, emails the customer, and returns a status URL and a HUMAN request URL. It does not submit, take payment or give consent. Requests that include consent, payment, approval or stage fields are refused (422 human-only). Give the requestUrl to the customer: they add the passport photo page and submit (self-service: also the required \"nobody checks my documents\" box; concierge: Camila Mota then approves before any payment). Send an Idempotency-Key header to make retries safe.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderIntentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderIntent"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/orders/{token}": {
      "get": {
        "operationId": "getOrderStatus",
        "tags": [
          "orders"
        ],
        "summary": "Read-only order status by public status token",
        "description": "The token is the last part of the statusUrl. Read-only: shows stage, history, next action and the quote. Do not republish status pages (see the agent policy).",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 40,
              "maxLength": 64
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderStatus"
                }
              }
            }
          },
          "404": {
            "description": "No such order.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pricing": {
      "get": {
        "operationId": "getPricing",
        "tags": [
          "catalog"
        ],
        "summary": "Fee policy, worked examples per service, service levels, official fees",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pricing"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pricing/services/{serviceId}": {
      "get": {
        "operationId": "priceServiceGet",
        "tags": [
          "catalog"
        ],
        "summary": "Price ONE service (modular; for GetBrazilVisa and agents)",
        "description": "Same engine and rule as every quote: at-cost lines + service fee = max(minimum, percent × partner cost). Use pages for sworn translation.",
        "parameters": [
          {
            "name": "serviceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "fbi-apostille",
                "fbi-apostille-express",
                "apostille-only",
                "paper-original",
                "sworn-translation",
                "notary-contract",
                "contract-courier"
              ]
            }
          },
          {
            "name": "pages",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            },
            "description": "Sworn translation pages (default 1)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceQuote"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "priceService",
        "tags": [
          "catalog"
        ],
        "summary": "Price ONE service (modular; for GetBrazilVisa and agents)",
        "parameters": [
          {
            "name": "serviceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "fbi-apostille",
                "fbi-apostille-express",
                "apostille-only",
                "paper-original",
                "sworn-translation",
                "notary-contract",
                "contract-courier"
              ]
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pages": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceQuote"
                }
              }
            }
          },
          "400": {
            "description": "Bad JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. `errors` lists each field.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/services": {
      "get": {
        "operationId": "getServices",
        "tags": [
          "catalog"
        ],
        "summary": "Services, what each includes, and its limits",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Services"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details.",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Health": {
        "type": "object",
        "required": [
          "ok",
          "version",
          "preview"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "version": {
            "type": "string"
          },
          "preview": {
            "type": "boolean"
          },
          "db": {
            "type": "string"
          }
        }
      },
      "PlannerRequest": {
        "type": "object",
        "required": [
          "submitDate",
          "channel",
          "docs"
        ],
        "properties": {
          "submitDate": {
            "type": "string",
            "format": "date",
            "description": "Date the person must submit (appointment, upload deadline or exigência date)."
          },
          "channel": {
            "type": "string",
            "enum": [
              "pf",
              "migranteweb",
              "consulate"
            ],
            "description": "pf = Polícia Federal appointment; migranteweb = online residence portal; consulate = Brazilian consulate abroad."
          },
          "consulate": {
            "type": "string",
            "enum": [
              "chicago",
              "san-francisco",
              "washington",
              "other"
            ],
            "description": "Only for channel=consulate."
          },
          "citizenship": {
            "type": "string",
            "enum": [
              "us-citizen",
              "green-card",
              "other"
            ],
            "description": "US status. Only matters with an FBI check (which FBI channels exist). Optional."
          },
          "location": {
            "type": "string",
            "enum": [
              "brazil",
              "us",
              "elsewhere"
            ],
            "default": "brazil"
          },
          "nationality": {
            "type": "string",
            "maxLength": 60,
            "description": "Nationality as on the passport (free text). Optional."
          },
          "docs": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "fbi",
                "have-fbi-pdf",
                "contract",
                "translation",
                "other"
              ]
            },
            "description": "Documents needed (required). fbi = new FBI background check (only if the person lived in the US); have-fbi-pdf = apostille of an FBI report already held; contract = work contract notarization + apostille; translation = sworn translation; other = price on request (free text, quoted by hand, never in the total)."
          },
          "fbiIssueDate": {
            "type": "string",
            "format": "date",
            "description": "With docs=have-fbi-pdf: issue date of the result already held."
          },
          "extraPages": {
            "type": "integer",
            "minimum": 0,
            "maximum": 50,
            "description": "Other pages to translate."
          },
          "contractPages": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "Pages of the work contract (default 3)."
          },
          "translateItems": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "fbi",
                "contract"
              ]
            },
            "description": "Which package documents our translator translates (default both). Other pages are always translated."
          },
          "serviceLevel": {
            "type": "string",
            "enum": [
              "concierge",
              "self-service"
            ],
            "description": "Changes the timeline detail only. Default concierge."
          },
          "otherRequest": {
            "type": "string",
            "maxLength": 2000,
            "description": "With docs=other (price on request): the document type the person needs, e.g. a criminal record from another country. Never in the total; quoted by hand."
          },
          "paperOriginal": {
            "type": "boolean",
            "description": "Criminal record: paper original by DHL. Omit = recommended on every channel (on MigranteWeb it does not hold up the online filing). false = cheaper PDF only (the PF may ask to see the original)."
          },
          "contractPaperOriginal": {
            "type": "boolean",
            "description": "Work contract original by DHL. Optional, off by default (the scan is enough)."
          },
          "validityOverride": {
            "description": "Removed. Accepted and ignored: the validity window is 90 days on every channel and consulate.",
            "deprecated": true
          },
          "fbiRoute": {
            "type": "string",
            "enum": [
              "standard",
              "rush"
            ],
            "description": "FBI kit handling. Omit = standard if it fits with a week of slack, else rush."
          },
          "today": {
            "type": "string",
            "format": "date",
            "description": "Optional reference date (defaults to today, UTC)."
          }
        }
      },
      "PlannerResponse": {
        "type": "object",
        "required": [
          "input",
          "headline",
          "plan",
          "planUrl",
          "milestones",
          "quickSubmission",
          "paperOriginal",
          "digitalCopy",
          "notes"
        ],
        "properties": {
          "input": {
            "type": "object"
          },
          "headline": {
            "type": "string"
          },
          "milestones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Milestone"
            },
            "description": "Empty when the plan has no FBI route."
          },
          "quickSubmission": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/QuickSubmission"
              },
              {
                "type": "null"
              }
            ]
          },
          "paperOriginal": {
            "$ref": "#/components/schemas/PaperChoice"
          },
          "digitalCopy": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "included",
                  "extraFeeUsd",
                  "notEApostille"
                ],
                "properties": {
                  "included": {
                    "const": true
                  },
                  "extraFeeUsd": {
                    "const": 0
                  },
                  "notEApostille": {
                    "const": true
                  },
                  "note": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "plan": {
            "type": "object",
            "required": [
              "status",
              "messages",
              "steps",
              "validity",
              "recommended",
              "milestones",
              "paper",
              "quickSubmission"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ok",
                  "tight",
                  "at-risk",
                  "too-soon",
                  "past",
                  "invalid-date",
                  "no-docs",
                  "expired-pdf",
                  "window-closed"
                ]
              },
              "messages": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "title",
                    "start",
                    "end",
                    "mode",
                    "status"
                  ]
                }
              },
              "startBy": {
                "type": "string",
                "format": "date"
              },
              "recommendedStart": {
                "type": "string",
                "format": "date"
              },
              "earliestFeasible": {
                "type": "string",
                "format": "date"
              },
              "validity": {
                "type": "object"
              },
              "recommended": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "pf-full-kit",
                    "fbi-kit",
                    "fbi-kit-express",
                    "apostille-courier",
                    "paper-original",
                    "contract-kit",
                    "contract-courier",
                    "translation",
                    "price-on-request"
                  ]
                }
              },
              "fbiRoute": {
                "type": "string",
                "enum": [
                  "standard",
                  "rush"
                ]
              },
              "milestones": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Milestone"
                }
              },
              "paper": {
                "$ref": "#/components/schemas/PaperChoice"
              },
              "quickSubmission": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/QuickSubmission"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "planUrl": {
            "type": "string",
            "format": "uri",
            "description": "Shareable link that opens this plan on the site."
          },
          "recommendedQuote": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Quote"
              },
              {
                "type": "null"
              }
            ]
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Milestone": {
        "type": "object",
        "required": [
          "id",
          "title",
          "date",
          "earliest",
          "selected",
          "inCriticalPath",
          "detail",
          "timing"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "digital-copy",
              "paper-original"
            ]
          },
          "title": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Planned date (upper end of the estimate). Not guaranteed."
          },
          "earliest": {
            "type": "string",
            "format": "date"
          },
          "selected": {
            "type": "boolean",
            "description": "paper-original: false = optional add-on not selected."
          },
          "inCriticalPath": {
            "type": "boolean"
          },
          "detail": {
            "type": "string"
          },
          "timing": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "label",
                "value",
                "status"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "verified",
                    "first-party",
                    "assumption",
                    "partner-stated"
                  ]
                }
              }
            }
          }
        }
      },
      "PaperChoice": {
        "type": "object",
        "required": [
          "recommended",
          "selected",
          "chosen",
          "reason"
        ],
        "properties": {
          "recommended": {
            "type": "boolean"
          },
          "selected": {
            "type": "boolean"
          },
          "chosen": {
            "type": "boolean",
            "description": "true = the customer chose; false = the recommendation applies."
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "QuickSubmission": {
        "type": "object",
        "required": [
          "available",
          "digitalCopyOn",
          "fileFrom",
          "text"
        ],
        "properties": {
          "available": {
            "type": "boolean"
          },
          "digitalCopyOn": {
            "type": "string",
            "format": "date"
          },
          "fileFrom": {
            "type": "string",
            "format": "date",
            "description": "Digital copy + sworn translation ready."
          },
          "text": {
            "type": "string"
          }
        }
      },
      "DigitalCopy": {
        "type": "object",
        "required": [
          "included",
          "priceUsd",
          "notEApostille",
          "caveat"
        ],
        "description": "Included in FBI services: a convenience scan, not an e-apostille.",
        "properties": {
          "included": {
            "const": true
          },
          "priceUsd": {
            "const": 0
          },
          "what": {
            "type": "string"
          },
          "use": {
            "type": "string"
          },
          "notEApostille": {
            "const": true
          },
          "caveat": {
            "type": "string"
          }
        }
      },
      "PaperOriginal": {
        "type": "object",
        "required": [
          "selected",
          "optional",
          "serviceId",
          "totalUsd"
        ],
        "properties": {
          "selected": {
            "type": "boolean"
          },
          "optional": {
            "const": true
          },
          "serviceId": {
            "const": "paper-original"
          },
          "totalUsd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Price of the add-on service when selected (courier at cost + service fee)."
          },
          "recommendedFor": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "notNeededFor": {
            "type": "string"
          },
          "transitDays": {
            "type": "object",
            "properties": {
              "min": {
                "type": "integer"
              },
              "max": {
                "type": "integer"
              },
              "status": {
                "type": "string"
              }
            }
          }
        }
      },
      "EstimateRequest": {
        "type": "object",
        "description": "Give items, or plan (a planner input; its recommended items are used).",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "pf-full-kit",
                "fbi-kit",
                "fbi-kit-express",
                "apostille-courier",
                "paper-original",
                "contract-kit",
                "contract-courier",
                "translation",
                "price-on-request"
              ]
            },
            "description": "One FBI-route item per order (pf-full-kit, fbi-kit, fbi-kit-express, apostille-courier); the last one wins."
          },
          "translationPages": {
            "type": "integer",
            "minimum": 0,
            "maximum": 50,
            "description": "Extra pages for the Sworn translation item (added to the kit pages in one service)."
          },
          "serviceLevel": {
            "type": "string",
            "enum": [
              "self-service",
              "concierge"
            ],
            "default": "self-service",
            "description": "concierge adds Concierge service (Camila Mota, OAB/CE 50.065, and our team): US$99 flat per order, not marked up."
          },
          "lawyerReview": {
            "type": "boolean",
            "deprecated": true,
            "description": "Legacy alias: true = serviceLevel concierge."
          },
          "paperOriginal": {
            "type": "boolean",
            "description": "true = add the paper original by courier (needs an FBI item; same as item paper-original; recommended). false = digital copy only. Omit = as items say."
          },
          "contractPaperOriginal": {
            "type": "boolean",
            "description": "true = add the contract original by DHL (needs contract-kit; same as item contract-courier). Default off."
          },
          "plan": {
            "$ref": "#/components/schemas/PlannerRequest"
          }
        }
      },
      "QuoteLine": {
        "type": "object",
        "required": [
          "kind",
          "id",
          "label",
          "qty",
          "unit",
          "unitUsd",
          "totalUsd",
          "atCost",
          "status"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "partner-fee",
              "shipping",
              "government-fee",
              "service-fee",
              "add-on"
            ]
          },
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "qty": {
            "type": "integer"
          },
          "unit": {
            "type": "string",
            "enum": [
              "order",
              "page",
              "shipment",
              "document"
            ]
          },
          "unitUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "totalUsd": {
            "type": [
              "number",
              "null"
            ],
            "description": "null = not priced yet."
          },
          "atCost": {
            "type": "boolean",
            "description": "true = pass-through at cost; false = our service fee or an add-on."
          },
          "status": {
            "type": "string",
            "enum": [
              "partner-stated",
              "assumed",
              "official",
              "test",
              "tbd",
              "unsupported",
              "rule"
            ],
            "description": "assumed = no confirmed partner rate yet; rule = computed by the fee rule."
          },
          "original": {
            "type": "object",
            "description": "Non-USD figure and the ASSUMED FX rate used.",
            "properties": {
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              },
              "fxRate": {
                "type": "number"
              },
              "fxStatus": {
                "const": "assumed"
              }
            }
          },
          "note": {
            "type": "string"
          }
        }
      },
      "ServiceFee": {
        "type": "object",
        "required": [
          "percent",
          "minimumUsd",
          "percentOfCostUsd",
          "applied",
          "amountUsd"
        ],
        "properties": {
          "percent": {
            "type": "number"
          },
          "minimumUsd": {
            "type": "number"
          },
          "percentOfCostUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "applied": {
            "enum": [
              "minimum",
              "percent",
              null
            ]
          },
          "amountUsd": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "ServiceQuote": {
        "type": "object",
        "required": [
          "serviceId",
          "name",
          "kind",
          "qty",
          "unit",
          "lines",
          "partnerCostUsd",
          "serviceFee",
          "totalUsd",
          "flags",
          "complete"
        ],
        "properties": {
          "serviceId": {
            "type": "string",
            "enum": [
              "fbi-apostille",
              "fbi-apostille-express",
              "apostille-only",
              "paper-original",
              "sworn-translation",
              "notary-contract",
              "contract-courier"
            ]
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "qty": {
            "type": "integer"
          },
          "unit": {
            "type": "string",
            "enum": [
              "order",
              "page"
            ]
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteLine"
            },
            "description": "At-cost lines first, then the service-fee line."
          },
          "partnerCostUsd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of the at-cost lines (courier included). The service fee is computed on this."
          },
          "serviceFee": {
            "$ref": "#/components/schemas/ServiceFee"
          },
          "totalUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "includedGovFees": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Official fees already inside a partner fee (not added again)."
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "assumed-cost",
                "fx-assumed",
                "unpriced",
                "unsupported"
              ]
            }
          },
          "complete": {
            "type": "boolean"
          },
          "digitalCopy": {
            "$ref": "#/components/schemas/DigitalCopy"
          },
          "feePolicy": {
            "type": "object"
          }
        }
      },
      "Quote": {
        "type": "object",
        "required": [
          "currency",
          "services",
          "addOns",
          "partnerCostUsd",
          "serviceFeesUsd",
          "addOnsUsd",
          "totalUsd",
          "complete",
          "serviceLevel",
          "payment",
          "feePolicy",
          "digitalCopy",
          "paperOriginal",
          "flags",
          "priceStatus",
          "assumptions",
          "disclaimer"
        ],
        "properties": {
          "currency": {
            "const": "USD"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Bundles picked; each lists its services."
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceQuote"
            }
          },
          "addOns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteLine"
            },
            "description": "Concierge fee when serviceLevel is concierge (flat, not marked up)."
          },
          "partnerCostUsd": {
            "type": "number"
          },
          "serviceFeesUsd": {
            "type": "number"
          },
          "addOnsUsd": {
            "type": "number"
          },
          "totalUsd": {
            "type": "number",
            "description": "Sum of the priced services plus add-ons."
          },
          "complete": {
            "type": "boolean"
          },
          "serviceLevel": {
            "type": "string",
            "enum": [
              "self-service",
              "concierge"
            ]
          },
          "payment": {
            "type": "object",
            "required": [
              "dueNowUsd",
              "dueAfterApprovalUsd"
            ],
            "properties": {
              "dueNowUsd": {
                "const": 0
              },
              "dueAfterApprovalUsd": {
                "type": "number",
                "description": "The whole total, paid once after Camila Mota approves (quote locked 7 days)."
              },
              "rule": {
                "type": "string"
              }
            }
          },
          "feePolicy": {
            "type": "object"
          },
          "digitalCopy": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DigitalCopy"
              },
              {
                "type": "null"
              }
            ],
            "description": "null when the quote has no FBI service."
          },
          "paperOriginal": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PaperOriginal"
              },
              {
                "type": "null"
              }
            ],
            "description": "null when the quote has no FBI service."
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "translationPages": {
            "type": "integer"
          },
          "priceStatus": {
            "const": "test"
          },
          "fulfilment": {
            "type": "string"
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "disclaimer": {
            "type": "string"
          }
        }
      },
      "ValidityRequest": {
        "type": "object",
        "required": [
          "issueDate",
          "submitDate"
        ],
        "properties": {
          "issueDate": {
            "type": "string",
            "format": "date"
          },
          "submitDate": {
            "type": "string",
            "format": "date"
          },
          "channel": {
            "type": "string",
            "enum": [
              "pf",
              "migranteweb",
              "consulate"
            ],
            "default": "pf"
          },
          "consulate": {
            "type": "string",
            "enum": [
              "chicago",
              "san-francisco",
              "washington",
              "other"
            ]
          }
        }
      },
      "ValidityResult": {
        "type": "object",
        "required": [
          "windowDays",
          "ageDaysOnSubmit",
          "inDateUntil",
          "marginDays",
          "verdict"
        ],
        "properties": {
          "windowDays": {
            "type": "integer",
            "enum": [
              60,
              90
            ]
          },
          "windowStatus": {
            "type": "string"
          },
          "ageDaysOnSubmit": {
            "type": "integer"
          },
          "inDateUntil": {
            "type": "string",
            "format": "date"
          },
          "marginDays": {
            "type": "integer"
          },
          "verdict": {
            "type": "string",
            "enum": [
              "ok",
              "close",
              "expired",
              "before"
            ]
          },
          "note": {
            "type": "string"
          }
        }
      },
      "RouteRequest": {
        "type": "object",
        "properties": {
          "citizenship": {
            "type": "string",
            "enum": [
              "us-citizen",
              "green-card",
              "other"
            ]
          },
          "location": {
            "type": "string",
            "enum": [
              "brazil",
              "us",
              "elsewhere"
            ]
          },
          "destination": {
            "type": "string",
            "enum": [
              "pf",
              "migranteweb",
              "consulate"
            ]
          }
        }
      },
      "RouteResult": {
        "type": "object",
        "required": [
          "rows",
          "mailLegs"
        ],
        "properties": {
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "topic",
                "answer",
                "detail",
                "mode"
              ]
            }
          },
          "mailLegs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "TranslationRequest": {
        "type": "object",
        "description": "Counts per document type (0–20). Missing types use the tool defaults (1 FBI result, 1 apostille page) unless you send counts{}.",
        "properties": {
          "fbi": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "apostille": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "birth": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "marriage": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "contract": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "other": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "counts": {
            "type": "object"
          }
        }
      },
      "TranslationResult": {
        "type": "object",
        "required": [
          "pages",
          "rangeBrl",
          "quote",
          "missingApostillePages"
        ],
        "properties": {
          "pages": {
            "type": "integer"
          },
          "rangeBrl": {
            "type": "object"
          },
          "quote": {
            "$ref": "#/components/schemas/ServiceQuote"
          },
          "missingApostillePages": {
            "type": "boolean"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "OrderIntentRequest": {
        "type": "object",
        "required": [
          "customer"
        ],
        "description": "Give items, or plan (the recommended items are used), or both. Never include consent or payment fields: they are refused.",
        "properties": {
          "customer": {
            "type": "object",
            "required": [
              "name",
              "email"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 120
              },
              "email": {
                "type": "string",
                "format": "email",
                "description": "The customer's own email: the request link goes there."
              },
              "notes": {
                "type": "string",
                "maxLength": 2000
              }
            }
          },
          "items": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "pf-full-kit",
                "fbi-kit",
                "fbi-kit-express",
                "apostille-courier",
                "paper-original",
                "contract-kit",
                "contract-courier",
                "translation",
                "price-on-request"
              ]
            }
          },
          "translationPages": {
            "type": "integer",
            "minimum": 0,
            "maximum": 50
          },
          "serviceLevel": {
            "type": "string",
            "enum": [
              "self-service",
              "concierge"
            ],
            "default": "self-service",
            "description": "Ask the person which level they want. The customer still submits and pays themselves."
          },
          "otherRequest": {
            "type": "string",
            "maxLength": 2000,
            "description": "Price on request: another document type the person needs (e.g. a criminal record from another country), in their words. Never in the total; Camila quotes it by hand within 24 hours, at either level."
          },
          "nationality": {
            "type": "string",
            "maxLength": 60,
            "description": "Optional prefill."
          },
          "keyDates": {
            "type": "object",
            "description": "Optional prefill, YYYY-MM-DD.",
            "properties": {
              "visaAppointment": {
                "type": "string",
                "format": "date"
              },
              "arrival": {
                "type": "string",
                "format": "date"
              },
              "pfDate": {
                "type": "string",
                "format": "date"
              },
              "otherDeadline": {
                "type": "string",
                "format": "date"
              },
              "otherLabel": {
                "type": "string",
                "maxLength": 80
              }
            }
          },
          "paperOriginal": {
            "type": "boolean",
            "description": "Paper original by courier (needs an FBI item; recommended). Omit with a plan = the planner recommendation."
          },
          "contractPaperOriginal": {
            "type": "boolean",
            "description": "Work contract original by DHL (needs contract-kit). Optional, off by default."
          },
          "plan": {
            "$ref": "#/components/schemas/PlannerRequest"
          }
        },
        "not": {
          "anyOf": [
            {
              "required": [
                "consent"
              ]
            },
            {
              "required": [
                "payment"
              ]
            },
            {
              "required": [
                "paid"
              ]
            },
            {
              "required": [
                "confirmed"
              ]
            },
            {
              "required": [
                "stage"
              ]
            },
            {
              "required": [
                "approved"
              ]
            },
            {
              "required": [
                "submitted"
              ]
            }
          ]
        }
      },
      "OrderIntent": {
        "type": "object",
        "required": [
          "quoteId",
          "orderId",
          "stage",
          "statusUrl",
          "requestUrl",
          "humanActionRequired",
          "approval",
          "quote"
        ],
        "properties": {
          "quoteId": {
            "type": "string"
          },
          "orderId": {
            "type": "string"
          },
          "stage": {
            "const": "draft"
          },
          "statusUrl": {
            "type": "string",
            "format": "uri"
          },
          "statusApiUrl": {
            "type": "string",
            "format": "uri"
          },
          "requestUrl": {
            "type": "string",
            "format": "uri",
            "description": "For the HUMAN customer only. Agents must not open it to submit, upload, consent or pay."
          },
          "approval": {
            "type": "object",
            "description": "kind none (self-service: no approval step, by null) or concierge (Camila Mota checks the documents and approves before payment)."
          },
          "humanActionRequired": {
            "type": "object"
          },
          "agentMayNot": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "serviceLevel": {
            "type": "string",
            "enum": [
              "self-service",
              "concierge"
            ]
          },
          "fulfilment": {
            "type": "string"
          },
          "quote": {
            "$ref": "#/components/schemas/Quote"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrderStatus": {
        "type": "object",
        "required": [
          "orderId",
          "stage",
          "stageLabel",
          "nextAction",
          "needsCustomerAction",
          "approval",
          "payment",
          "history",
          "quote"
        ],
        "properties": {
          "orderId": {
            "type": "string"
          },
          "stage": {
            "type": "string",
            "enum": [
              "draft",
              "submitted",
              "changes_requested",
              "declined",
              "approved",
              "expired",
              "paid",
              "edo_submitted",
              "prints_pending",
              "card_mailed",
              "fingerprints_rejected_new_card_needed",
              "fbi_result",
              "apostille_in_progress",
              "scan_ready",
              "translation_in_progress",
              "notary_session_booked",
              "awaiting_predelivery_check",
              "courier_to_brazil",
              "delivered",
              "completed",
              "on_hold",
              "cancelled"
            ]
          },
          "stageLabel": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "nextAction": {
            "type": "string"
          },
          "needsCustomerAction": {
            "type": "boolean"
          },
          "approval": {
            "type": "object",
            "description": "Camila Mota's decision: approved | changes_requested | declined, with her message."
          },
          "quoteLocked": {
            "type": "boolean"
          },
          "quoteExpiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "End of the 7-day payment window once approved."
          },
          "checklist": {
            "type": "array",
            "description": "Post-payment checklist items and their status."
          },
          "plan": {
            "type": [
              "object",
              "null"
            ]
          },
          "quote": {
            "$ref": "#/components/schemas/Quote"
          },
          "payment": {
            "type": "object",
            "description": "Single payment of the locked quote, only after approval: not_due | awaiting_payment | checkout_created | paid | expired. Stripe test mode."
          },
          "serviceLevel": {
            "type": "object"
          },
          "fulfilment": {
            "type": "string"
          },
          "history": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "stage",
                "label",
                "at"
              ]
            }
          }
        }
      },
      "Pricing": {
        "type": "object",
        "required": [
          "currency",
          "status",
          "model",
          "rule",
          "serviceFee",
          "concierge",
          "digitalCopy",
          "paperOriginal",
          "services",
          "bundles"
        ],
        "properties": {
          "currency": {
            "const": "USD"
          },
          "status": {
            "const": "test"
          },
          "model": {
            "const": "cost-plus-service-fee"
          },
          "rule": {
            "type": "string"
          },
          "serviceFee": {
            "type": "object",
            "required": [
              "percent",
              "minimumUsd"
            ],
            "properties": {
              "percent": {
                "type": "number"
              },
              "minimumUsd": {
                "type": "number"
              },
              "per": {
                "const": "service"
              },
              "formula": {
                "type": "string"
              }
            }
          },
          "shipping": {
            "type": "string"
          },
          "digitalCopy": {
            "type": "object",
            "required": [
              "included",
              "extraFeeUsd",
              "isEApostille",
              "caveat"
            ],
            "properties": {
              "included": {
                "const": true
              },
              "extraFeeUsd": {
                "const": 0
              },
              "isEApostille": {
                "const": false
              },
              "notEApostille": {
                "const": true
              },
              "includedIn": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "fbi-apostille",
                    "fbi-apostille-express",
                    "apostille-only",
                    "paper-original",
                    "sworn-translation",
                    "notary-contract",
                    "contract-courier"
                  ]
                }
              },
              "caveat": {
                "type": "string"
              }
            }
          },
          "paperOriginal": {
            "type": "object",
            "required": [
              "optional",
              "default",
              "partnerCostUsd",
              "example"
            ],
            "properties": {
              "optional": {
                "const": true
              },
              "default": {
                "const": false
              },
              "partnerCostUsd": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "example": {
                "$ref": "#/components/schemas/ServiceQuote"
              },
              "recommendedFor": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "transitDays": {
                "type": "object"
              }
            }
          },
          "governmentFees": {
            "type": "object"
          },
          "concierge": {
            "type": "object",
            "required": [
              "priceUsd",
              "markedUp"
            ],
            "properties": {
              "priceUsd": {
                "type": "number"
              },
              "markedUp": {
                "const": false
              },
              "per": {
                "const": "order"
              }
            }
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "example"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "enum": [
                    "fbi-apostille",
                    "fbi-apostille-express",
                    "apostille-only",
                    "paper-original",
                    "sworn-translation",
                    "notary-contract",
                    "contract-courier"
                  ]
                },
                "example": {
                  "$ref": "#/components/schemas/ServiceQuote"
                }
              }
            }
          },
          "bundles": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Services": {
        "type": "object",
        "required": [
          "services"
        ],
        "properties": {
          "services": {
            "type": "array"
          }
        }
      }
    }
  }
}