Introdução à API

A Pilar Collector disponibiliza uma interface de programação web, no modelo REST. Por meio dessa interface, é possível conversar com o sistema da Pilar, comandando ações, verificando configurações e realizando a sincronização com os seus sistemas.

O endereço base de comunicação é pilarcollector.com.br, acompanhado sempre do protocolo seguro https:// como prefixo. As versões da API são agrupadas por diretório, sufixadas ao endereço base (https://pilarcollector.com.br/api/).

Endereço para comunicação com a API

Este documento trata da versão da API 1.0.

O endereço para se comunicar através desta versão é:
https://pilarcollector.com.br/api/

Autenticação

A autenticação na Pilar Collector é feita através da utilização de uma chave de API. Esta chave serve para que o sistema identifique a sua conta, e concede permissões para que o sistema se comunique com a pilar em nome da conta em questão.

[POST] https://pilarcollector.com.br/api/v2/obter-token/

Parâmetros:

  • usuario (string obrigatório)
  • senha (string obrigatório)

Exemplo de chamada (cURL):


  curl --location --request POST 'https://pilarcollector.com.br/api/v2/obter-token/' \
	--header 'Content-Type: application/json' \
	--data-raw '{ \
		"usuario":"exemplo", \
		"senha":"Teste123@", \
		"force":"0" ou "1", \
	}'
					

Exemplo de retorno (JSON):


  {
     "status": true,
     "auth_token": "exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=",
  }
  					

Resposta em JSON

A fim de facilitar a interoperabilidade entre sistemas, todas as nossas chamadas de API respondem no formato JSON.

Atualizar Produtos

Importação (automática) de Produtos do sistema do cliente via API.

[POST] https://pilarcollector.com.br/api/v2/atualizar-produtos

Parâmetros:

  • auth_token (string obrigatório)
  • produtos (array of objects produto_item obrigatório)
    • produto_item:
      • codigo (string opcional, máximo 20 caracteres)
      • codigo_barras (string obrigatório, máximo 20 caracteres)
      • codigo_barras_alternativo (string opcional, máximo 20 caracteres)
      • embalagem (string opcional, máximo 50 caracteres)
      • descricao (string obrigatório, máximo 80 caracteres)
      • custo_unitario (integer opcional)
      • unidade (string opcional, máximo 10 caracteres)
      • secoes (string opcional, máximo 255 caracteres)
      • grupo (string opcional, máximo 40 caracteres)
      • sub_grupo (string opcional, máximo 40 caracteres)
      • familia (string opcional, máximo 60 caracteres)

Exemplo de chamada (cURL):

						
	curl --location --request POST 'https://pilarcollector.com.br/api/v2/atualizar-produtos/' \
	--header 'Content-Type: application/json' \
	--data-raw '{
	  "auth_token": "exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=",
	  "produtos": [
	    {
	      "codigo": "42073",
	      "codigo_barras": "7898125081607",
	      "codigo_barras_alternativo": "",
	      "embalagem": "",
	      "descricao": "AIPIM PRE COZIDO SHEKINAH 800 G",
	      "custo_unitario": "4,99",
	      "unidade": "UN",
	      "secoes": "CEREAIS - LOJA;CEREAIS - DEPÓSITO",
	      "grupo": "CEREAIS",
	      "sub_grupo": "CONGELADOS",
	      "familia": "PRE COZIDOS",
	      "ativo": "1"
        },
      ]
    }'

Exemplo de retorno (JSON):

						
	{
	  "status": true,
	  "message": "Produtos atualizados com sucesso."
	}

Atualizar Estoque - Inventário

Importação (automática) de estoque do sistema do cliente via API.

[POST] https://pilarcollector.com.br/api/v2/atualizar-estoque/

Parâmetros:

  • auth_token (string obrigatório)
  • opcao_duplicados (string[1] obrigatório)
    • [1]: Ignorar os itens duplicados
    • [2]: Somar quantidade dos itens duplicados
    • [3]: Substituir os itens duplicados
  • opcao_erros (string[1] obrigatório)
    • [1]: Ignorar os registros com erro e importar os outros
    • [2]: Não importar nenhum item
  • estoque (array of objects estoque_item obrigatório)
    • estoque_item:
      • codigo (integer obrigatório)
      • codigo_barras (string obrigatório, máximo 20 caracteres)
      • estoque_sistema (decimal obrigatório, exemplo: 896,037)
      • produto_custo_unitario (decimal obrigatório, exemplo: 4,99)

Exemplo de chamada (cURL):


  curl --location --request POST 'https://pilarcollector.com.br/api/v2/atualizar-estoque/' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "auth_token": "exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=",
     "opcao_duplicados": "1", 
     "opcao_erros": "1",
     "estoque": [
        {
        	"codigo": "42073",
        	"codigo_barras": "7898125081607",
        	"estoque_sistema": "896,037",
        	"produto_custo_unitario": "4,99",
        },
        {
        	"codigo": "32866",
        	"codigo_barras": "7898937237049",
        	"estoque_sistema": "26",
        	"produto_custo_unitario": "5,99",
        }
     ]
  }'
	

Exemplo de retorno (JSON):


{
    "status": true,
    "message": "Estoque importado com sucesso."
}
	

Obter Operações

Obtem as operações cadastradas, via API.

[POST] https://pilarcollector.com.br/api/v2/obter-operacoes/

Parâmetros:

  • auth_token (string obrigatório)

Exemplo de chamada (cURL):


curl --location --request POST 'https://pilarcollector.com.br/api/v2/obter-operacoes/' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "auth_token": "exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=",
}'

Exemplo de retorno (JSON):


