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, nunca no frontend. Esconde as credenciais e centraliza o acesso, atrás do JWT e do escopo do Hub.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/acessorias-proxyA 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 é umPOST)acessorias_proxy:read- reservado pela convenção de escopos; não há rotasGETneste 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 a API Acessórias, autenticando com o token configurado no servidor.
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).
{
"status": "success",
"message": "Requisição encaminhada com sucesso",
"data": []
}Erros possíveis:
422 Unprocessable Entity-pathinválido (ausente ou não começa com/).429 Too Many Requests- a Acessórias atingiu o limite de requisições. A resposta inclui o headerRetry-After(segundos) quando a Acessórias o informa; aguarde esse tempo antes de repetir.502 Bad Gateway- falha ao contatar a Acessórias (por exemplo, timeout; mensagem genérica) ou erro retornado por ela.403 Forbidden- a API Key não tem o escopoacessorias_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
{ status, message, data }; odataé o corpo cru vindo da Acessórias, sem transformação. - O proxy só realiza
GETcontra a Acessórias - oPOSTdo Hub existe apenas para transportar opathno 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 ([]). - O token da Acessórias fica no servidor e nunca trafega para o cliente.
- Limite da Acessórias (
429): o429é repassado ao chamador comRetry-After, em vez de502. - Timeout padrão de 30s para a chamada upstream à API Acessórias.