Instalando e usando o curl
Na maioria dos exemplos fornecidos na documentação do SoftExpert Suite utilizam o curl, um utilitário eficiente e de fácil utilização para efetuar requisições HTTP sem a necessidade de um navegador web. Com o curl, é possível experimentar diferentes chamadas de API por meio de uma interface de linha de comando, seja no prompt do Windows, no Terminal do macOS ou Linux. Você não precisa construir uma aplicação web funcional para experimentar as APIs.
O funcionamento do curl é similar ao de um navegador web, realizando requisições HTTP. Para requisitar uma página web a partir da linha de comando, basta digitar curl seguido do endereço URL desejado:
A resposta do servidor web é exibida diretamente em sua interface de linha de comando. Se você solicitou uma página HTML, obtém a fonte da página -- que é o que um navegador normalmente lê.
Isenção de Responsabilidade: O SoftExpert Suite não oferece suporte para tecnologias de terceiros, como curl, Windows, MacOS ou Linux. Para ajuda consulte o respectivo manual do fornecedor.
Usando o curl
Você pode usar o curl para inspecionar e testar diferentes requisições de API do SoftExpert Suite sem precisar criar um aplicativo Web funcional. Por exemplo, a instrução curl a seguir faz uma solicitação HTTP para a API do SoftExpert Documento:
curl 'https://my-domain.softexpert.com/apigateway/v1/document/view' \
-d '{"iddocument": "<id_document>"}' \
-H 'Content-Type: application/json' \
-v -H 'Authorization: <your_api_token> ' -X POST
A API retorna um objeto JSON que retorna informações do documento consultado localizado no SoftExpert Documento.
{
"return": {
"IDDOCUMENT": "007008",
"NMTITLE": "SoftExpert Suite 2.2 - Integration Guide",
"IDCATEGORY": "007",
"NMCATEGORY": "Tecnologia da Informação",
"STATUS": "2",
"NRHITS": "0",
"NMAUTHOR": "Jorge Benitez",
"IDREVISION": "00",
"DTDOCUMENT": "17/04/2023",
"RESUME": "SoftExpert Suite Integration Guide.",
"URL": "https://my-domain.softexpert.com/se/v19666/document/dc_view_document/api_view_document.php?cddocument=615",
"LINKSHARE": " ",
"ATTRIBUTTES": {
"item": {
"ATTRIBUTTENAME": "ATRNF07",
"ATTRIBUTTEVALUE": {
"document": ""
}
}
},
"ELECTRONICFILE": {
"item": {
"FILENAME": "DT22.PT0007 - 00 - DOCUMENTATION-2.2-PT_BR-Guia de integração.pdf"
}
}
}
}
JSON (JavaScript Object Notation) é um formato compacto e eficiente para a troca de informações entre sistemas. Sua estrutura foi concebida de modo a facilitar a leitura e escrita pelos seres humanos, ao mesmo tempo em que proporciona uma fácil análise e geração de dados para as máquinas.
Usando curl no Windows
Você pode usar o prompt de comando do Windows para executar os exemplos de curl. Para iniciar o prompt de comando, abra o menu Iniciar , digite cmd na caixa de pesquisa e pressione Enter.
A partir da compilação 17063 do Windows 10, o curl tornou-se um componente padrão do sistema operacional. Dessa forma, todas as instalações do Microsoft Windows 10 e Windows 11, desde então, incluem o curl por padrão em sua configuração.
Os exemplos nos documentos precisam ser ligeiramente modificados para funcionar
corretamente no Windows. Primeiro, substitua qualquer caractere de barra
invertida (\)
de fim de linha pelo caractere de circunflexo (^)
. Em segundo
lugar, se um exemplo contiver dados JSON, mova os dados para um arquivo antes de
executar o exemplo. As seções a seguir fornecem mais detalhes.
Substituir barras invertidas de fim de linha
Os exemplos de curl geralmente têm uma barra invertida (\)
no final das linhas
para dividir uma instrução longa em linhas mais fáceis de ler. A barra invertida
é um caractere de continuação de linha no UNIX, mas não no Windows. No Windows,
substitua qualquer barra invertida no final das linhas pelo caractere
circunflexo (^)
, que é um caractere de escape no Windows. Não deixe nenhum
espaço após qualquer caractere ^
ou não funcionará. O cursor escapará do
espaço em vez da nova linha.
Exemplo:
url https://my-domain.softexpert.com/apigateway/v1/document/view ^
-d '{"iddocument": "DT22.PT0007"}' ^
-H 'Content-Type: application/json' ^
-v -H 'Authorization: <your_api_token> ' -X POST
Você pode colar uma instrução de várias linhas no prompt de comando clicando no ícone no canto superior esquerdo e selecionando Editar -> Colar . Se preferir usar o teclado, pressione Alt + barra de espaço para abrir o menu e pressione E e C (E e P em inglês).
Mover dados JSON para um arquivo
O prompt de comando do Windows não suporta aspas simples. É um problema porque as instruções curl usam aspas simples para especificar dados JSON. Exemplo:
curl https://my-domain.softexpert.com/apigateway/v1/document/view ^
-d '{"iddocument": "DT22.PT0007"}' ^
-H "Content-Type: application/json" ^
-v -H 'Authorization: <your_api_token> ' -X POST
A instrução especifica dados JSON para criar um grupo (a opção -d
significa
data). Como o JSON está entre aspas simples, a instrução não funcionará na
linha de comando.
Para corrigir o problema, salve o JSON em um arquivo separado e importe-o para a instrução curl. Para modificar o exemplo acima, crie um arquivo chamado json.txt contendo o seguinte texto:
{ "iddocument": "DT22.PT0007" }
Em seguida, altere a instrução curl para importar os dados JSON com a sintaxe @filename:
curl https://my-domain.softexpert.com/apigateway/v1/document/view ^
-d @json.txt ^
-H "Content-Type: application/json" ^
-v -H 'Authorization: <your_api_token> ' -X POST
Antes de executar a instrução, use o comando cd
(alterar o diretório) para
navegar até a pasta que contém o arquivo. Exemplo:
C:\> cd json_files
Em seguida, cole a instrução curl no prompt de comando:
curl https://my-domain.softexpert.com/apigateway/v1/document/view ^
-d @json.txt ^
-H "Content-Type: application/json" ^
-v -H 'Authorization: <your_api_token> ' -X POST
Uma alternativa para não precisar mover o JSON para um arquivo separado é usar
aspas duplas em torno dos dados JSON na instrução curl
e escapar das internas
com barras invertidas:
-d "{\"group\": {\"name\": \"My Group\"}}" \
Não termina aí. Os seguintes caracteres especiais em strings devem ter escape
com o caractere circunflexo (^): &, \, <, >, ^, |
.
Então se o arquivo a ser importado contiver um desses caracteres, você terá que escapá-los.
Isso é tedioso e sujeito a erros. Melhor continuar importando o JSON de um arquivo.
Instalando o curl
Mac OS
O curl é instalado por padrão no macOS. Para experimentá-lo, consulte Testando sua instalação do curl abaixo.
Para verificar a versão instalada Execute curl --version
.
Windows 10/11 posterior a compilação 17063
Para verificar se o curl está instalado, abra o prompt de comando e digite o
comando curl -V
. Se o comando for reconhecido, o curl está instalado.
As compilações mais recentes do Windows já possuem o curl instalado por padrão. Mas você pode baixar um instalador gráfico. Após isso, o curl deve estar em seu PATH e pronto para usar pelo CMD ou PowerShell.
Linux
O curl pode ou não vir pré-instalado em uma distribuição Linux, dependendo da distribuição. Algumas distribuições populares, como Ubuntu, Debian e CentOS, geralmente incluem o curl por padrão, enquanto outras podem o incluir.
Caso você precise verificar se o cURL está instalado no seu sistema, você pode executar o seguinte comando no terminal:
curl --version
Se o curl estiver instalado, o comando retornará a versão instalada. Se não estiver, você receberá uma mensagem de erro, e será necessário instalar o cURL.
Para instalar o curl no Ubuntu ou Debian, você pode usar o seguinte comando:
sudo apt update && sudo apt install curl
Para instalar o curl no CentOS, Fedora ou RHEL, use:
sudo yum install curl
Ou, para versões mais recentes do Fedora, use:
sudo dnf install curl
Lembre-se de que os comandos de instalação podem variar dependendo da distribuição Linux que você está usando.
Testando a instalação do curl
Você pode testar a instalação do curl fazendo uma solicitação à API do SoftExpert Suite. O teste recupera informação de um documento do SoftExpert Documento.
Testar o curl
- Cole a seguinte instrução curl em seu editor de texto favorito:
curl 'https://my-domain.softexpert.com/apigateway/v1/document/view' \
-d @json.txt ^ \
-H 'Content-Type: application/json' \
-v -H 'Authorization: <your_api_token>' -X POST
Usuários do Windows: Substitua o caractere de continuação de linha de barra
invertida (\)
por um caractere de circunflexo (^)
. Certifique-se de que não
haja espaço após o cursor. Consulte
Usando curl no Windows acima.
- Substitua os espaços reservados entre chaves pelas pelo seu token de usuário e identificador do documento do SoftExpert Documento no arquivo json.txt. Exemplo:
curl "https://my-domain.softexpert.com/apigateway/v1/document/view" ^
-d @json.txt ^
-H "Content-Type: application/json" ^
-v -H "Authorization: eyJhbG..." -X POST
Exemplo do arquivo .txt
localizado em C:\> cd json_files
:
{ "iddocument": "007008" }
- Inicie sua interface de linha de comando.
- No Windows, abra o menu Iniciar, digite cmd na caixa de pesquisa e pressione Enter.
- No macOS, clique duas vezes no aplicativo Terminal na pasta Aplicativos/Utilitários. Você também pode pressionar as teclas Command + Espaço para abrir a pesquisa Spotlight e digitar "Terminal" para encontrá-lo mais rapidamente.
- Copie a instrução curl do seu arquivo de texto e cole-a no prompt de comando.
Usuários do Windows: Depois de copiá-lo para a área de transferência, selecione Editar > Colar no menu de contexto no canto superior esquerdo da janela:
- Pressione Enter para executar a instrução curl.
O console deve exibir as informações do SoftExpert Documento formatadas como um objeto JSON.
Você pode imprimir os resultados para facilitar a leitura.
Opções de linha de comando comuns do curl
-H
ou --header
: Especifica qualquer conteúdo de cabeçalho extra a ser
incluído na solicitação HTTP. As solicitações de API que enviam dados para
nossos servidores normalmente incluem o tipo de conteúdo dos dados. Exemplo:
Exemplo: -H "Content-Type: application/json"
.
-v
ou --verbose
: Torna a resposta mais detalhada.
-X
ou --request
: Especifica o método de solicitação a ser usado ao se
comunicar com o servidor HTTP.
Exemplo: -X PUT
ou -X POST
.
-d
ou --data
: A opção -d
permite especificar os dados a serem enviados no
corpo da solicitação, seja em formato de string ou em um arquivo.
Exemplo:
{ "iddocument": "<id_document>" }
-L
ou --location
: Usado para seguir automaticamente redirecionamentos HTTP.
-o
ou --output
: Usado para salvar a resposta do servidor em um arquivo
Para consultar outras opções de linha de comando do curl, consulte a documentação oficial aqui.