Ir para o conteúdo principal

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

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:

Jean Winter

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 /api/integration/v1/.

2. Base URL e Escopo

  • Prefixo das rotas: /api/integration/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 /api/integration/v1/health/

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

Resposta


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


GET /api/integration/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 /api/integration/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 /api/integration/v1/properties/?search=Farm&page=1&page_size=50
X-Integration-Key: esg_abc123.secret-value


GET /api/integration/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 /api/integration/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 /api/integration/v1/consultants/{id}/

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

GET /api/integration/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 /api/integration/v1/producers/{id}/

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

GET /api/integration/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 /api/integration/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 /api/integration/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 /api/integration/v1/tags/?search=Compliance&page=1&page_size=50
X-Integration-Key: esg_abc123.secret-value


POST /api/integration/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 /api/integration/v1/properties/tags/detach/

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

    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, producers, groups, users e tags
    4. para notificações por usuário, consultar primeiro GET /users/ para obter o id correto
    5. executar mutações de tags ou notificações somente após validar leitura e contexto
    6. armazenar o X-Integration-Request-Id para auditoria e suporte

    9. Observações Finais

    r tags a produtores por ID interno ou externo

Payload mínimo


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


POST /api/integration/v1/producers/tags/detach/

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

POST /api/integration/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 /api/integration/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
Voltar ao topo