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-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 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 - path invá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 header Retry-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 escopo acessorias_proxy:write.

Escopo: acessorias_proxy:write

Schemas

AcessoriasProxyRequest

CampoTipoObrigatórioObservações
pathstrsimPath 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.

CampoTipoNotas
dataAnyCorpo JSON retornado pela Acessórias (objeto ou array), repassado sem transformação.

Notas

  • A resposta do Hub segue o envelope { status, 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 ([]).
  • O token da Acessórias fica no servidor e nunca trafega para o cliente.
  • Limite da Acessórias (429): o 429 é repassado ao chamador com Retry-After, em vez de 502.
  • Timeout padrão de 30s para a chamada upstream à API Acessórias.