A documentação da API fica dentro da Kamino, em Documentação da API, no rodapé do menu lateral. Ela traz os conceitos, a referência de cada rota e o botão Testar, que chama o ambiente de teste com o seu acesso, sem chave.
Antes de começar a primeira chamada à API
Quem abre a documentação: quem está logado na Kamino e tem acesso à documentação. Para quem escreve o código e não é usuário da Kamino, o administrador libera um passe. Veja "Passe de documentação da API".
Para chamar do seu sistema: uma chave de API. Para começar, uma chave de teste. Veja "Como criar, acompanhar e revogar uma chave de API".
Passo a passo para fazer a primeira chamada à API
No rodapé do menu lateral, clique em Documentação da API. A página Visão geral abre.
Leia Antes de começar e copie a chamada do bloco Sua primeira chamada.
Troque o valor depois de
Bearerpelo segredo da sua chave.Para testar sem chave, abra uma rota em Referência (por exemplo, Contas a receber › Listar) e clique em Testar. Com Teste escolhido em Ambiente dos exemplos, a chamada vai ao ambiente de teste com o seu acesso.
Confira a resposta em Última execução: o status, o ambiente e o tempo da chamada.
O cabeçalho de autenticação da API
Toda chamada leva o segredo no cabeçalho Authorization: Bearer <segredo>.
O identificador da chave não vai na chamada; ele serve só para achar a chave na lista.
Testar em produção pela documentação
Com Produção escolhido em Ambiente dos exemplos, o Testar pede o Segredo da chave de produção. Em produção a chamada lê e grava dados reais. O segredo vai só no cabeçalho daquela chamada e não fica guardado.
Erros da primeira chamada à API, e o que fazer
401 invalid_key— o segredo não corresponde a uma chave ativa. Confira o segredo; repetir não resolve.401 key_expiredou401 key_revoked— a chave venceu ou foi revogada. Peça uma chave nova.401 environment_mismatch— a chave é de um ambiente e a rota é do outro. Use/testcom chave de teste.403 insufficient_scope— a chave não tem a permissão que a rota pede. Peça ao administrador a permissão nomeada na resposta.429 rate_limited— o limite de chamadas acabou. Espere os segundos do cabeçalhoRetry-After.
Perguntas frequentes sobre a documentação da API
Preciso de chave para usar o botão Testar?
Não, no ambiente de teste. Em produção, o Testar pede o segredo de uma chave de produção.
O primeiro Testar respondeu 503 sandbox_unavailable. O que eu faço?
O primeiro Testar da sua empresa cria o ambiente de teste, com dados fictícios. Enquanto ele é criado, a Última execução mostra 503 sandbox_unavailable e a orientação para clicar em Testar de novo em alguns segundos. O ambiente fica pronto sozinho, sem nenhuma ação sua. Se o 503 continuar depois de um minuto, fale com o suporte.
A documentação está em inglês?
A documentação está em português. As mensagens de erro que a API devolve ao sistema vêm em inglês.