Visão geral da integração

A API de integração permite que sistemas externos (ERP, RH, plataformas de gestão) leiam e escrevam dados na Nearone usando chaves de API com escopos. A organização (tenant) é sempre derivada da chave — o corpo da requisição nunca escolhe o tenant.

Há duas superfícies:

Superfície	Prefixo	Autenticação	Para quê
Integração	/api/integrations/v1	Chave de API (Bearer no_live_…)	Operações do sistema externo (empresas).
Gestão de chaves	/api/v1/integrations/api-keys	JWT de usuário (org_admin)	Criar/rotacionar/revogar chaves (o painel usa).

Recursos

Empresas (companies:read / companies:write)

Método	Caminho	Escopo	Descrição
POST	/companies	companies:write	Criar empresa
PUT	/companies/by-cnpj/{cnpj}	companies:write	Upsert por CNPJ
PUT	/companies/{company_id}	companies:write	Atualizar por ID
GET	/companies/{company_id}	companies:read	Obter por ID
GET	/companies	companies:read	Listar

Participantes (participants:read / participants:write)

Participantes são os colaboradores — as pessoas que respondem às pesquisas psicossociais NR-1. O CPF é a chave natural; criar um participante dispara o onboarding NR-1.

Método	Caminho	Escopo	Descrição
POST	/participants	participants:write	Criar participante
PUT	/participants/by-cpf/{cpf}	participants:write	Upsert por CPF
PUT	/participants/{participant_id}	participants:write	Atualizar por ID
GET	/participants/{participant_id}	participants:read	Obter por ID
GET	/participants	participants:read	Listar

Departamentos (departments:read / departments:write)

Departamentos são unidades organizacionais da empresa. O slug (derivado do nome) é a chave natural para upsert; a organização vem da chave.

Método	Caminho	Escopo	Descrição
POST	/departments	departments:write	Criar departamento
PUT	/departments/by-slug/{slug}	departments:write	Upsert por slug
PUT	/departments/{department_id}	departments:write	Atualizar por ID
GET	/departments/{department_id}	departments:read	Obter por ID
GET	/departments	departments:read	Listar

Equipes (teams:read / teams:write)

Equipes (times) são subunidades, normalmente vinculadas a um departamento via department_id. O slug é a chave natural para upsert.

Método	Caminho	Escopo	Descrição
POST	/teams	teams:write	Criar equipe
PUT	/teams/by-slug/{slug}	teams:write	Upsert por slug
PUT	/teams/{team_id}	teams:write	Atualizar por ID
GET	/teams/{team_id}	teams:read	Obter por ID
GET	/teams	teams:read	Listar

:::info Próximos recursos A superfície de integração vai crescer. Cada novo recurso aparece automaticamente na Referência da API (gerada do contrato OpenAPI). :::

Convenções transversais

• Autenticação: ver Autenticação.
• Ambientes: live/test + URLs base — ver Ambientes.
• Idempotência: writes (POST/PUT) aceitam Idempotency-Key.
• Erros: corpo { "detail": ... }; escopo insuficiente traz { "detail": { "error": "insufficient_scope", "message": "...", "required_scope": "..." } }.
• Rate limit: por chave; estouro → 429.
• Auditoria: todo uso (writes + ciclo de vida das chaves) é registrado (timestamp, ação, IP, status), consultável em Uso e auditoria da chave.

Referência interativa

A Referência da API traz, para cada endpoint: descrição, parâmetros, schema de requisição/resposta, amostras de código (curl, Python, JavaScript e outras) e um console "Try it" para disparar a requisição direto do navegador.

:::caution Try it & CORS O console "Try it" envia requisições reais a partir do navegador. Use uma chave test contra staging (api-staging.nearone.com.br). O servidor precisa liberar CORS para a origem docs.nearone.com.br; sem isso, o navegador bloqueia a chamada — nesse caso use os exemplos curl/Python. :::