{"openapi":"3.1.0","info":{"title":"Focus NFe (BYOK) API","version":"0.1.0","description":"Focus NFe (BYOK) lets an AI assistant read your own Focus NFe data through the Focus NFe API with a key you supply (Focus NFe production token (company or main account token)). Read-only: 11 tools (list_companies, get_nfe, get_nfse, list_received_nfes, list_webhooks, lookup_cnpj, search_ncm_codes, search_cfop_codes, search_cnae_codes, search_postal_codes, list_municipalities). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-focusnfe.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-focusnfe/docs"},"termsOfService":"https://connectorbay.com/byok-focusnfe/terms"},"servers":[{"url":"https://byok-focusnfe.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-focusnfe/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_companies":{"post":{"operationId":"list_companies","summary":"List the companies registered on your Focus NFe account: id, legal and trade name, CNPJ, tax regime, location, enabled d","description":"List the companies registered on your Focus NFe account: id, legal and trade name, CNPJ, tax regime, location, enabled document types and certificate validity (credentials, tokens, SMTP and contact data are left out). Use for \"Which companies and document types are set up on my Focus NFe account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cnpj":{"anyOf":[{"maxLength":14,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by company CNPJ (digits only).","title":"Cnpj"},"cpf":{"anyOf":[{"maxLength":11,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by company CPF (digits only).","title":"Cpf"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many records to skip for paging (each page returns up to 50).","title":"Offset"}},"title":"list_companiesArguments","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_nfe":{"post":{"operationId":"get_nfe","summary":"Get the processing status of an NF-e you issued, by your reference: status, SEFAZ status code and message, access key, n","description":"Get the processing status of an NF-e you issued, by your reference: status, SEFAZ status code and message, access key, number, series and paths to the XML and DANFe. Use for \"Was NF-e reference pedido-1042 authorized by SEFAZ\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"referencia":{"description":"The reference you chose when issuing the NF-e.","maxLength":200,"title":"Referencia","type":"string"}},"required":["referencia"],"title":"get_nfeArguments","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_nfse":{"post":{"operationId":"get_nfse","summary":"Get the status of a service invoice (NFS-e) you issued, by your reference: status, number, verification code, issue date","description":"Get the status of a service invoice (NFS-e) you issued, by your reference: status, number, verification code, issue date and links to the note and XML (customer data is left out). Use for \"Was service invoice reference servico-77 issued\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"referencia":{"description":"The reference you chose when issuing the NFS-e.","maxLength":200,"title":"Referencia","type":"string"}},"required":["referencia"],"title":"get_nfseArguments","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_received_nfes":{"post":{"operationId":"list_received_nfes","summary":"List the NF-e invoices issued against a company (received invoices) with emitter, total value, issue date, status and th","description":"List the NF-e invoices issued against a company (received invoices) with emitter, total value, issue date, status and the recipient manifestation. Use for \"Which invoices were issued against my company and are still pending manifestation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cnpj":{"description":"CNPJ of the receiving company (digits only).","maxLength":14,"title":"Cnpj","type":"string"},"pendente":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 lists only invoices pending a final manifestation.","title":"Pendente"},"pendente_ciencia":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 lists only invoices without the acknowledgement (ciencia) operation.","title":"Pendente Ciencia"},"versao":{"anyOf":[{"maximum":1000000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Return only documents whose version is greater than this number.","title":"Versao"}},"required":["cnpj"],"title":"list_received_nfesArguments","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_webhooks":{"post":{"operationId":"list_webhooks","summary":"List the webhook triggers registered for your token: id, event type and company (the delivery URL and its authorization ","description":"List the webhook triggers registered for your token: id, event type and company (the delivery URL and its authorization secret are left out). Use for \"Which Focus NFe webhook triggers do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_webhooksArguments","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/lookup_cnpj":{"post":{"operationId":"lookup_cnpj","summary":"Look up a Brazilian company registration by CNPJ: legal name, registration status, main CNAE, Simples Nacional and MEI f","description":"Look up a Brazilian company registration by CNPJ: legal name, registration status, main CNAE, Simples Nacional and MEI flags and address. Use for \"Is CNPJ 12345678000123 active, and is it a Simples Nacional taxpayer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cnpj":{"description":"CNPJ with 14 digits, digits only.","maxLength":200,"title":"Cnpj","type":"string"}},"required":["cnpj"],"title":"lookup_cnpjArguments","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_ncm_codes":{"post":{"operationId":"search_ncm_codes","summary":"Search NCM product classification codes by code prefix, description or chapter. Use for \"What is the NCM code for coffee","description":"Search NCM product classification codes by code prefix, description or chapter. Use for \"What is the NCM code for coffee beans\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"codigo":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the NCM code.","title":"Codigo"},"descricao":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Part of the description to search (Portuguese).","title":"Descricao"},"capitulo":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Exact chapter (2 digits).","title":"Capitulo"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many records to skip for paging (each page returns up to 50).","title":"Offset"}},"title":"search_ncm_codesArguments","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_cfop_codes":{"post":{"operationId":"search_cfop_codes","summary":"Search CFOP fiscal operation codes by code prefix or description. Use for \"Which CFOP applies to a sale of goods within ","description":"Search CFOP fiscal operation codes by code prefix or description. Use for \"Which CFOP applies to a sale of goods within the state\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"codigo":{"anyOf":[{"maxLength":4,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the CFOP code.","title":"Codigo"},"descricao":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Part of the description to search (Portuguese).","title":"Descricao"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many records to skip for paging (each page returns up to 50).","title":"Offset"}},"title":"search_cfop_codesArguments","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_cnae_codes":{"post":{"operationId":"search_cnae_codes","summary":"Search CNAE economic activity codes by code or description, with their section, division, group and class. Use for \"What","description":"Search CNAE economic activity codes by code or description, with their section, division, group and class. Use for \"What is the CNAE code for software development\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"codigo":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":null,"description":"Code or part of the CNAE code.","title":"Codigo"},"descricao":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Part of the description to search (Portuguese).","title":"Descricao"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many records to skip for paging (each page returns up to 50).","title":"Offset"}},"title":"search_cnae_codesArguments","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_postal_codes":{"post":{"operationId":"search_postal_codes","summary":"Search Brazilian CEP postal codes by IBGE city code, state, street name or locality. Use for \"What CEPs does Avenida Pau","description":"Search Brazilian CEP postal codes by IBGE city code, state, street name or locality. Use for \"What CEPs does Avenida Paulista have in Sao Paulo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uf":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"State abbreviation, for example SP.","title":"Uf"},"localidade":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Locality name (full or part).","title":"Localidade"},"logradouro":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Street name (at least 3 characters).","title":"Logradouro"},"codigo_ibge":{"anyOf":[{"maxLength":7,"type":"string"},{"type":"null"}],"default":null,"description":"7-digit IBGE city code.","title":"Codigo Ibge"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many records to skip for paging (each page returns up to 50).","title":"Offset"}},"title":"search_postal_codesArguments","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_municipalities":{"post":{"operationId":"list_municipalities","summary":"List Brazilian municipalities with their IBGE code, state and NFS-e support: provider, requirements and status. Use for ","description":"List Brazilian municipalities with their IBGE code, state and NFS-e support: provider, requirements and status. Use for \"Does Curitiba support NFS-e emission through Focus NFe\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sigla_uf":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"State abbreviation, for example PR.","title":"Sigla Uf"},"nome":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Part of the municipality name.","title":"Nome"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many municipalities to return (default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many records to skip for paging (each page returns up to 50).","title":"Offset"}},"title":"list_municipalitiesArguments","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}}}}