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

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:

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

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

1. validar disponibilidade com GET /health/
2. validar o token com GET /auth-context/
3. consumir listas e detalhes de properties, consultants e producers
4. executar mutações de tags ou notificações somente após validar leitura e contexto
5. 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