Dados de referência

Os dados de referência são catálogos somente leitura que alimentam os cadastros: o bank_id de uma conta financeira, a unit_of_measurement_id de um produto, o payment_method_id de um recebível, o city_id/state_id de um cliente ou fornecedor.

São seis recursos, cada um com sua permissão (banks, payment-methods, units-of-measurement, countries, states, cities), todos na ação read. Todas as listagens são paginadas e aceitam search (ver paginação e filtros).

Escopo por país do tenant

A maioria dos catálogos é escopada ao país do tenant — você só enxerga o que faz sentido para a sua região:

• Bancos pertencem a um único país: a lista traz os bancos ativos do país do tenant. (As buscas por swift/{code} e por {id} não são escopadas por país.)
• Formas de pagamento e unidades de medida usam uma lista de países (country_codes): uma lista vazia significa universal (disponível em todos os países); caso contrário, o país do tenant precisa estar nela.
• Países são um catálogo global — não filtrado pelo tenant.

Bancos (/banks)

Campos principais da resposta: id, code (código nacional, ex.: 341), name, official_name, swift_code, country_code, logo_url, aliases, is_active.

• GET /banks — lista os bancos do país do tenant.
• GET /banks/code/{code} — por código nacional (escopado ao país).
• GET /banks/swift/{code} — por SWIFT/BIC.
• GET /banks/{id} — por UUID.

Formas de pagamento (/payment-methods)

Campos: id, code (ex.: pix, credit_card), country_codes, titles (por idioma), descriptions, is_active. Uma forma universal tem country_codes: [].

• GET /payment-methods — disponíveis para o país do tenant.
• GET /payment-methods/code/{code} — por código.
• GET /payment-methods/{id} — por UUID.

Unidades de medida (/units-of-measurement)

Campos: id, code (ex.: UN, KG), symbol, country_codes, titles, descriptions, is_active. É a unit_of_measurement_id usada em produtos.

• GET /units-of-measurement — disponíveis para o país do tenant.
• GET /units-of-measurement/code/{code} — por código.
• GET /units-of-measurement/{id} — por UUID.

Geografia: países, estados e cidades

A geografia é hierárquica: país → estado → cidade. É assim que você obtém os city_id/state_id exigidos por fornecedores (e aceitos por clientes).

GET /countries                 → escolha country.id
GET /states?country_id={id}    → escolha state.id
GET /cities?state_id={id}      → escolha city.id

Países (/countries)

Catálogo global. Campos: id, iso2, iso3, numeric_code, name_en, name_pt, name_es, currency, region, entre outros.

• GET /countries — lista.
• GET /countries/iso2/{code} — por ISO2 (ex.: BR).
• GET /countries/iso3/{code} — por ISO3 (ex.: BRA).
• GET /countries/{id} — por ID.

Estados (/states)

Campos: id, country_id, state_code, country_code, name. A lista e a busca aceitam um seletor de país opcional: country_id, country_iso2 ou country_iso3 (o alias country_code está depreciado).

• GET /states?country_id={id} — estados do país.
• GET /states/search?q={texto} — busca por nome (q obrigatório).
• GET /states/code/{state_code} — por código.
• GET /states/{id} — por ID.

Cidades (/cities)

Campos: id, country_id, state_id, country_code, state_code, name. Cidades são navegadas por state_id, que é obrigatório.

• GET /cities?state_id={id} — cidades do estado (state_id obrigatório).
• GET /cities/search?state_id={id}&q={texto} — busca por nome no estado (state_id e q obrigatórios).
• GET /cities/{id} — por ID.

Referência dos endpoints