What's Changed
FiscalReference— the published classification tables, with an accessor per kindTaxpayer— one lookup, by exact tax id- Path segments are escaped — a value the caller types can no longer rewrite the request's URL
Why
An issuer filling a document needs CFOP, NCM, CEST and the rest, and until now the SDK had no way to ask. Both clients are read-only and take the same api key.
ref = FiscalReference(api_key="...")
ref.ncm.get("84716052")
ref.ncm.search("teclado", limit=5)
ref.kinds()
Taxpayer(api_key="...").get("00000000000191")
The eight named accessors are ergonomics. kind(name) reaches anything else, including a classification published after this release — ask kinds() rather than trusting the list, because the two answers diverge the moment the source data grows one.
metadata is passed through as the API sends it and differs per kind: utrib on an NCM, ncm_code on a CEST, tax_type on a CST, empty on an ISS service.
Three things worth knowing
These share the invoice read allowance — 600 calls a minute per key, the same bucket consult(), history(), received() and pdf() draw from. One page of search() beats N single lookups.
Ordering is fixed — kind, then code, ascending. Unlike history(), the search takes no sort or order argument: the route accepts them and discards them.
A 404 from Taxpayer does not mean the company does not exist. That registry reloads monthly from the RFB dump, so a recently registered CNPJ is simply not in it yet. It is not a validation rule.
Fixed
A tax id or code containing a / — which is how a CNPJ is normally written — used to land in the URL raw and address a different path, surfacing as a 404 that read like a registry miss. Segments are now escaped, and the ones that would leave the path are refused before the call.