EA-G-OP-SO-AC - Catálogo de APIs ESGFarmGuard

Catálogo de APIs ESGFarmGuard

Código do Documento:

EA-G-OP-SO-AC

Versão:

1.0

Elaborado Por:

Rafael Quadros

Data de Revisão:

14/04/2026

Aprovado Por:

Status:

Ativo

1. Visão Geral

Esta documentação descreve as rotas públicas de integração do ESG Farm Guard para consumo por clientes externos. O foco é exclusivamente operacional: autenticação, headers, erros, endpoints disponíveis e exemplos mínimos de uso.

Escopo restrito ao data plane com prefixo /v1/.

2. Base URL e Escopo

Prefixo das rotas: /v1/
Ambientes suportados: produção em subdomínio dedicado e sandbox
Consumidor: cliente externo autenticado por token de integração

3. Autenticação

Todas as rotas protegidas exigem um token de integração ativo. O cliente pode autenticar a requisição usando um dos headers abaixo:

Header	Formato	Uso
`X-Integration-Key`	`<prefix.secret>`	Forma preferencial para integração
`Authorization`	`Bearer <prefix.secret>`	Alternativa compatível

Regras essenciais:

o token de integração é obrigatório nas rotas protegidas
a empresa pode manter até 3 tokens ativos em paralelo
cada requisição utiliza apenas um token

3.1 Produção

Em produção, o cliente consome o subdomínio dedicado da integração usando somente o token ativo.

3.2 Sandbox

Em sandbox ou acesso direto à API, o comportamento é o mesmo: o cliente deve enviar um dos tokens ativos liberados para a empresa.

4. Header de Resposta

Chamadas autenticadas retornam o header abaixo para rastreabilidade:

X-Integration-Request-Id - identificador único da requisição para correlação com logs

5. Contrato de Erros

Status	Descrição
`400`	Payload inválido ou parâmetros inconsistentes
`401`	Token ausente, inválido, expirado ou inativo
`403`	Cliente inativo, assinatura ausente/inativa ou escopo não permitido
`404`	Entidade inexistente ou fora do tenant autenticado
`429`	Rate limit ou quota excedida

Com o modo MVP ativo, erros 403 por escopo/assinatura e 429 por limites podem deixar de ocorrer nas rotas liberadas.

7. Endpoints

Observações importantes:

o data plane agora expõe também as rotas /groups/, /users/ e /tags/
a rota /tags/ retorna apenas tags do tipo standards
as rotas /groups/ e /users/ retornam apenas registros do tenant autenticado
o filtro de tenant continua aplicado pelo customer_id do client autenticado

GET /v1/health/

Autenticação: não exige token
Objetivo: validar disponibilidade básica do namespace público

Resposta

{
  "status": "ok",
  "domain": "integration-public"
}

GET /v1/auth-context/

Autenticação: obrigatória
Scope: integration.auth_context.read
Objetivo: validar rapidamente se a chave está funcional e qual contexto foi resolvido

Resposta

{
  "status": "ok",
  "client_id": "00000000-0000-0000-0000-000000000001",
  "customer_id": "customer-123",
  "api_key_id": "00000000-0000-0000-0000-000000000010",
  "api_key_prefix": "esg_abc123",
  "environment": "sandbox",
  "scope_code": "integration.auth_context.read",
  "endpoint_code": "auth-context-v1"
}

GET /v1/properties/

Autenticação: obrigatória
Scope: properties.read
Query params: search, page, page_size
Campos pesquisáveis em search: name, external_property_id, producer.name, city.name
Regra: retorna apenas propriedades do customer_id autenticado, ignorando registros removidos logicamente

Exemplo de requisição

GET /v1/properties/?search=Farm&page=1&page_size=50
X-Integration-Key: esg_abc123.secret-value

GET /v1/properties/{id}/

Autenticação: obrigatória
Scope: properties.read
Regra: retorna 404 se a propriedade não existir ou estiver fora do tenant autenticado

