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.

Há duas etapas de autenticação, sendo a primeira enviando um requisição POST com usuário/email (um dos 2 parâmetros é obrigatório) e senha, será retornado o token de autenticação temporário (24h) esse token deverá ser utilizado em todas as requisições via API da pilar através do parâmetro de nome auth_token.

[POST] https://pilarcollector.com.br/api/login

Parâmetros:

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

Exemplo de chamada (cURL):


  curl --location --request POST 'https://pilarcollector.com.br/api/login/' \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode 'usuario=exemplo' \
	--data-urlencode 'email=teste@exemplo.com.br' \
	--data-urlencode 'senha=Teste123@'
	

Exemplo de retorno (JSON):


  {
     "status": true,
     "auth_token": "exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=",
     "funcionario": {
        "funcao": {
            "pk": 1856,
            "nome": "Analista"
        },
        "celular": "(27)99723-9386",
        "telefone": "",
        "nome": "Usuário exemplo",
        "pk": 153403,
        "cliente": {
            "cnpj": "",
            "razao_social": "PILAR CONSULTORIA",
            "pk": 8,
            "grupo": {
                "pk": 45631,
                "nome": "TESTE"
            },
            "fantasia": "PILAR CONSULTORIA",
            "ativo": true
        },
        "ativo": true,
        "email": "teste@exemplo.com.br",
        "cpf": "000.000.000-00",
        "user": {
            "username": "exemplo",
            "pk": 57434,
            "is_staff": true,
            "is_active": true,
            "is_superuser": false
        }
     }
  }
	

Resposta em JSON

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

Como especificar o formato de resposta

Você tem duas formas de especificar o formato de resposta:

  1. Adicionar a extensão ".json" no final dos endereços de API.
  2. Enviar um Header HTTP contendo JSON como tipo de conteúdo: "Accept: application/json".

Atualizar Estoque

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

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

Parâmetros:

  • auth_token (string obrigatório)
  • opcao_duplicados (string[1] obrigatório)
    • [1]: Ignorar os produtos duplicados
    • [2]: Somar quantidade dos produtos duplicados
    • [3]: Substituir os produtos duplicados
  • opcao_erros_planilha (string[1] obrigatório)
    • [1]: Ignorar os registros com erro e importar os outros
    • [2]: Não importar a planilha
  • estoque (array of objects estoque_item obrigatório)
    • estoque_item:
      • codigo (integer obrigatório)
      • codigo_barras (string obrigatório, máximo 20 caracteres)
      • codigo_barras_alternativo (string opcional, máximo 20 caracteres)
      • embalagem (integer opcional)
      • descricao (string obrigatório, máximo 80 caracteres)
      • qtd_estoque_sistema (decimal obrigatório, exemplo: 896,037)
      • custo_unitario (decimal obrigatório, exemplo: 4,99)
      • unidade (string obrigatório, exemplo: UN, KG, L, CX)
      • secoes (string opcional, exemplo: CEREAIS - LOJA;CEREAIS - DEPÓSITO)
      • grupo (string opcional, exemplo: HORTIFRUTI)
      • sub_grupo (string opcional, exemplo: FRUTAS)
      • familia (string opcional, exemplo: FRUTAS CÍTRICAS)
      • ativo (string opcional)
        • [0]: Inativo
        • [1]: Ativo

Exemplo de chamada (cURL):


  curl --location --request POST 'https://pilarcollector.com.br/api/atualizar-estoque-sistema/' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "auth_token": "exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=",
     "opcao_duplicados": "1", 
     "opcao_erros_planilha": "1",
     "estoque": [
        {
        	"codigo": "42073",
        	"codigo_barras": "7898125081607",
        	"codigo_barras_alternativo": "",
        	"embalagem": "",
        	"descricao": "AIPIM PRE COZIDO SHEKINAH 800 G",
        	"qtd_estoque_sistema": "896,037",
        	"custo_unitario": "4,99",
        	"unidade": "UN",
        	"secoes": "CEREAIS - LOJA;CEREAIS - DEPÓSITO",
        	"grupo": "CEREAIS",
        	"sub_grupo": "CONGELADOS",
        	"familia": "PRE COZIDOS",
        	"ativo": "1"
        },
        {
        	"codigo": "32866",
        	"codigo_barras": "7898937237049",
        	"codigo_barras_alternativo": "",
        	"embalagem": "",
        	"descricao": "AMEIXA BLACK RUBY 1 2A CAMBUCA 650G",
        	"qtd_estoque_sistema": "26",
        	"custo_unitario": "5,99",
        	"unidade": "UN",
        	"secoes": "CEREAIS - LOJA",
        	"grupo": "HORTIFRUTI",
        	"sub_grupo": "FRUTAS",
        	"familia": "FRUTAS VERMELHAS",
        	"ativo": "1"
        }
     ]
  }'
	

Exemplo de retorno (JSON):


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

Listar expedição

Lista de expedições do sistema.

[GET] https://pilarcollector.com.br/api/nota

Parâmetros:

  • auth_token (string obrigatório)

Exemplo de chamada (cURL):


  curl --request GET \
    --url https://pilarcollector.com.br/api/nota/ \
    --header 'Authorization: Bearer Bearer exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=' \

Exemplo de retorno (JSON):


