Introdução

Sobre

A integração com o sistema iApp é feita através de uma API em protocolo HTTP (modelo REST), e os dados são comunicados em formato JSON. Apesar das siglas complicadas, o processo é muito simples. Seu software poderá se comunicar com nossos servidores através de requisições HTTP, de forma muito parecida com um navegador de internet.

O protocolo HTTP é utilizado pelos navegadores para se comunicar com servidores web, através dos métodos GET, POST e PUT. Você irá utilizar estes mesmos métodos para fazer leitura, cadastro e atualização de registros em nossa API.

Utilizamos o protocolo HTTPS no ambiente.

Protocolo e Estrutura

Protocolo: HTTPS (com criptografia SSL/TLS)
Formato dos dados: JSON
Métodos suportados:
- GET → Leitura de informações
- POST → Criação de registros
- PUT → Atualização de registros
- DELETE → Exclusão (em endpoints específicos)

Cada requisição enviada para a API deve conter a URL completa do recurso desejado, o método HTTP apropriado e, quando aplicável, os cabeçalhos de autenticação e o corpo (body) da requisição em formato JSON.

Autenticação

A segurança é prioridade em todas as integrações com o iApp.

Por isso, a API utiliza autenticação baseada em Token e Secret, que funcionam como chaves exclusivas de acesso.

Essas credenciais garantem que apenas usuários autorizados possam realizar operações em seus respectivos ambientes.

Token → Identifica o cliente (empresa).
Secret → Atua como uma senha criptográfica que valida a integridade da requisição.

Essas credenciais podem ser encontradas dentro do iApp acessando:

Engrenagem → Minha Empresa → Rodapé da Página.

Ao realizar qualquer requisição, ambos devem ser enviados no header HTTP:

token: SEU_TOKEN_AQUI
secret: SEU_SECRET_AQUI

Exemplo em formato cURL:

                        curl -X GET "https://api.iniciativaaplicativos.com.br/api/manufatura/ordens-producao/lista?offset=50&page=1" \
                        -H "token: 1234567890abcdef" \
                        -H "secret: abcdef1234567890"

Endpoint Base

Todas as requisições devem iniciar pelo endpoint principal:

https://api.iniciativaaplicativos.com.br/api

A partir dele, você acessa os módulos e funcionalidades disponíveis — por exemplo:

/manufatura/ordens-producao/lista

/comercial/pedidos-venda/lista

/estoque/movimentacoes/lista

A lista completa de módulos e endpoints pode ser consultada aqui.

Paginação

Para garantir performance e evitar sobrecarga nos servidores, todas as requisições de listagem exigem parâmetros de paginação:

offset: Númerico -> Quantidade máxima de registros retornados por página.
page: Númerico -> Número da página a ser retornada.

Exemplo:

?offset=50&page=2

Retorna os registros de 51 a 100.

Filtros

A maioria dos endpoints de listagem aceita filtros personalizados para refinar os resultados.

Os filtros devem ser enviados no parâmetro filters da URL, usando a seguinte convenção:

filters=chave|valor;chave2|valor2

Regras gerais:

Vários filtros devem ser separados por ponto e vírgula (;)
Cada filtro contém um par chave|valor.
Para intervalos numéricos ou de datas, use dois valores separados por dois-pontos (:).
As datas devem seguir o formato YYYY-MM-DD.

Exemplo de uso:

filters=data_inicial|2025-01-01:data_final|2025-01-31;status|Fechado

Esse filtro retornará todos os registros com status “Fechado” no intervalo de janeiro de 2025.

Ordenação

É possível ordenar os resultados utilizando os parâmetros:

sort_by: Text -> Nome do campo pelo qual deseja ordenar.
sort_type: Text -> Tipo da Ordenação: ASC - Ascendente ou DESC - Decrescente

Exemplo:

sort_by=data_emissao&sort_type=DESC

Resumo prático (exemplo completo)

Requisição:

                        GET https://api.iniciativaaplicativos.com.br/api/manufatura/ordens-producao/lista?offset=50&page=1&filters=status|Aberto;data|2025-01-01:2025-01-31&sort_by=data_emissao&sort_type=DESC

Cabeçalhos:

                        token: 1234567890abcdef
                        secret: abcdef1234567890

Resposta (JSON simplificado):

                        {
                            "total": 230,
                            "page": 1,
                            "offset": 50,
                            "data": [
                                {
                                    "id": 1082,
                                    "codigo": "OP-2025-001",
                                    "produto": "Massa Pão de Queijo 1kg",
                                    "status": "Aberto",
                                    "data_emissao": "2025-01-10"
                                }
                            ]
                        }