Integração
API do Nomear
Conecte o sistema da sua organização às listas do Nomear. A API entrega em JSON as mesmas listas que a organização vê na tela: as dela, as Referências do Nomear e as que outras organizações abriram para ela.
Uma chave por sistema
A chave é da organização, não de uma pessoa: quem a criou pode sair que a integração continua.
Só leitura
A chave lê o que a organização lê no Nomear. Nada é alterado pelo caminho da API.
Chave do termo que não muda
Cada termo tem uma chave fixa (value). Guarde ela no seu sistema: o nome pode mudar, a chave não.
Começar
- Na página da organização no Nomear (menu Organização), seção Integrações (API), clique em Nova chave. Dê o nome do sistema que vai usar a chave e escolha a validade (1 ano por padrão). Só a administração do Nomear e os editores da organização geram chaves.
- Copie a chave (começa com
nmr_). Ela aparece uma vez só: guarde na configuração do sistema ou num cofre de senhas. - Teste. A resposta diz de qual organização é a chave e até quando ela vale.
curl -H "Authorization: Bearer nmr_SUA_CHAVE" https://nomear-staging.terrakrya.com/api/v1Autenticação
Todo pedido leva a chave no cabeçalho Authorization, no formato Bearer nmr_…. Endereço base de todas as rotas:
https://nomear-staging.terrakrya.com/api/v1- A chave é para o servidor do seu sistema. Não coloque em página aberta no navegador, em aplicativo instalado nem em código público: quem tiver a chave lê o que a organização lê.
- Gere uma chave para cada sistema. Se uma vazar, revogue só ela na página da organização: o acesso acaba na hora.
- Antes de a chave vencer, gere outra, troque no sistema e revogue a antiga.
- A interface do Nomear e a API são separadas: o login da tela não abre a API, e a chave não abre a tela.
Rotas
Todas são GET e respondem JSON (as de planilha, o arquivo). {id} é o id da lista, que aparece em /vocabularies e nunca muda.
GET/A chave
Organização dona da chave, nome e validade. Bom para testar a configuração.
GET/vocabulariesListas
Todas as listas que a organização lê: as dela, as Referências do Nomear e as que outras organizações abriram para ela.
| Parâmetro | Tipo | O que é |
|---|---|---|
| q | string | Parte do título, sem acento nem caixa. |
| model | string | Só listas deste modelo (model.slug). |
| archived | "true" | "false" | "all" | false (padrão) esconde as arquivadas; true só elas; all todas. |
GET/vocabularies/{id}Uma lista
Dados da lista e os atributos que os termos têm.
GET/vocabularies/{id}/termsTermos
Termos da lista, em páginas, na ordem da lista. Com at, como estavam numa versão ou data.
| Parâmetro | Tipo | O que é |
|---|---|---|
| q | string | Casa com o rótulo ou um sinônimo, sem acento nem caixa. |
| active | "true" | "false" | "all" | true (padrão) só os em uso; false só os inativos; all todos. |
| limit | integer | Termos por página (1 a 500, padrão 100). |
| cursor | string | O nextCursor da página anterior. |
| at | string | Ler como estava numa versão (v3) ou num instante (ISO 8601 com fuso, 2026-09-30T23:59:59-03:00). Ausente ou atual: estado atual. |
GET/vocabularies/{id}/terms/{value}Um termo
Um termo pela chave, em uso ou inativo. Termo inativo vem com replacedBy quando foi substituído.
GET/vocabularies/{id}/searchBusca
Termos em uso que casam com o texto: para autocompletar um campo no seu sistema.
| Parâmetro | Tipo | O que é |
|---|---|---|
| q * | string | Texto digitado: casa com o rótulo ou um sinônimo; quem começa com ele vem primeiro. |
| limit | integer | Quantos termos (1 a 20, padrão 20). |
GET/vocabularies/{id}/changesO que mudou
Termos criados, alterados, desativados ou com relações mudadas desde since, já no estado atual. Sem since, todos os termos.
| Parâmetro | Tipo | O que é |
|---|---|---|
| since | string | O nextSince da sincronização anterior. Ausente: todos os termos (primeira sincronização). |
| limit | integer | Termos por página (1 a 500, padrão 100). |
| cursor | string | O nextCursor da página anterior. |
GET/vocabularies/{id}/versionsVersões
Versões salvas da lista, da mais recente à mais antiga.
GET/vocabularies/{id}/export/csvPlanilha CSV
A lista em CSV (separador ;, decimal com vírgula), no mesmo formato da exportação da tela.
| Parâmetro | Tipo | O que é |
|---|---|---|
| at | string | Ler como estava numa versão (v3) ou num instante (ISO 8601 com fuso, 2026-09-30T23:59:59-03:00). Ausente ou atual: estado atual. |
| includeInactive | "0" | "1" | "true" | "false" | 1 inclui os termos inativos. |
GET/vocabularies/{id}/export/xlsxPlanilha Excel
A lista em XLSX, no mesmo formato da exportação da tela.
| Parâmetro | Tipo | O que é |
|---|---|---|
| at | string | Ler como estava numa versão (v3) ou num instante (ISO 8601 com fuso, 2026-09-30T23:59:59-03:00). Ausente ou atual: estado atual. |
| includeInactive | "0" | "1" | "true" | "false" | 1 inclui os termos inativos. |
Exemplos:
curl -H "Authorization: Bearer nmr_SUA_CHAVE" "https://nomear-staging.terrakrya.com/api/v1/vocabularies"curl -H "Authorization: Bearer nmr_SUA_CHAVE" "https://nomear-staging.terrakrya.com/api/v1/vocabularies/ID_DA_LISTA/terms?limit=100"curl -H "Authorization: Bearer nmr_SUA_CHAVE" "https://nomear-staging.terrakrya.com/api/v1/vocabularies/ID_DA_LISTA/search?q=altamira"Páginas. As rotas de termos devolvem até 500 termos por vez (limit) e um nextCursor. Para a próxima página, repita o pedido com cursor=<nextCursor>; quando ele vier null, acabou.
Documento OpenAPI. A descrição completa, para importar no Postman ou no Insomnia ou gerar um cliente, está em https://nomear-staging.terrakrya.com/api/v1/openapi (aberto, sem chave).
O termo
Cada termo vem assim. Os atributos dependem do modelo da lista (veja attributes em /vocabularies/{id}).
{
"value": "altamira",
"label": "Altamira",
"code": "1500602",
"synonyms": [
"Altamira (PA)"
],
"active": true,
"replacedBy": null,
"broader": {
"value": "pa",
"label": "Pará",
"active": true
},
"related": [
{
"vocabularyId": "7d1f2c4e-8a90-4b6f-9c3d-2e5a7b8c9d01",
"vocabularySlug": "terras-indigenas",
"vocabularyTitle": "Terras indígenas",
"value": "ti_arara",
"label": "Arara",
"active": true
}
],
"coordinates": {
"latitude": -3.2033,
"longitude": -52.2064
},
"attributes": {},
"sortOrder": null,
"createdAt": "2026-09-15T12:00:00.000Z",
"updatedAt": "2026-10-29T10:00:00.000Z"
}| Campo | Tipo | O que é |
|---|---|---|
| value | string | Chave do termo: única na lista e nunca muda. É ela que o seu sistema guarda. |
| label | string | Nome preferido do termo. |
| code | string | null | Código opcional (por exemplo, o código do IBGE). |
| synonyms | array<string> | Outros nomes: grafias, siglas, nomes locais. A busca também casa por eles. |
| active | boolean | Em uso. Termo inativo continua respondendo, mas não deve ser oferecido em cadastros novos. |
| replacedBy | object | null | Termo da mesma lista que substitui este, quando inativo. |
| broader | object | null | "Pertence a": termo da lista indicada em broaderVocabulary. |
| related | array<object> | "Relacionado a": termos ligados a este, de qualquer lista. |
| coordinates | object | null | Ponto no mapa em graus decimais, só em listas com mapa. |
| attributes | object | Atributos do modelo da lista (ver attributes da lista). Atributo de referência vem como { value, label, active }. |
| sortOrder | integer | null | Posição fixa na lista, quando definida. |
| createdAt | string (ISO 8601) | Criação do termo. |
| updatedAt | string (ISO 8601) | Última alteração do termo ou das relações dele. |
Campos da lista (/vocabularies/{id})
| Campo | Tipo | O que é |
|---|---|---|
| id | string (uuid) | Identificador da lista, usado nas rotas. Nunca muda. |
| slug | string | Identificador legível (único dentro da organização dona). |
| title | string | Título da lista. |
| description | string | null | Descrição da lista. |
| kind | "reference" | "organization" | reference: Referência do Nomear, com dados oficiais. organization: lista de uma organização. |
| organization | object | null | Organização dona; null em Referência do Nomear. |
| ownedByYou | boolean | A lista é da organização da chave. |
| model | object | Modelo da lista: define os atributos dos termos. |
| source | object | null | Fonte dos dados (nome, endereço, versão, licença). |
| basedOn | object | null | Referência do Nomear de onde a lista escolhe termos. |
| hasCoordinates | boolean | Os termos têm ponto no mapa. |
| broaderVocabulary | object | null | Lista a que os termos "pertencem" (broader de cada termo). isSelf: hierarquia dentro da própria lista. |
| archived | boolean | Lista arquivada: não recebe mais alterações. |
| termCount | integer | Termos da lista, ativos e inativos. |
| activeTermCount | integer | Termos em uso. |
| latestVersion | object | null | Última versão salva, se houver. |
| lastTermChangeAt | string (ISO 8601) | null | Última alteração de algum termo da lista. |
| createdAt | string (ISO 8601) | Criação da lista. |
| updatedAt | string (ISO 8601) | Última alteração dos dados da lista (título, estrutura). |
| attributes | array<object> | Atributos dos termos desta lista. |
Manter o seu sistema em dia
- Na primeira vez, peça
/vocabularies/{id}/changessemsince: vêm todos os termos da lista, em páginas. Grave cada um pela chave (value): insere se não existe, atualiza se existe. - Guarde o
nextSinceda resposta (é o mesmo em todas as páginas). - De tempos em tempos (por exemplo, a cada hora), peça de novo com
since=<nextSince>: vêm só os termos criados, alterados ou desativados desde então, e os que ganharam ou perderam uma relação. Grave e guarde o novonextSince.
- Nenhum termo é apagado no Nomear: termo que sai de uso vem com
active: falsee, se foi substituído, comreplacedBy. Use isso para corrigir os registros antigos do seu sistema. - O mesmo termo pode vir em duas sincronizações seguidas. Gravar pela chave resolve.
- Os rótulos dos termos apontados (
broader,related,replacedBy, atributos de referência) são os do momento da leitura. Quando um termo apontado muda, ele vem na sincronização da lista dele, não na dos termos que apontam para ele: guarde as chaves e tire o rótulo da lista de origem. - Se o cursor de uma página se perder ou vier corrompido, a resposta é 400: recomece com o último
nextSinceque você guardou.
import requests
BASE = "https://nomear-staging.terrakrya.com/api/v1"
HEADERS = {"Authorization": "Bearer nmr_SUA_CHAVE"}
def sincronizar(lista, since=None):
"""Traz o que mudou na lista desde `since` (None = tudo) e devolve o próximo since."""
params = {"limit": 500}
if since:
params["since"] = since
while True:
url = f"{BASE}/vocabularies/{lista}/changes"
r = requests.get(url, headers=HEADERS, params=params, timeout=30)
r.raise_for_status()
pagina = r.json()
for termo in pagina["items"]:
salvar(termo) # inserir ou atualizar pela chave termo["value"]
if not pagina["nextCursor"]:
return pagina["nextSince"] # guarde para a próxima vez
params = {"limit": 500, "cursor": pagina["nextCursor"]}Campos da resposta de /changes
| Campo | Tipo | O que é |
|---|---|---|
| items | array<object> | |
| nextCursor | string | null | Envie em cursor para a próxima página; null quando acabou. |
| total | integer | Quantos termos atendem ao pedido, somando todas as páginas. |
| since | string (ISO 8601) | null | O since pedido, como foi enviado; null = primeira sincronização (todos os termos). |
| nextSince | string (ISO 8601) | Guarde e envie como since na próxima sincronização. Vem igual em todas as páginas. |
Versões e datas
A organização pode salvar versões de uma lista. O seu sistema pode ficar preso a uma versão enquanto a lista continua mudando, ou ler a lista como estava numa data. Nas rotas de termos e de planilha, use at=v3 (versão) ou at=2026-09-30T23:59:59-03:00 (data e hora com fuso). As versões de cada lista estão em /vocabularies/{id}/versions.
curl -H "Authorization: Bearer nmr_SUA_CHAVE" "https://nomear-staging.terrakrya.com/api/v1/vocabularies/ID_DA_LISTA/terms?at=v3"Limites e erros
Cada chave pode fazer até 120 pedidos por minuto. Os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining mostram quanto resta. Erros vêm em JSON, com o código HTTP e uma mensagem em português: { "statusCode": 404, "message": "Vocabulário não encontrado." }.
| Código | Quando |
|---|---|
| 400 | Parâmetro inválido. A mensagem diz qual. |
| 401 | Chave ausente, inválida, vencida ou revogada. |
| 403 | A organização da chave está arquivada. |
| 404 | Lista ou termo não existe, ou a organização não lê essa lista. |
| 429 | Mais de 120 pedidos por minuto com a mesma chave. Espere os segundos do cabeçalho Retry-After. |