API: os dois codigos do token, sigilo, troca do par e o que a API nao faz sozinha
DO QUE ESTA FONTE TRATA
Esta fonte trata dos dois codigos de acesso da API: o que sao, como guardar, o que acontece quando voce revoga uma chave, e o que a API nao faz sozinha. Ela nao repete o resto da pasta. O passo a passo da tela de credenciais (criar chave com nome e validade, revogar, baixar) e a fonte de credenciais da API.
Se a pergunta for de filtro, paginacao ou nome de campo, e a fonte de campos, filtros e retorno. Se for mensagem de erro ou bloqueio por excesso de chamadas, e a fonte de erro por erro. Se for "a API nao traz tudo" ou 403, e a fonte sobre quem o token representa. Se for CORS ou como testar, e a fonte de CORS e teste. O que da e o que nao da para fazer esta na visao geral da pasta.
SAO DOIS CODIGOS, E OS DOIS SAO NECESSARIOS
A API usa duas credenciais: o Access Token e o Secret Access Token. Elas nascem juntas quando voce cria uma chave de API na tela Credenciais do aplicativo API (Meus aplicativos › Ver todos os aplicativos › API), e vao em cabecalhos a cada chamada. A conta pode ter varias chaves, cada uma com o seu par, o seu nome e a sua validade.
Os dois sao obrigatorios. Quem copia so o primeiro nao autentica. Faltando um deles, a resposta diz exatamente qual nao foi informado; errados, ela diz que estao incorretos.
O Secret Access Token aparece uma unica vez, na hora em que a chave e criada. Depois disso a tela nao o mostra mais. Quem perdeu cria outra chave.
OS CODIGOS SAO SECRETOS
Quem tem os dois codigos age em nome da empresa, sem passar por tela de login. E por isso que eles nao entram em codigo de pagina, planilha compartilhada nem conversa de atendimento.
Nunca peca esses valores no atendimento e nunca repita um que o cliente tenha colado. Se ele colar, oriente a gerar outros.
REVOGAR DERRUBA QUEM USAVA A CHAVE; CRIAR OUTRA NAO
A API confere os dois codigos juntos, comparando com o par de cada chave gravada. Criar uma chave nova nao mexe nas outras: cada integracao continua com a sua. O que tira um par de uso e revogar a chave, ou a data de validade dela passar. Nesse momento toda integracao que ainda use aquele par para de autenticar na hora.
Revogar e o certo quando os codigos vazaram, ou quando um parceiro deixou de trabalhar com voce. Mas avise antes quem depende daquela chave. Quem esquece disso revoga e derruba a propria integracao no mesmo minuto, e a queixa chega como "revoguei a chave e parou tudo".
Antes dessa mudanca a conta tinha um token so, e gerar outro invalidava o anterior. O token gerado naquela epoca continua valendo e aparece na lista de chaves sem nome.
A API RESPONDE QUANDO E PERGUNTADA
O funcionamento e de pergunta e resposta: o sistema do cliente chama um endereco e recebe o retorno.
Nao prometa que o ERP avisa o sistema do cliente sozinho quando algum dado muda. Se ele perguntar por esse aviso automatico, ofereca verificar em vez de afirmar que existe ou que nao existe.
Nao confunda com o aviso das integracoes bancarias: ali quem avisa o sistema e o banco. E o caminho contrario.
QUEM CONSTROI A INTEGRACAO
A equipe fornece a API e a documentacao. A integracao em si e escrita por um desenvolvedor do lado do cliente. Nao escreva codigo nem monte a requisicao pelo cliente no atendimento.
Programas de teste de requisicao e colecoes de exemplo sao apoio do time. Nao prometa envia-los nem os trate como parte do produto.
DUAS CREDENCIAIS OPOSTAS, E ISSO CONFUNDE
Os codigos da API sao do cliente, para que outro sistema consuma os dados da empresa dele.
As credenciais que ele informa dentro de uma integracao pronta (marketplace, meio de pagamento, loja virtual) sao do parceiro, para o ERP consumir os dados do parceiro. Sao coisas opostas.
Quem troca uma pela outra procura o token no lugar errado, e costuma abrir chamado dizendo que a chave nao funciona. Para integracao pronta nao e preciso mexer no aplicativo API: ela tem tela propria e usa as credenciais do parceiro.
O QUE COSTUMA DAR ERRADO
"Revoguei a chave e a integracao parou." Causa: e o esperado. O par revogado nao vale mais. A integracao precisa receber o par de uma chave ativa.
"Criei uma chave nova e a antiga continua funcionando." Causa: e o esperado. Criar nao invalida nada; so revogar ou a validade vencer.
"Recebi Token expirado!". Causa: a chave tinha validade e ela passou. Crie outra chave e troque o par na integracao.
"Copiei a chave e nao autentica." Causa quase certa: veio so um dos dois codigos, ou um deles foi copiado pela metade.
"A API nao avisa meu sistema quando muda um pedido." Causa: expectativa de aviso automatico. Nao prometa esse aviso; ofereca verificar.
"Meu parceiro esta pedindo o token." Causa: pode ser legitimo, mas o valor nao passa pelo atendimento. Oriente o cliente a entregar direto ao parceiro, e a gerar outro par se ficar em duvida.
"Coloquei a credencial do marketplace no aplicativo API e nao funcionou." Causa: sao credenciais opostas. A do parceiro vai na tela da integracao pronta, nao aqui.