[
    {
        "id": 162,
        "notaitem_set": [
            {
                "id": 398,
                "unidade": "UN",
                "quantidade": "10.000",
                "desconto": "0.000",
                "quantidade_nf": "10.000",
                "valor_unitario": "0.000",
                "valor_total": "0.000",
                "quantidade_contagem": "10.000",
                "validade": "2024-01-01",
                "lote": null,
                "inconsistencia": false,
                "corte": false,
                "corte_qtd": "0.000",
                "conferido": true,
                "produto": 2311633,
                "corte_motivo": null
            },
            {
                "id": 399,
                "unidade": null,
                "quantidade": "0.000",
                "desconto": "0.000",
                "quantidade_nf": "5.000",
                "valor_unitario": "0.000",
                "valor_total": "0.000",
                "quantidade_contagem": "0.000",
                "validade": "2024-01-01",
                "lote": null,
                "inconsistencia": true,
                "corte": true,
                "corte_qtd": "5.000",
                "conferido": false,
                "produto": 2327927,
                "corte_motivo": null
            },
            {
                "id": 400,
                "unidade": null,
                "quantidade": "0.000",
                "desconto": "0.000",
                "quantidade_nf": "1.000",
                "valor_unitario": "0.000",
                "valor_total": "0.000",
                "quantidade_contagem": "0.000",
                "validade": "2025-01-01",
                "lote": null,
                "inconsistencia": true,
                "corte": true,
                "corte_qtd": "1.000",
                "conferido": false,
                "produto": 2327927,
                "corte_motivo": null
            }
        ],
        "cliente_pedido": "NOME DA EMPRESA DO CLIENTE",
        "chave_acesso_nfe": null,
        "numero_nota": "32048082",
        "serie_nota": "1",
        "data": "2023-06-28",
        "data_cadastro": "2023-06-28T16:26:15.014564",
        "tipo": "S",
        "desconto": "0.000",
        "valor_total": "0.000",
        "codigo_pedido_omie": null,
        "carga": 121,
        "operacao": 3,
        "cliente": 2,
        "fornecedor": null,
        "funcionario": null
    }
]
	

Listar produtos

Lista de produtos do sistema.

[GET] https://pilarcollector.com.br/api/produtos

Parâmetros:

  • auth_token (string obrigatório)
  • codigo_filter (string opcional)
  • search (string opcional, exemplos: chocolate, 7891150041349 OU 47056)

Exemplo de chamada (cURL):


  curl --request GET \
    --url https://pilarcollector.com.br/api/produtos?codigo_filter=7891150041349&search=chocolate \
    --header 'Authorization: Bearer Bearer exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=' \

Exemplo de retorno (JSON):


[
    {
        "id": 1881188,
        "codigo_barras": "7891150041349",
        "codigo_interno": "47056",
        "descricao": "ADES 200ML CHOCOLATE",
        "slug": "ades-chocolate-200ml",
        "embalagem": 1,
        "embalagem_desc": null,
        "custo_unitario": "1.32",
        "ativo": true,
        "codigo_barras_alternativo": "",
        "secoes": "",
        "pesavel": null,
        "unidade": "UN",
        "shelf_life": 0,
        "cods_alters": null,
        "preco_venda": null,
        "dun": null,
        "peso_variavel": false,
        "peso_liq": "0.000",
        "peso_bruto": "0.000",
        "peso_embalagem": "0.000",
        "peso_min": "0.000",
        "peso_max": "0.000",
        "altura": "0.000",
        "largura": "0.000",
        "comprimento": "0.000",
        "cubagem": 0.0,
        "altura_pallet": null,
        "lastro_pallet": null,
        "caixas_pallet": null,
        "numero_serie": null,
        "numero_patrimonio": null,
        "imagem": null,
        "atualizar_etiqueta": false,
        "data_conferencia_etiqueta": null,
        "data_impressao_etiqueta": null,
        "classe": 6434,
        "subclasse": 98290,
        "familia": 119186,
        "cliente": 38,
        "tipo_carne": null,
        "refrigeracao": null,
        "usuario_conferencia_etiqueta": null
    }
]
	

Listar recebimentos de produtos

Lista de recebimentos de produtos do sistema.

[GET] https://pilarcollector.com.br/api/recebimentoproduto

Parâmetros:

  • auth_token (string obrigatório)
  • search (integer opcional, número da ordem de expedição, exemplo: 0)

Exemplo de chamada (cURL):


  curl --request GET \
    --url https://pilarcollector.com.br/api/recebimentoproduto?search=0 \
    --header 'Authorization: Bearer Bearer exemplo::pbkdf2_sha256$24000$HJMs7tozaitE$497y1jWZB515kXt5eGh00pWCULXR7LIPCCNU/W8sk6g=' \

Exemplo de retorno (JSON):


[
    {
        "id": 3,
        "produto_descricao": "LINGUICA FRANGO SEARA 700G",
        "produto_codigo_barras": "17894904259394",
        "unidade": "CX",
        "validade": null,
        "lote": null,
        "quantidade": "100.000",
        "quantidade_nf": "0.000",
        "valor_unitario": "250.815",
        "quantidade_contagem": null,
        "contado_em": "2022-08-03T16:05:46.044445",
        "nota": 3,
        "produto": 5216391,
        "contado_por": null
    }
]