Status: Approved · v2 · SPEC-API-AUXILIARY-001

depends_on: SPEC-DOMAIN-FIELD-001, SPEC-DOMAIN-SERVICE-001, SPEC-DOMAIN-REPORT-001

used_by: IS-MVP-13.1, IS-MVP-13.2, IS-MVP-13.3, IS-MVP-14.1, IS-MVP-14.2, IS-MVP-14.3

API de campos, serviços, prestadores, denúncias e suporte

Presença pública e gestão básica de entidades auxiliares, com operação manual de confiança e segurança.

Princípios e padrões

• Base path /api/v1; JSON UTF-8; chaves em camelCase.
• Toda resposta usa ApiResponse<T> com ok, data|error e meta contendo requestId e timestamp.
• IDs são strings opacas; datas são ISO-8601 UTC; dinheiro é inteiro em centavos com moeda BRL.
• Listas usam page e pageSize no MVP; default 20, máximo 100; metadados ficam em meta.pagination.
• Endpoints públicos usam DTOs públicos específicos; entidades internas, memberships, saldos e dados privados nunca vazam.
• Erros de domínio são estáveis e acionáveis; stack traces e detalhes internos não são retornados.
• Alterações sensíveis usam Idempotency-Key, confirmação recente quando necessário e audit log.
• Uploads usam fluxo presigned; o backend valida propósito, MIME, tamanho e ownership antes de confirmar o asset.

Endpoints

Método	Rota	Acesso	Request	Response	Regras principais
POST	/fields	Autenticado	CreateFieldRequest	FieldManagementResponse	Owner e página pública.
PATCH	/fields/:id	field.editProfile	UpdateFieldRequest	FieldManagementResponse	Address visibility.
GET	/fields/:id/management-summary	Membership	—	FieldManagementSummary	Jogos/galeria/status.
POST	/fields/:id/gallery	field.manageMedia	AddGalleryAssetRequest	GalleryAssetResponse	Asset confirmado.
POST	/services	Autenticado	CreateServiceRequest	ServiceManagementResponse	Owner e type.
PATCH	/services/:id	service.editProfile	UpdateServiceRequest	ServiceManagementResponse	Contato/showcase.
POST	/services/:id/providers/registered	service.manageProviders	AddRegisteredProviderRequest	ProviderLinkResponse	Pending acceptance.
POST	/services/:id/providers/unregistered	service.manageProviders	AddUnregisteredProviderRequest	ProviderLinkResponse	Private details.
POST	/provider-links/:id/respond	Provider alvo	RespondProviderLinkRequest	ProviderLinkResponse	Accept/reject.
POST	/services/:id/event-links	service.manageEvents	CreateEventLinkRequest	EventLinkResponse	Requested/approved.
POST	/reports	Autenticado	CreateReportRequest	ReportResponse	Target/reason/description/evidence.
GET	/reports/my	Autenticado	ReportQuery	ReportsResponse	Próprios.
POST	/support-requests	Autenticado	CreateSupportRequest	SupportRequestResponse	Claim/privacy/correction.
GET	/support-requests/my	Autenticado	SupportQuery	SupportRequestsResponse	Timeline.
POST	/support-requests/:id/cancel	Solicitante	—	SupportRequestResponse	Somente received quando permitido.

Autenticação e autorização

• Fields/services management por permission.
• Reports/support próprios; denunciado não acessa identidade do denunciante.
• Provider acceptance para perfil público.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
ADDRESS_VISIBILITY_INVALID	422	Endereço contraditório	Corrigir.
PROVIDER_LINK_DUPLICATE	409	Vínculo já existe	Abrir.
EVENT_LINK_NOT_ALLOWED	403	Sem autoridade contextual	Solicitar aprovação.
REPORT_DUPLICATE	409	Mesmo target/reason recente	Acompanhar protocolo.
CLAIM_NOT_ELIGIBLE	422	Entidade ativa/gerida	Explicar.
SUPPORT_REQUEST_LOCKED	409	Já em análise	Não cancelar.

Idempotência e concorrência

• Criação e vínculos/requests idempotentes.
• Reports duplicates por user/target/window quando apropriado.

Auditoria e efeitos colaterais

• Profile/status/provider/event changes auditados.
• Report/support timeline registra actor operação sem detalhes públicos.

Exemplos

report

{
  "target": {
    "type": "team",
    "id": "team_009"
  },
  "reason": "false_information",
  "description": "O nome e o escudo não correspondem ao time local.",
  "evidenceAssetIds": [
    "asset_101"
  ]
}

service

{
  "name": "Olhar da Várzea Fotografia",
  "type": "photo_video",
  "districtId": "district_001",
  "contact": {
    "whatsapp": "+5511999999999"
  }
}

Mocks

• Cenários unclaimed/abandoned/private address.
• Reports stateful e timeline manual simulada.

Testes obrigatórios

• Field/service create/manage.
• Provider accept/privacy.
• Event link.
• Report login/duplicate.
• Claim eligibility.

Critérios de aceite

• Sem booking/marketplace.
• Contato externo.
• Reports e suporte completos e privados.

Machine summary

spec: SPEC-API-AUXILIARY-001
api_group: API de campos, serviços, prestadores, denúncias e suporte
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents