Contrato OpenAPI
Baixe o contrato da API e importe no Postman, no Insomnia ou no gerador de código que você usa.
Esta página é para quem prefere testar a API numa ferramenta em vez do terminal, ou quer gerar o cliente a partir do contrato.
Onde está o contrato
O contrato da API v1 é um arquivo OpenAPI 3. Ele tem cada rota, cada campo, os exemplos e o significado de cada erro, em português. É o mesmo arquivo que monta a referência.
| Onde | O que é |
|---|---|
/openapi-v1.json | O contrato desta documentação, já apontando para a API deste ambiente. |
https://api-staging.kinho.dev/api/v1/docs-json | O contrato que a API de staging publica agora. |
https://api-staging.kinho.dev/api/v1/docs | A mesma coisa numa página do Swagger, com o botão para testar cada rota com a sua chave (só em staging). |
Em produção, a API publica o contrato em https://api.topocontabil.com.br/api/v1/docs-json, sem o botão de teste.
Importar no Postman
- No Postman, clique em Import e cole o endereço
https://developers-staging.kinho.dev/openapi-v1.json. Esse arquivo só aponta para a API de staging; o de/api/v1/docs-jsonlista produção primeiro, e o Postman usaria produção como endereço. - Escolha Postman Collection. Em Folder organization, escolha Tags, para ter uma pasta por assunto: Empresas, Planos de contas, Balancetes, Conciliações e GraphQL. Confirme.
- Na coleção, abra Authorization, escolha Bearer Token e ponha
{{TOPO_CHAVE}}. Crie a variávelTOPO_CHAVEnum ambiente do Postman, do tipo secreto, com a sua chave. - Confira a variável
baseUrlda coleção: ela deve serhttps://api-staging.kinho.dev.
No Insomnia o caminho é o mesmo: Import, cole o endereço, e ponha a chave no Auth da coleção.
Gerar o cliente
Qualquer gerador de OpenAPI 3 lê o contrato. Por exemplo, para TypeScript:
npx openapi-typescript https://developers-staging.kinho.dev/openapi-v1.json -o topo-api.d.tsNão há SDK oficial do TOPO. O contrato é conferido a cada mudança da API, então o cliente gerado dele acompanha o que a API responde.