# EA-G-OP-SO-AC - Catálogo de APIs ESGFarmGuard
[![image.jpeg](https://docs.eaware.io/uploads/images/gallery/2025-07/scaled-1680-/4EExK1Ige2FmsRLD-image.jpeg)](https://docs.eaware.io/uploads/images/gallery/2025-07/4EExK1Ige2FmsRLD-image.jpeg)
##### 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` `` Forma preferencial para integração
`Authorization` `Bearer ` 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 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`