API: onde está a documentação, como pesquisar nela e baixar o arquivo OpenAPI

A documentação da API de integração fica dentro do próprio sistema, no aplicativo API. Ela mostra recurso por recurso o que a API aceita: cada endereço, o método, os filtros, os campos obrigatórios e exemplos de envio e de retorno.

Caminho

Meus aplicativos › Ver todos os aplicativos › API (botão Acessar)

Na tela inicial do aplicativo, clique no cartão Documentação. No menu lateral, o item Documentação abre a mesma tela.

O que a tela mostra

No topo aparece o Servidor: é o endereço base que a sua integração deve usar. Ele é o da sua conta, então use o que a tela mostra, e não um endereço copiado de outro lugar.

O botão Baixar OpenAPI entrega o arquivo completo da documentação no padrão OpenAPI. É esse arquivo que se importa em programas de requisição para ter todas as chamadas prontas.

Logo abaixo vêm as regras gerais que valem para a API inteira:

  • Autenticação — os dois códigos, Access Token e Secret Access Token, enviados como cabeçalhos em toda chamada.
  • Limite de requisições — a documentação informa o máximo por segundo e por dia; ao ultrapassar, a resposta vem com o código 429.
  • Limites de registros — toda listagem é paginada, com no máximo 100 registros por página. Os parâmetros de página, limite, ordenação e direção estão descritos ali.
  • Atribuição de usuário e de loja — quando a conta tem mais de um usuário ou mais de uma loja, o que informar para a chamada entrar como o usuário e a loja certos.

Pesquisar um recurso

O campo Buscar recurso ou endpoint… filtra o sumário na hora. Digite o nome do recurso (clientes, vendas, recebimentos) ou um pedaço do endereço.

O sumário é agrupado por módulo: cadastros, produtos e serviços; orçamentos, vendas e ordens de serviço; compras; financeiro; notas fiscais; e assinatura digital. Ao lado de cada recurso aparece o número de operações dele. Clicando, a página rola até o recurso, com uma linha por operação: listar, cadastrar, visualizar, editar, excluir e as ações próprias de cada um, como gerar parcelas, emitir e cancelar nota.

Cada operação abre com os filtros aceitos, os campos obrigatórios e os exemplos.

A lista muda conforme o que você contratou

A documentação mostra só os módulos do seu produto. Quem usa a linha de emissão fiscal vê uma lista diferente de quem usa o sistema de gestão completo. Recurso que não aparece na sua documentação não está disponível para a sua conta.

O módulo de assinatura digital tem uma diferença marcada na própria página: responde sem o envelope padrão dos outros recursos. A tela sinaliza isso ao lado do módulo.

Os dois endereços que funcionam

A API responde tanto no endereço que termina em /api quanto no que termina em /v1. São o mesmo destino. Se a sua integração já usa um deles, não precisa trocar.

O único endereço fora de uso continua sendo o que tem /api/v2/, que responde "Este App foi descontinuado!".

Quando dá errado

  • A documentação não abre — ela fica dentro do aplicativo API. Se o aplicativo não está liberado na conta, o cartão dele em Meus aplicativos mostra Testar grátis ou Acessar.
  • Não encontro o endpoint que eu queria — use o campo de busca. Se ainda assim não aparece, o recurso não faz parte da sua linha de produto ou não é exposto pela API. A fonte sobre o que dá e o que não dá para fazer tem as duas listas confirmadas.
  • O arquivo OpenAPI não importa no meu programa — o arquivo segue o padrão OpenAPI 3; confira se o programa aceita essa versão.
  • A doc mostra um endereço e minha integração usa outro — vale o que a tela mostra para a sua conta. Endereço com /api e com /v1 são equivalentes; endereço com /api/v2/ está descontinuado.