{
 "openapi": "3.1.0",
 "info": {
  "title": "Avanciq Connector",
  "version": "0.1.1",
  "description": "Checked business facts for AI agents: VAT/GST rates on a date, official tax/e-invoice code validity (Brazil, Mexico, Poland), EN 16931 e-invoice validation, exact business arithmetic. Every answer has its official source, date and a receipt id. Facts and checks only - not tax or legal advice. The same tools are available as an MCP server at /mcp.",
  "contact": {
   "name": "Avanciq",
   "email": "hello@avanciq.com",
   "url": "https://avanciq.com/agents/"
  },
  "termsOfService": "https://avanciq.com/terms/"
 },
 "servers": [
  {
   "url": "https://api.avanciq.com/connect",
   "description": "planned public address (not live yet)"
  }
 ],
 "security": [
  {
   "bearer": []
  }
 ],
 "paths": {
  "/v1/tools/coverage": {
   "post": {
    "operationId": "coverage",
    "summary": "What Avanciq covers (free)",
    "description": "Free (0 calls). Lists what the other tools can answer: VAT/GST jurisdictions, official code tables per country with dates, e-invoice rulesets, and the calculation kinds with their exact input fields. Call it once when unsure whether something is covered or which input fields verify_calculation needs.",
    "x-openai-isConsequential": false,
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Small JSON answer with source, date and receipt id (or status not_covered).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Input problem. 'next_step' says exactly what to change.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing/invalid key. Free key: https://avanciq.com/api/keys/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Plan or per-minute limit; next_step says when to retry or how to upgrade.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/tools/vat_rate": {
   "post": {
    "operationId": "vat_rate",
    "summary": "VAT / GST rate on a date",
    "description": "1 call. Official VAT/GST/sales-tax rate for a country (EU 27, UK, CH, NO, IN, JP, SG, NZ, AE, Canada provinces, 22 US states) on a given date, with valid-from/to, official source link, the date we read it and a receipt id. Use it instead of recalling rates from memory, especially around rate changes. Returns standard rate + reduced rates; it does not map products to reduced rates. Uncovered places answer status not_covered (never a guess).",
    "x-openai-isConsequential": false,
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "country": {
          "type": "string",
          "description": "ISO 3166 two-letter code, e.g. DE, FR, GB, IN, SG, CA, US. 'CA-QC' / 'US-TX' style also works."
         },
         "region": {
          "type": "string",
          "description": "Optional: Canadian province (ON, QC, BC, NS...) or US state (CA, TX, NY...). US answers are the state-level rate only, no local add-ons."
         },
         "date": {
          "type": "string",
          "description": "Optional: the date that matters (invoice/supply date) as YYYY-MM-DD. Default today."
         }
        },
        "required": [
         "country"
        ],
        "additionalProperties": false
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Small JSON answer with source, date and receipt id (or status not_covered).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Input problem. 'next_step' says exactly what to change.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing/invalid key. Free key: https://avanciq.com/api/keys/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Plan or per-minute limit; next_step says when to retry or how to upgrade.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/tools/code_check": {
   "post": {
    "operationId": "code_check",
    "summary": "Was this tax/e-invoice code valid on a date?",
    "description": "1 call per code. Checks whether an official code-list entry was in force on a date, from the authorities' own published files: Brazil NF-e (NCM, CFOP, cClassTrib, CST, CSOSN...), Mexico SAT CFDI 4.0 and 3.3 catalogs (c_UsoCFDI, c_ClaveProdServ, c_RegimenFiscal...), Poland KSeF FA(2)/FA(3) lists (TStawkaPodatku, TKodKraju, TGTU...). Answers status valid / expired / not_yet_valid / never_existed / not_covered with valid_from/valid_to, table version, source file link and receipt id. Use before accepting a code on an invoice or when checking an old one. Send either one check (country, table, code, date) or 'checks' (list, max 100).",
    "x-openai-isConsequential": false,
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "country": {
          "type": "string",
          "description": "br, mx or pl."
         },
         "table": {
          "type": "string",
          "description": "Official table name, e.g. ncm, cfop, cclasstrib, cst_icms (BR); c_UsoCFDI, c_ClaveProdServ, c_RegimenFiscal, c_ClaveUnidad (MX, add @3.3 for the CFDI 3.3 catalog); TStawkaPodatku, TKodKraju, TKodWaluty, TGTU (PL). Call coverage for the full list."
         },
         "code": {
          "type": "string",
          "description": "The code as written on the invoice; dots and spaces are ignored (8471.30.12 = 84713012)."
         },
         "date": {
          "type": "string",
          "description": "The date that matters (issue date) as YYYY-MM-DD."
         },
         "checks": {
          "type": "array",
          "maxItems": 100,
          "description": "Optional batch instead of the single fields: list of {country, table, code, date}.",
          "items": {
           "type": "object",
           "properties": {
            "country": {
             "type": "string"
            },
            "table": {
             "type": "string"
            },
            "code": {
             "type": "string"
            },
            "date": {
             "type": "string"
            }
           },
           "required": [
            "country",
            "table",
            "code",
            "date"
           ]
          }
         }
        },
        "additionalProperties": false
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Small JSON answer with source, date and receipt id (or status not_covered).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Input problem. 'next_step' says exactly what to change.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing/invalid key. Free key: https://avanciq.com/api/keys/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Plan or per-minute limit; next_step says when to retry or how to upgrade.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/tools/einvoice_check": {
   "post": {
    "operationId": "einvoice_check",
    "summary": "Validate an e-invoice (EN 16931)",
    "description": "2 calls. Runs the official CEN EN 16931 business rules (validation artefacts, unmodified) on a UBL 2.1 Invoice/CreditNote or UN/CEFACT CII (also the XML inside Factur-X/ZUGFeRD). Returns VALID/INVALID, each failed rule id with where it fails and how to fix it. Use it whenever asked if an e-invoice is valid or why it was rejected - reading XML by eye misses arithmetic and code-list rules. XML is checked in memory, not stored.",
    "x-openai-isConsequential": false,
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "xml": {
          "type": "string",
          "maxLength": 2000000,
          "description": "The complete invoice XML document as text."
         },
         "ruleset": {
          "type": "string",
          "enum": [
           "auto",
           "en16931-ubl",
           "en16931-cii"
          ],
          "default": "auto",
          "description": "Optional; auto detects UBL vs CII."
         }
        },
        "required": [
         "xml"
        ],
        "additionalProperties": false
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Small JSON answer with source, date and receipt id (or status not_covered).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Input problem. 'next_step' says exactly what to change.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing/invalid key. Free key: https://avanciq.com/api/keys/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Plan or per-minute limit; next_step says when to retry or how to upgrade.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/tools/einvoice_rule": {
   "post": {
    "operationId": "einvoice_rule",
    "summary": "Explain an EN 16931 rule (free)",
    "description": "Free (0 calls). Official text and fix hint for one EN 16931 business rule id, e.g. BR-CO-15, so you can explain a rejection.",
    "x-openai-isConsequential": false,
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "rule_id": {
          "type": "string",
          "description": "Rule id like BR-CO-15, BR-S-08, BR-01."
         }
        },
        "required": [
         "rule_id"
        ],
        "additionalProperties": false
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Small JSON answer with source, date and receipt id (or status not_covered).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Input problem. 'next_step' says exactly what to change.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing/invalid key. Free key: https://avanciq.com/api/keys/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Plan or per-minute limit; next_step says when to retry or how to upgrade.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/tools/verify_calculation": {
   "post": {
    "operationId": "verify_calculation",
    "summary": "Check business arithmetic to the cent",
    "description": "1 call. Recomputes a business calculation exactly (decimal, stated rounding) and says whether a claimed result is correct: invoice/claim totals with discounts and shipping, GST/VAT invoices, loan interest and amortisation, depreciation, FX with markup and fees, FIFO / moving-average inventory, weekly payroll overtime, trade quotes. Use it before giving the user any total you computed yourself, or to check a number another AI produced. Input fields per kind: call coverage (free).",
    "x-openai-isConsequential": false,
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "kind": {
          "type": "string",
          "enum": [
           "invoice_or_claim_total",
           "gst_vat_invoice",
           "loan_interest",
           "loan_amortisation",
           "depreciation",
           "fx_with_fees",
           "inventory_fifo_avg",
           "payroll_overtime",
           "trade_quote"
          ],
          "description": "Which calculation."
         },
         "inputs": {
          "type": "object",
          "description": "The numbers, e.g. loan_interest {principal, annual_rate_percent, days, day_count 365|360}; invoice_or_claim_total {lines[{quantity, unit_price, discount_percent?}], invoice_discount_percent?, shipping?, tax_rate_percent?, tax_on_shipping?, amount_paid?}. Full field list per kind: coverage."
         },
         "claimed_result": {
          "description": "Optional: the number (or object of named numbers) to check, e.g. 49.32 or {\"interest\": 49.32}."
         }
        },
        "required": [
         "kind",
         "inputs"
        ],
        "additionalProperties": false
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Small JSON answer with source, date and receipt id (or status not_covered).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Input problem. 'next_step' says exactly what to change.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing/invalid key. Free key: https://avanciq.com/api/keys/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Plan or per-minute limit; next_step says when to retry or how to upgrade.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "Avanciq API key (avq_...). Free key, 100 calls a month: https://avanciq.com/api/keys/"
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string"
     },
     "message": {
      "type": "string"
     },
     "next_step": {
      "type": "string"
     }
    },
    "required": [
     "error",
     "next_step"
    ]
   }
  }
 }
}