{
  "status": true,
  "operacoes": [
    {
      "id": 4,
      "descricao": "Entrada",
      "tipo": "E",
      "status": "A",
      "permitir_importar_repetido": false
    }
  ]
}
O campo "tipo" pode ser:
  • "E" - Entrada
  • "S" - Saída
O campo "status" pode ser:
  • "A" - Ativo
  • "I" - Inativo
O campo "permitir_importar_repetido" pode ser:
  • "true" - permite importar nota com "chave_acesso_nfe" repetido
  • "false" - não permite importar nota com "chave_acesso_nfe" repetido

Atualizar Estoque - Expedição

Importação (automática) de estoque de Expedição, via API.

[POST] https://pilarcollector.com.br/api/v2/atualizar-estoque-expedicao/

Parâmetros:

  • auth_token (string obrigatório)
  • Carga (Devem ser todos os 3 campos informados ou nenhum)
    Não é permitido adicionar Nota Fiscal em Carga com status não bloqueada
    • numero (string não obrigatório, máximo 16 caracteres)
    • data_saida (string não obrigatório, formato "dd/mm/AAAA")
    • tipo (string não obrigatório)
      • [E]: Entrada
      • [S]: Saída
  • Veículo
    • placa (string não obrigatório, máximo 20 caracteres)
  • Motorista
    • nome (string não obrigatório, máximo 100 caracteres)
  • Doca
    • nome (string não obrigatório, máximo 20 caracteres)
  • Lista de Pedidos/NFs (array of objects obrigatório)
    • Pedido / Nota Fiscal
      • chave_acesso_nfe (string não obrigatório, máximo 50 caracteres)
      • numero_nota (string obrigatório, máximo 16 caracteres)
      • tipo (string obrigatório, 1 caracter)
        • [E]: Entrada
        • [S]: Saída
      • cliente_pedido (string não obrigatório, máximo 200 caracteres)
      • Operação
        • id (integer obrigatório, id da operação)
      • Cliente armazenagem
        • id (integer obrigatório, id do cliente)
      • status (string obrigatório, 1 caracter)
        • [0]: Pendente
        • [1]: Em expedição
        • [2]: Em rota
        • [3]: Devolvido
        • [4]: Entregue
        • [5]: Reentrada
        • [6]: Canhoto retido
        • [7]: Devolvido parcial
      • Itens do Pedido/NF (array of objects itens_nota_fiscal obrigatório)
        Os itens do mesmo produto e com mesma validade e lote serão agrupados, somando as quantidades.
        • itens_nota_fiscal:
          • codigo (integer obrigatório)
          • codigo_barras (string obrigatório, máximo 20 caracteres)
          • quantidade (decimal obrigatório, exemplo: 896,037)
          • unidade (string não obrigatório, máximo 10 caracteres)
          • validade (string não obrigatório, formato "dd/mm/AAAA")
          • lote (string não obrigatório, máximo 30 caracteres)

Exemplo de chamada (cURL):


curl --location --request POST 'https://pilarcollector.com.br/api/v2/atualizar-estoque-expedicao/' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "auth_token": "exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=",
  "carga": {
    "numero": "",
    "data_saida": "10/10/2024",
    "tipo": "E"
  },
  "veiculo": {
    "placa": "123"
  },
  "motorista": {
    "nome": "João"
  },
  "doca": {
    "nome": ""
  },
  "lista_de_notas_fiscais": [
    {
      "nota_fiscal": {
        "chave_acesso_nfe": "NFe28220903522737000104550010001844351272702003",
        "numero_nota": "12345678",
        "tipo": "E",
        "cliente_pedido": "",
        "operacao": {
          "id": 123
        },
        "cliente_armazenagem": {
          "id": 123
        },
        "status": ""
      },
	  "itens_nota_fiscal": [
        {
          "codigo": "42073",
          "codigo_barras": "7898125081607",
          "quantidade": "896,037",
          "unidade": "CX",
          "validade": "10/10/2024",
          "lote": ""
        }
      ]
    }
  ]
}'

Exemplo de retorno (JSON):


{
  "status": true,
  "message": "Atualização completa com sucesso."
}
  					

Retorno das coletas do inventário aberto

Retorna os dados das coletas do inventário aberto, via API.

[POST] https://pilarcollector.com.br/api/v2/retorno-das-coletas-do-inventario-aberto/

Parâmetros:

  • auth_token (string obrigatório)
  • Local
    • id (integer não obrigatório)
  • Seção
    • id (integer não obrigatório)
  • Gôndola
    • id (integer não obrigatório)
  • Inventário
    • id (integer obrigatório)

Exemplo de chamada (cURL):


curl --location --request POST 'https://pilarcollector.com.br/api/v2/retorno-das-coletas-do-inventario-aberto/' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "auth_token": "exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=",
  "local": {
    "id": 12
  },
  "secao": {
    "id": 23
  },
  "gondola": {
    "id": 34
  },
  "inventario": {
    "id": 45
  },
}'

Exemplo de retorno (JSON):

{
  "status": true,
  "inventario": {
    "id": 2490,
    "codigo": 114,
    "codigo_auxiliar": "",
    "quantidade_contado": "1256.00",
    "quantidade_sistema": "0.00",
    "fechado": true,
    "inicio": "11/04/2022",
    "fim": "11/04/2022",
    "tempo": "654"
  },
  "itens": [
    {
      "quantidade": "4.000",
      "codigo_barras": "7898537113781",
      "codigo_interno": "1101001023",
      "descricao": "CAPA DE BANCO SUZUKI AE 50",
      "custo_unitario": "0.00"
    },
    {...}
  ]
}