Atendimento: Acessórias Proxy

Proxy server-side da WebApiAlcance para a API do sistema externo Acessórias. O cliente envia apenas um path relativo (ex.: /companies/ListAll?...) e o servidor encaminha a requisição GET para a Acessórias usando o token que fica no servidor (ACESSORIAS_TOKEN), nunca no frontend. Substitui a Edge Function acessorias-proxy do Supabase, resolvendo o mesmo problema (esconder credenciais + centralizar o acesso) agora atrás do JWT e do escopo do Hub.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/acessorias-proxy

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/acessorias-proxy.

Escopos necessários

O escopo é derivado da rota: o prefixo /acessorias-proxy vira o recurso acessorias_proxy (hífen → underscore) e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

acessorias_proxy:write - encaminhar requisição (o único endpoint é um POST)
acessorias_proxy:read - reservado pela convenção de escopos; não há rotas GET neste domínio no momento

Por que POST para encaminhar um GET

O endpoint recebe o path no corpo da requisição (POST) e, internamente, faz um GET na API Acessórias. Por ser POST no Hub, a ação derivada é write - logo, o escopo efetivo exigido é acessorias_proxy:write.

Endpoints

`POST /acessorias-proxy/`

Encaminha uma requisição GET para a API Acessórias usando o token do servidor. Repassa o path informado no corpo para ACESSORIAS_BASE_URL (default https://api.acessorias.com), com os headers Authorization: Bearer <ACESSORIAS_TOKEN> e Accept: application/json.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (AcessoriasProxyRequest): path (obrigatório), que deve começar com /.

Request

{
  "path": "/companies/ListAll?page=1"
}

Response 200 OK

O envelope segue o padrão do Hub e o data é a resposta crua repassada da API Acessórias (pode ser um objeto ou um array JSON, conforme o endpoint chamado).

{
  "success": true,
  "message": "Requisição encaminhada com sucesso",
  "data": []
}

Erros possíveis: 422 Unprocessable Entity quando o path é inválido (ausente ou não começa com /); 502 Bad Gateway quando o ACESSORIAS_TOKEN não está configurado no servidor ou há falha ao contatar / erro retornado pela API Acessórias; 403 Forbidden quando a API Key não tem o escopo acessorias_proxy:write.

Escopo: acessorias_proxy:write

Schemas

`AcessoriasProxyRequest`

Campo	Tipo	Obrigatório	Observações
`path`	`str`	sim	Path relativo da API Acessórias (ex.: `/companies/ListAll?...`). Deve começar com `/`.

`AcessoriasProxyResponse`

Representa a resposta crua repassada da API Acessórias - uma lista ou um objeto JSON. No envelope do Hub, esse conteúdo vem dentro de data.

Campo	Tipo	Notas
`data`	`Any`	Corpo JSON retornado pela Acessórias (objeto ou array), repassado sem transformação.

Notas

A resposta do Hub segue o envelope { success, message, data }; o data é o corpo cru vindo da Acessórias, sem transformação.
O proxy só realiza GET contra a Acessórias - o POST do Hub existe apenas para transportar o path no corpo da requisição de forma segura.
Respostas sem corpo da Acessórias (status 204, 205, 304) ou corpo não-JSON são normalizadas para lista vazia ([]) - mesmo comportamento do || [] da Edge Function original.
O token da Acessórias (ACESSORIAS_TOKEN) e a URL base (ACESSORIAS_BASE_URL) são configurados por variável de ambiente no servidor e nunca trafegam para o cliente.
Timeout padrão de 30s para a chamada upstream à API Acessórias.