Versão: 2.2.0

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ê.

cuidado

  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).

Atalhos para colar no prompt de comando do Windows

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.

Usando o curl​

Usando curl no Windows​

Substituir barras invertidas de fim de linha​

Mover dados JSON para um arquivo​

Instalando o curl​

Mac OS​

Windows 10/11 posterior a compilação 17063​

Linux​

Testando a instalação do curl​