GET /v1/consultants/

Autenticação: obrigatória
Scope: consultants.read
Query params: search, page, page_size
Campos pesquisáveis em search: name, email, cpf, external_consultant_id
Regra: retorna apenas consultores do tenant autenticado

GET /v1/consultants/{id}/

Autenticação: obrigatória
Scope: consultants.read

GET /v1/producers/

Autenticação: obrigatória
Scope: producers.read
Query params: search, page, page_size
Campos pesquisáveis em search: name, email, cpf, cnpj, external_producer_id, city.name
Regra: retorna apenas produtores do tenant autenticado

GET /v1/producers/{id}/

Autenticação: obrigatória
Scope: producers.read

GET /v1/groups/

Autenticação: obrigatória
Scope: groups.read
Query params: search, page, page_size
Campos pesquisáveis em search: name, description, external_sector_id, region.name
Regra: retorna apenas grupos do customer_id autenticado

GET /v1/users/

Autenticação: obrigatória
Scope: users.read
Query params: search, page, page_size
Campos pesquisáveis em search: name, email
Regra: retorna apenas usuários vinculados ao tenant autenticado
Uso recomendado: utilize esta rota para localizar o id do usuário antes de enviar notificações administrativas segmentadas por user_ids

GET /v1/tags/

Autenticação: obrigatória
Scope: tags.read
Query params: search, page, page_size
Campos pesquisáveis em search: name, description
Regra: retorna apenas tags do tipo standards, do tenant autenticado, excluindo tags system e personalized

Exemplo de requisição

GET /v1/tags/?search=Compliance&page=1&page_size=50
X-Integration-Key: esg_abc123.secret-value

POST /v1/properties/tags/attach/

Autenticação: obrigatória
Scope: properties.tags.write
Objetivo: vincular tags a propriedades por ID interno ou ID externo

Payload mínimo

{
  "tag_ids": ["00000000-0000-0000-0000-000000000003"],
  "property_external_ids": ["PROP-001"],
  "observation": "integration update"
}

Regras

tag_ids é obrigatório
deve existir ao menos um entre property_ids ou property_external_ids
ids duplicados são normalizados
a operação é idempotente
respeita o tenant autenticado

POST /v1/properties/tags/detach/

Autenticação: obrigatória
Scope: properties.tags.write
Objetivo: remover vínculo

Payload mínimo

{
  "tag_ids": ["00000000-0000-0000-0000-000000000003"],
  "producer_external_ids": ["PROD-001"],
  "observation": "producer update",
  "value": "vip"
}

POST /v1/producers/tags/detach/

Autenticação: obrigatória
Scope: producers.tags.write
Objetivo: remover vínculo de tags em produtores

POST /v1/admin-notifications/

Autenticação: obrigatória
Scope: admin.notifications.write
Objetivo: criar notificações administrativas segmentadas

Quando usar

Use esta rota para enviar notificações a usuários ou segmentos específicos. Quando a segmentação exigir user_ids, consulte primeiro GET /v1/users/ para localizar o identificador correto do usuário. O parâmetro search dessa rota permite busca por name e email.

Payload mínimo

{
  "title": "Maintenance Window",
  "message": "Window tonight",
  "segment_spec": {
    "user_ids": ["user-1"],
    "group_ids": [],
    "subgroup_ids": [],
    "region_ids": []
  }
}

Regras

title é obrigatório
segment_spec é obrigatório
as chaves aceitas são user_ids, group_ids, subgroup_ids e region_ids
cada chave deve conter lista de strings não vazias

8. Fluxo Recomendado de Consumo

validar disponibilidade com GET /health/
validar o token com GET /auth-context/
consumir listas e detalhes de properties, consultants e producers
executar mutações de tags ou notificações somente após validar leitura e contexto
armazenar o X-Integration-Request-Id para auditoria e suporte

9. Observações Finais

as rotas de leitura não possuem filtro dedicado por external_id; a busca é feita pelo parâmetro search