{"openapi":"3.1.0","info":{"title":"FiscalAPI (BYOK) API","version":"0.1.0","description":"FiscalAPI (BYOK) lets an AI assistant read your own FiscalAPI data through the FiscalAPI API with a key you supply (FiscalAPI API key). Read-only: 8 tools (list_catalogs, search_catalog, list_sat_validation_types, list_stamp_movements, get_stamp_movement, list_events, list_products, get_auto_invoice_consumption). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-fiscalapi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-fiscalapi/docs"},"termsOfService":"https://connectorbay.com/byok-fiscalapi/terms"},"servers":[{"url":"https://byok-fiscalapi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-fiscalapi/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_catalogs":{"post":{"operationId":"list_catalogs","summary":"List the names of the SAT and internal catalogs (payment forms, tax regimes, CFDI uses, units, product codes and more) t","description":"List the names of the SAT and internal catalogs (payment forms, tax regimes, CFDI uses, units, product codes and more) that search_catalog accepts. Use for \"Which SAT catalogs can I search in FiscalAPI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_catalogsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_catalog":{"post":{"operationId":"search_catalog","summary":"Search one SAT catalog by a term and return the matching ids and descriptions, for example the payment form or tax regim","description":"Search one SAT catalog by a term and return the matching ids and descriptions, for example the payment form or tax regime code for a name. Use for \"What is the SAT payment form code for debit card\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"catalog_name":{"description":"Catalog name exactly as list_catalogs prints it (case sensitive), for example SatPaymentForms.","maxLength":200,"title":"Catalog Name","type":"string"},"search_term":{"description":"Text to look for in the catalog, for example tarjeta.","maxLength":200,"title":"Search Term","type":"string"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 100).","title":"Page Size"}},"required":["catalog_name","search_term"],"title":"search_catalogArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_sat_validation_types":{"post":{"operationId":"list_sat_validation_types","summary":"List the SAT validation checks FiscalAPI offers for a CFDI (XML structure, certificate validity, seals, SAT status, blac","description":"List the SAT validation checks FiscalAPI offers for a CFDI (XML structure, certificate validity, seals, SAT status, blacklist 69-B) with what each one verifies. Use for \"Which SAT validations does FiscalAPI support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_sat_validation_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_stamp_movements":{"post":{"operationId":"list_stamp_movements","summary":"List movements of invoice stamps (timbres) between accounts with amount, type, status, reference and date, showing your ","description":"List movements of invoice stamps (timbres) between accounts with amount, type, status, reference and date, showing your stamp balance history. Use for \"How many stamps have I bought and used recently on FiscalAPI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50).","title":"Page Size"}},"title":"list_stamp_movementsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_stamp_movement":{"post":{"operationId":"get_stamp_movement","summary":"Get one stamp movement by id. Use for \"Show FiscalAPI stamp movement 77678d6d-94b1-4635-aa91-15cdd7423aab\".","description":"Get one stamp movement by id. Use for \"Show FiscalAPI stamp movement 77678d6d-94b1-4635-aa91-15cdd7423aab\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Stamp movement id (UUID) from list_stamp_movements.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_stamp_movementArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_events":{"post":{"operationId":"list_events","summary":"List account events of the last 30 days (for example invoice.canceled) with type, related object and status change, newe","description":"List account events of the last 30 days (for example invoice.canceled) with type, related object and status change, newest first. Use for \"What events happened on my FiscalAPI account this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only events of this type, for example invoice.canceled.","title":"Type"},"related_object_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only events about this resource id, for example an invoice id.","title":"Related Object Id"},"from_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start instant in UTC, ISO 8601, for example 2026-10-01T00:00:00Z.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End instant in UTC, ISO 8601; the window is at most 30 days.","title":"To Time"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50).","title":"Page Size"}},"title":"list_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_products":{"post":{"operationId":"list_products","summary":"List the products and services saved on the account with price, SAT unit, SAT product code and tax rates. Use for \"Which","description":"List the products and services saved on the account with price, SAT unit, SAT product code and tax rates. Use for \"Which products do I have saved in FiscalAPI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50).","title":"Page Size"}},"title":"list_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_auto_invoice_consumption":{"post":{"operationId":"get_auto_invoice_consumption","summary":"Report Auto CFDI usage for a date range: tickets by status per issuer and ticket credits consumed, with totals. Use for ","description":"Report Auto CFDI usage for a date range: tickets by status per issuer and ticket credits consumed, with totals. Use for \"How many Auto CFDI tickets did we process in October 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"description":"First day of the period, YYYY-MM-DD (Mexico date).","maxLength":200,"title":"From Date","type":"string"},"to_date":{"description":"Last day of the period, YYYY-MM-DD; at most 366 days after from_date.","maxLength":200,"title":"To Date","type":"string"},"person_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this person id of your account.","title":"Person Id"}},"required":["from_date","to_date"],"title":"get_auto_invoice_consumptionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}