API: erro de CORS no navegador e como testar as chamadas
Quem começa a integrar pela API costuma esbarrar em duas coisas logo no primeiro dia: uma mensagem de CORS que parece defeito do sistema, e a dúvida de como testar as chamadas. As duas têm a mesma raiz.
A MENSAGEM DE CORS
Ao chamar a API direto de uma página aberta no navegador, aparece algo como CORS policy, no Access-Control-Allow-Origin, ou request blocked by CORS policy. As redações variam de navegador para navegador.
Isso não é falha da API nem da sua conta. CORS é uma trava de segurança do PRÓPRIO NAVEGADOR: antes de deixar uma página buscar dados em outro endereço, ele pergunta ao destino se aquele tipo de chamada é liberado. A API responde que não libera as chamadas autenticadas vindas de dentro de uma página, e o navegador cancela.
E isso é proposital. Para chamar a API você precisa mandar as suas chaves de acesso junto. Se a chamada acontecesse dentro da página, as chaves ficariam visíveis para qualquer pessoa que abrisse o site — e quem tem as chaves age em nome da sua empresa, sem tela de login.
POR QUE NÃO ADIANTA INSISTIR
Quando o navegador pergunta quais cabeçalhos o destino aceita, a resposta da API cita Content-Type, X-Requested-With e Authorization. Os dois cabeçalhos de autenticação da API, access-token e secret-access-token, não estão nessa resposta. Ou seja: mesmo com as chaves certas, o navegador não deixa a chamada sair. E a checagem prévia que o navegador faz antes da chamada de verdade também não conclui com sucesso.
Por isso não existe liberação de CORS por domínio, nem chave, plano ou permissão que mude esse comportamento. Não é caso de chamado técnico.
A SOLUÇÃO: CHAMAR PELO SERVIDOR
A integração deve ser feita do lado do SERVIDOR do seu sistema, não do navegador do visitante. Servidor não passa pela trava do CORS, e as chaves ficam guardadas onde ninguém vê.
Na prática, se o seu site precisa mostrar algum dado do ERP, o caminho é: a página fala com o seu próprio servidor, e o seu servidor fala com a API.
Essa mudança é no código da integração e cabe ao desenvolvedor responsável por ela.
PARA TESTAR AS CHAMADAS
Antes de escrever código, o normal é testar cada chamada num programa de requisições — o Postman é o mais usado. Ele não é um navegador, então não sofre a trava de CORS, e mostra a resposta da API exatamente como ela vem.
O que não pode faltar em cada requisição são os dois códigos gerados no sistema, enviados como cabeçalhos: o Access Token e o Secret Access Token. Sem os dois, a resposta é de token não informado ou incorreto, e não adianta olhar o resto.
Para criar e alterar registros, os dados vão no CORPO da requisição, em JSON.
O QUE COSTUMA DAR ERRADO
Funciona no Postman e não funciona no site. Causa: a chamada do site sai do navegador. É o caso desta fonte, e a saída é chamar pelo servidor.
Pedido para liberar o domínio no CORS. Causa: expectativa de que exista essa configuração. Não existe.
A mensagem fala em token, não em CORS. Causa: aí o assunto é outro — cabeçalho faltando ou par de chaves errado, e se responde pela fonte do token.
Responde certo, mas vem vazio. Causa: filtro ou parâmetro, não CORS. Isso é da fonte de campos, filtros e retorno.
ONDE ESTÁ O RESTO
Os dois códigos, sigilo e troca do par: a fonte do token. Frase de erro literal e código HTTP: a fonte de erro por erro. Nome de campo, filtro, paginação e formato da resposta: a fonte de campos, filtros e retorno. O que dá e o que não dá para fazer pela API: a fonte de visão geral da pasta.