API do ERP Connect Mobile

Testar a chave

GET/v1/status

qualquer chave

Confirma que a chave funciona e diz a empresa, as permissões e quanto do limite do minuto já foi usado. Use como primeiro teste.

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/status" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "ok": true,
  "empresa": {
    "id": "uuid",
    "nome": "Minha Empresa"
  },
  "chave": {
    "nome": "Integração Bling",
    "escopos": [
      "produtos:read",
      "estoque:read"
    ]
  },
  "limite": {
    "por_minuto": 120,
    "usadas": 3
  },
  "versao": "1.2.2",
  "hora_servidor": "2026-11-07T22:22:00Z"
}

Especificação OpenAPI 3.1

GET/v1/openapi.json

sem chave

A API inteira em OpenAPI 3.1 (JSON). Importe no Postman, Insomnia, Swagger ou no gerador de código da sua linguagem. Não precisa de chave.

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/openapi.json"

Listar produtos

GET/v1/produtos

permissão produtos:read?formato=csv

Lista paginada com todos os campos do produto, as URLs das fotos (até 12) e o saldo. Produto base (componente) só aparece com incluir_base=1.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "072f458d-…",
      "erp_id": 1234,
      "referencia": "CP-01",
      "codigo_barras": "7890000000017",
      "nome": "Coador de pano nº 3",
      "marca": "Mesa Posta",
      "unidade": "UN",
      "preco_venda": 13.19,
      "estoque": 70,
      "estoque_reservado": 2,
      "disponivel": 68,
      "ncm": "63079090",
      "peso_kg": 0.12,
      "ativo": true,
      "categoria": "Utilidades",
      "tipo_produto": "venda",
      "foto_principal_url": "https://…/produto-1234-capa.jpg",
      "fotos": [
        "https://…/1.jpg",
        "https://…/2.jpg"
      ],
      "updated_at": "2026-11-07T19:22:00-03:00"
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 100,
    "total": 1,
    "total_paginas": 1
  }
}

Ler um produto

GET/v1/produtos/{produto}

permissão produtos:read

Todos os campos do produto + fotos (ordem, capa), códigos de barras, variações, composição (kit) e saldo.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": {
    "id": "072f458d-…",
    "erp_id": 1234,
    "referencia": "CP-01",
    "codigo_barras": "7890000000017",
    "nome": "Coador de pano nº 3",
    "marca": "Mesa Posta",
    "unidade": "UN",
    "preco_venda": 13.19,
    "estoque": 70,
    "estoque_reservado": 2,
    "disponivel": 68,
    "ncm": "63079090",
    "peso_kg": 0.12,
    "ativo": true,
    "categoria": "Utilidades",
    "tipo_produto": "venda",
    "foto_principal_url": "https://…/produto-1234-capa.jpg",
    "fotos": [
      "https://…/1.jpg",
      "https://…/2.jpg"
    ],
    "updated_at": "2026-11-07T19:22:00-03:00",
    "codigos_barras": [
      {
        "codigo": "7890000000017",
        "principal": true
      }
    ],
    "variacoes": [],
    "composicao": []
  }
}

Erros específicos

Criar produto

POST/v1/produtos

permissão produtos:writeaceita Idempotency-Key

Cria um produto de venda com o código numérico seguinte da empresa. Aceita qualquer campo gravável (ver Campos do produto). Estoque inicial: use POST /estoque/entradas depois. Se a referência ou o código de barras já existir, devolve 409 com o id do produto existente.

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/produtos" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"nome":"Coador de pano nº 3","referencia":"CP-01","codigo_barras":"7890000000017","unidade":"UN","preco_venda":13.19,"ncm":"63079090","peso_kg":0.12}'

Resposta

{
  "dados": {
    "id": "072f458d-…",
    "erp_id": 1234,
    "referencia": "CP-01",
    "codigo_barras": "7890000000017",
    "nome": "Coador de pano nº 3",
    "marca": "Mesa Posta",
    "unidade": "UN",
    "preco_venda": 13.19,
    "estoque": 70,
    "estoque_reservado": 2,
    "disponivel": 68,
    "ncm": "63079090",
    "peso_kg": 0.12,
    "ativo": true,
    "categoria": "Utilidades",
    "tipo_produto": "venda",
    "foto_principal_url": "https://…/produto-1234-capa.jpg",
    "fotos": [
      "https://…/1.jpg",
      "https://…/2.jpg"
    ],
    "updated_at": "2026-11-07T19:22:00-03:00"
  }
}

Erros específicos

Alterar produto

PATCH/v1/produtos/{produto}

permissão produtos:writeaceita Idempotency-Key

Muda só os campos enviados. Campo que não é gravável é recusado com 422 (nunca ignorado em silêncio).

Parâmetros

Exemplo

curl -X PATCH "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"preco_venda":14.5,"ncm":"63079090"}'

Resposta

{
  "dados": {
    "id": "072f458d-…",
    "erp_id": 1234,
    "referencia": "CP-01",
    "codigo_barras": "7890000000017",
    "nome": "Coador de pano nº 3",
    "marca": "Mesa Posta",
    "unidade": "UN",
    "preco_venda": 13.19,
    "estoque": 70,
    "estoque_reservado": 2,
    "disponivel": 68,
    "ncm": "63079090",
    "peso_kg": 0.12,
    "ativo": true,
    "categoria": "Utilidades",
    "tipo_produto": "venda",
    "foto_principal_url": "https://…/produto-1234-capa.jpg",
    "fotos": [
      "https://…/1.jpg",
      "https://…/2.jpg"
    ],
    "updated_at": "2026-11-07T19:22:00-03:00"
  },
  "alterados": [
    "preco_venda",
    "ncm"
  ]
}

Erros específicos

Alterar vários produtos

PATCH/v1/produtos

permissão produtos:writeaceita Idempotency-Key

Até 200 produtos numa chamada. Cada item leva "produto" (identificador) e os campos. Um item com erro não derruba os outros: a resposta diz o resultado de cada um.

Exemplo

curl -X PATCH "https://app.erpconnectmobile.com.br/api/v1/produtos" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"produtos":[{"produto":"sku:CP-01","preco_venda":14.5},{"produto":"ean:7890000000024","ativo":false}]}'

Resposta

{
  "ok": 2,
  "total": 2,
  "resultados": [
    {
      "produto": "sku:CP-01",
      "ok": true
    },
    {
      "produto": "ean:7890000000024",
      "ok": true
    }
  ]
}

Inativar produto

DELETE/v1/produtos/{produto}

permissão produtos:write

Produto nunca é apagado (pedidos, notas e lotes apontam para ele): fica inativo. Para reativar, PATCH ativo=true.

Parâmetros

Exemplo

curl -X DELETE "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "ok": true,
  "dados": {
    "id": "uuid",
    "ativo": false
  }
}

Erros específicos

Lista de campos do produto

GET/v1/produtos/campos

permissão produtos:read

Todos os campos do produto com tipo, grupo, se é gravável e limite. É a mesma tabela desta documentação.

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/campos" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "nome": "preco_venda",
      "tipo": "numero",
      "grupo": "preco",
      "gravavel": true,
      "descricao": "Preço de venda (R$)."
    }
  ]
}

Ler um campo

GET/v1/produtos/{produto}/campos/{campo}

permissão produtos:read

Devolve só o valor de um campo. Serve para todo campo da tabela "Campos do produto".

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/campos/preco_venda" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "produto_id": "uuid",
  "campo": "preco_venda",
  "valor": 13.19
}

Erros específicos

Gravar um campo

PUT/v1/produtos/{produto}/campos/{campo}

permissão produtos:writeaceita Idempotency-Key

Grava um campo só. Corpo: {"valor": …}. Recusa campo só-leitura (403) e valor do tipo errado (422).

Parâmetros

Exemplo

curl -X PUT "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/campos/ncm" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"valor":"63079090"}'

Resposta

{
  "produto_id": "uuid",
  "campo": "ncm",
  "valor": "63079090",
  "anterior": "63079000"
}

Erros específicos

Listar fotos

GET/v1/produtos/{produto}/fotos

permissão produtos:read

As fotos do produto na ordem (até 12). A de ordem 0 é a capa. URLs públicas, prontas para marketplace.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/fotos" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "ordem": 0,
      "capa": true,
      "url": "https://…/1.jpg",
      "miniatura_url": "https://…/1-thumb.jpg"
    }
  ],
  "maximo": 12
}

Adicionar foto

POST/v1/produtos/{produto}/fotos

permissão fotos:writeaceita Idempotency-Key

Manda a foto por URL pública (https) OU em base64. JPG, PNG ou WebP, até 10 MB. Entra no fim; a primeira foto do produto vira capa. Com "capa": true ela vai para a frente. Também aceita {"fotos": [ … ]} com várias.

Parâmetros

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/fotos" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"url":"https://meusite.com/fotos/coador.jpg","capa":false}'

Resposta

{
  "dados": {
    "id": "uuid",
    "ordem": 3,
    "capa": false,
    "url": "https://…"
  },
  "total_fotos": 4
}

Erros específicos

Reordenar fotos

PUT/v1/produtos/{produto}/fotos/ordem

permissão fotos:write

Manda a lista COMPLETA de ids na ordem nova; o primeiro vira capa.

Parâmetros

Exemplo

curl -X PUT "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/fotos/ordem" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"ids":["uuid-3","uuid-1","uuid-2"]}'

Resposta

{
  "ok": true
}

Erros específicos

Trocar a capa

POST/v1/produtos/{produto}/fotos/{foto}/capa

permissão fotos:write

Põe esta foto na frente (ordem 0); as outras andam uma casa.

Parâmetros

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/fotos/{foto}/capa" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "ok": true
}

Apagar foto

DELETE/v1/produtos/{produto}/fotos/{foto}

permissão fotos:write

Apaga a foto e o arquivo. Se era a capa, a próxima vira capa.

Parâmetros

Exemplo

curl -X DELETE "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/fotos/{foto}" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "ok": true,
  "total_fotos": 3
}

Listar vídeos

GET/v1/produtos/{produto}/videos

permissão produtos:read

Vídeos do produto (URL, capa, duração).

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/videos" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "ordem": 0,
      "url": "https://…/video.mp4",
      "capa_url": "https://…",
      "duracao_s": 18
    }
  ]
}

Listar códigos

GET/v1/produtos/{produto}/codigos-barras

permissão produtos:read

Todos os códigos do produto (EAN da unidade, DUN da caixa, código interno), com quantas unidades cada um representa.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/codigos-barras" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "codigo": "7890000000017",
      "simbologia": "EAN13",
      "unidades": 1,
      "principal": true
    },
    {
      "id": "uuid",
      "codigo": "17890000000014",
      "simbologia": "DUN14",
      "unidades": 12,
      "principal": false
    }
  ]
}

Adicionar código

POST/v1/produtos/{produto}/codigos-barras

permissão produtos:writeaceita Idempotency-Key

Liga mais um código ao produto. Código já usado por outro produto da empresa = 409.

Parâmetros

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/codigos-barras" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"codigo":"17890000000014","unidades":12,"apelido":"Caixa"}'

Erros específicos

Remover código

DELETE/v1/produtos/{produto}/codigos-barras/{codigo}

permissão produtos:write

Desliga o código do produto (o código principal do cadastro não sai por aqui: grave outro em codigo_barras).

Parâmetros

Exemplo

curl -X DELETE "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/codigos-barras/{codigo}" \
  -H "Authorization: Bearer $CHAVE"

Variações

GET/v1/produtos/{produto}/variacoes

permissão produtos:read

Variações (cor, tamanho…) com SKU, código de barras e preço diferencial.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/variacoes" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "atributo_tipo": "cor",
      "atributo_valor": "Azul",
      "sku": "CP-01-AZ",
      "codigo_barras": "789…",
      "preco_diferencial": 0
    }
  ]
}

Composição do kit

GET/v1/produtos/{produto}/composicao

permissão produtos:read

Se o produto é kit, quais produtos e quantidades ele leva.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/composicao" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "componente_id": "uuid",
      "componente_erp_id": 55,
      "nome": "Seda Brown",
      "quantidade": 2,
      "unidade": "UN"
    }
  ]
}

Embalagens

GET/v1/produtos/{produto}/embalagens

permissão produtos:read

Formas de venda/compra do produto (unidade, display, caixa) com o fator de conversão.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/embalagens" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "nome": "Caixa com 12",
      "fator_conversao": 12,
      "tipo": "caixa"
    }
  ]
}

Listar categorias

GET/v1/categorias

permissão produtos:read

Categorias com as subcategorias dentro.

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/categorias" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "nome": "Utilidades",
      "ordem": 1,
      "ativa": true,
      "subcategorias": [
        {
          "id": "uuid",
          "nome": "Cozinha"
        }
      ]
    }
  ]
}

Criar categoria

POST/v1/categorias

permissão produtos:writeaceita Idempotency-Key

Cria a categoria (nome repetido devolve a existente com 200).

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/categorias" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"nome":"Utilidades","descricao":"Casa e cozinha"}'

Criar subcategoria

POST/v1/categorias/{categoria}/subcategorias

permissão produtos:writeaceita Idempotency-Key

Cria a subcategoria dentro da categoria.

Parâmetros

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/categorias/{categoria}/subcategorias" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"nome":"Cozinha"}'

Preços do produto

GET/v1/produtos/{produto}/precos

permissão produtos:read

Preço de venda, preço por quantidade (atacado) e o preço em cada tabela de preço.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/precos" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "preco_venda": 13.19,
  "por_quantidade": [
    {
      "quantidade_minima": 12,
      "desconto_pct": 5,
      "preco_fixo": null
    }
  ],
  "tabelas": [
    {
      "tabela_id": "uuid",
      "nome": "Atacado",
      "preco": 11.9
    }
  ]
}

Tabelas de preço

GET/v1/tabelas-preco

permissão produtos:read

Tabelas de preço da empresa.

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/tabelas-preco" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "nome": "Atacado",
      "desconto_pct_padrao": 10,
      "ativo": true
    }
  ]
}

Itens da tabela

GET/v1/tabelas-preco/{tabela}/itens

permissão produtos:read?formato=csv

Preço de cada produto na tabela.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/tabelas-preco/{tabela}/itens" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "produto_id": "uuid",
      "erp_id": 1234,
      "referencia": "CP-01",
      "preco": 11.9
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 100,
    "total": 1,
    "total_paginas": 1
  }
}

Saldos de todos os produtos

GET/v1/estoque

permissão estoque:read?formato=csv

Um número por produto. vendavel = o que dá para vender, já na unidade de venda (o mesmo número que o app manda aos marketplaces): produto em caixa = caixas inteiras, cartela = só as lacradas, kit virtual = prontos + o que dá para montar; já desconta venda de fora ainda sem baixa e o que já foi prometido a cliente (venda que ficou sem estoque). saldo/reservado/disponivel = soma dos lotes, em unidade de estoque. É o que sistemas sem lote/local precisam. Para o detalhe por local e lote, use /estoque/{produto}. Veja "Cartela de fornecedor e kit virtual".

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/estoque" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "produto_id": "uuid",
      "erp_id": 1234,
      "referencia": "CP-01",
      "codigo_barras": "7890000000017",
      "saldo": 70,
      "reservado": 2,
      "disponivel": 68,
      "tipo_estoque": "simples",
      "vendavel": 5,
      "unidades_por_venda": 12,
      "vendido_fora_sem_baixa": 0,
      "proxima_validade": "2027-03-01",
      "atualizado_em": "…"
    },
    {
      "produto_id": "uuid",
      "erp_id": 1240,
      "referencia": "CAD-C12",
      "codigo_barras": null,
      "saldo": 12,
      "reservado": 0,
      "disponivel": 12,
      "tipo_estoque": "cartela",
      "vendavel": 1,
      "unidades_por_venda": 12,
      "cartelas_lacradas": 1,
      "soltas_da_cartela": 3,
      "vendido_fora_sem_baixa": 0
    },
    {
      "produto_id": "uuid",
      "erp_id": 1241,
      "referencia": "CAD-UN",
      "codigo_barras": null,
      "saldo": 0,
      "reservado": 0,
      "disponivel": 0,
      "tipo_estoque": "kit_virtual",
      "vendavel": 15,
      "unidades_por_venda": 1,
      "prontos": 0,
      "da_para_montar": 15,
      "vendido_fora_sem_baixa": 0
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 100,
    "total": 1,
    "total_paginas": 1
  }
}

Estoque detalhado do produto

GET/v1/estoque/{produto}

permissão estoque:read

Saldo total + vendável (como em /estoque) + quanto tem em cada local + cada lote (número do lote, validade, local, quantidade, caixas fechadas e unidades soltas). Lote sem local = aguardando endereçamento.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/estoque/sku:CP-01" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "produto_id": "uuid",
  "saldo": 70,
  "reservado": 2,
  "disponivel": 68,
  "tipo_estoque": "simples",
  "vendavel": 5,
  "unidades_por_venda": 12,
  "vendido_fora_sem_baixa": 0,
  "por_local": [
    {
      "local_id": "uuid",
      "local": "A-01-02",
      "quantidade": 60
    },
    {
      "local_id": null,
      "local": "Sem local (aguardando endereçar)",
      "quantidade": 10
    }
  ],
  "lotes": [
    {
      "lote_id": "uuid",
      "lote": "L2611",
      "validade": "2027-03-01",
      "local_id": "uuid",
      "local": "A-01-02",
      "quantidade": 60,
      "caixas_fechadas": 5,
      "unidades_soltas": 0,
      "unidades_por_caixa": 12
    }
  ]
}

Todos os lotes

GET/v1/estoque/lotes

permissão estoque:read?formato=csv

Lotes ativos de todos os produtos. Filtre por vencendo_ate para saber o que vence.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/estoque/lotes" \
  -H "Authorization: Bearer $CHAVE"

Movimentos de estoque

GET/v1/estoque/movimentos

permissão estoque:read?formato=csv

Histórico de entradas, saídas, transferências e ajustes de cada lote, com motivo e pedido, do mais antigo para o mais novo. Cartela aberta para vender kit virtual aparece como abertura_cartela (e fechamento_cartela quando volta lacrada no cancelamento). Para sincronizar, peça "desde" a data do último que você leu.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/estoque/movimentos" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "tipo": "saida",
      "quantidade": 2,
      "produto_erp_id": 1234,
      "lote_id": "uuid",
      "local_origem_id": "uuid",
      "local_destino_id": null,
      "pedido_id": "uuid",
      "motivo": "Venda",
      "origem_tipo": "pedido",
      "criado_em": "…",
      "estornada_em": null
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 100,
    "total": 1,
    "total_paginas": 1
  }
}

Dar entrada

POST/v1/estoque/entradas

permissão estoque:writeaceita Idempotency-Key

Soma estoque criando um lote. Local: o informado → o local onde o produto já está → o local padrão da empresa. No controle por lote a mercadoria nunca fica sem endereço: se nenhum desses existir, a entrada é recusada com estoque_sem_local (mande local_id, veja /locais). No modo simples o local não é exigido. Validade e lote são opcionais. Cartela de fornecedor entra só lacrada (múltiplo do tamanho da cartela, ou "unidade": "venda" com o número de cartelas); kit virtual e produto base não recebem entrada. Aceita uma entrada ou {"entradas": [ … ]} (até 200).

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/estoque/entradas" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"entradas":[{"produto":"sku:CP-01","quantidade":24,"validade":"2027-03-01","lote":"L2611","custo_unitario":6.5}]}'

Resposta

{
  "ok": 1,
  "total": 1,
  "resultados": [
    {
      "ok": true,
      "lote_id": "uuid",
      "local_id": "uuid",
      "sem_local": false,
      "quantidade_entrada": 24,
      "estoque_total": 94
    }
  ]
}

Erros específicos

Dar saída

POST/v1/estoque/saidas

permissão estoque:ajustaraceita Idempotency-Key

Tira estoque pela validade mais próxima (FEFO), de qualquer local, ou só do local informado. Falta saldo = recusa inteira (nunca tira pela metade). Cada lote mexido fica no histórico com o nome da integração. Kit virtual, produto base e cartela de fornecedor são recusados: a venda deles entra como pedido, e o app decide qual cartela abrir. Com "previa": true mostra o que faria sem mexer.

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/estoque/saidas" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"produto":"ean:7890000000017","quantidade":3,"motivo":"Venda no balcão do sistema X"}'

Resposta

{
  "ok": true,
  "aplicado": true,
  "saldo_antes": 70,
  "saldo_depois": 67,
  "lotes": [
    {
      "lote_id": "uuid",
      "validade": "2027-03-01",
      "de": 60,
      "para": 57
    }
  ]
}

Erros específicos

Acertar o saldo (valor absoluto)

PUT/v1/estoque/{produto}/saldo

permissão estoque:ajustaraceita Idempotency-Key

Para sistemas que só conhecem "quanto tem". Calcula a diferença: se subiu, cria um lote (local como na entrada); se desceu, tira só a diferença pela validade mais próxima — os outros locais e lotes ficam como estão. Kit virtual, produto base e cartela de fornecedor são recusados. Recomendado mandar "previa": true primeiro.

Parâmetros

Corpo (JSON)

Exemplo

curl -X PUT "https://app.erpconnectmobile.com.br/api/v1/estoque/sku:CP-01/saldo" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"quantidade":65,"motivo":"Contagem do sistema X","previa":true}'

Resposta

{
  "ok": true,
  "aplicado": false,
  "saldo_antes": 70,
  "saldo_depois": 65,
  "lotes": [
    {
      "lote_id": "uuid",
      "de": 60,
      "para": 55
    }
  ]
}

Balanço (vários saldos)

POST/v1/estoque/balanco

permissão estoque:ajustaraceita Idempotency-Key

Mesmo que acertar o saldo, para até 200 produtos. Cada item tem resultado próprio.

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/estoque/balanco" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"previa":true,"itens":[{"produto":"sku:CP-01","quantidade":65},{"produto":"sku:CP-02","quantidade":0}]}'

Locais de estoque

GET/v1/locais

permissão estoque:read

Endereços do depósito (zona, corredor, coluna, linha) e o local padrão da empresa.

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/locais" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "local_padrao_id": "uuid",
  "dados": [
    {
      "id": "uuid",
      "nome": "A-01-02",
      "zona": "A",
      "corredor": "01",
      "coluna": "02",
      "linha": null,
      "codigo_barras": "LOC-A0102",
      "ativo": true
    }
  ]
}

Listar clientes

GET/v1/clientes

permissão clientes:read?formato=csv

Clientes da empresa.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/clientes" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "razao_social": "Mercado Bom Preço Ltda",
      "fantasia": "Bom Preço",
      "cnpj_cpf": "12345678000190",
      "inscricao_estadual": "110042490114",
      "email": "compras@bompreco.com.br",
      "telefone": "11999990000",
      "cep": "01001000",
      "logradouro": "Praça da Sé",
      "numero": "100",
      "bairro": "Sé",
      "cidade": "São Paulo",
      "uf": "SP",
      "codigo_municipio": "3550308",
      "limite_credito": 5000,
      "ativo": true
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 100,
    "total": 1,
    "total_paginas": 1
  }
}

Ler cliente

GET/v1/clientes/{cliente}

permissão clientes:read

Pelo id ou por doc:CNPJ.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/clientes/doc:12345678000190" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": {
    "id": "uuid",
    "razao_social": "Mercado Bom Preço Ltda",
    "fantasia": "Bom Preço",
    "cnpj_cpf": "12345678000190",
    "inscricao_estadual": "110042490114",
    "email": "compras@bompreco.com.br",
    "telefone": "11999990000",
    "cep": "01001000",
    "logradouro": "Praça da Sé",
    "numero": "100",
    "bairro": "Sé",
    "cidade": "São Paulo",
    "uf": "SP",
    "codigo_municipio": "3550308",
    "limite_credito": 5000,
    "ativo": true
  }
}

Erros específicos

Criar cliente

POST/v1/clientes

permissão clientes:writeaceita Idempotency-Key

Documento já cadastrado = 409 com o id existente.

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/clientes" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"razao_social":"Mercado Bom Preço Ltda","cnpj_cpf":"12345678000190","email":"compras@bompreco.com.br","telefone":"11999990000","cep":"01001000","uf":"SP","cidade":"São Paulo"}'

Erros específicos

Alterar cliente

PATCH/v1/clientes/{cliente}

permissão clientes:writeaceita Idempotency-Key

Muda só os campos enviados.

Parâmetros

Exemplo

curl -X PATCH "https://app.erpconnectmobile.com.br/api/v1/clientes/doc:12345678000190" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"telefone":"11988887777"}'

Listar fornecedores

GET/v1/fornecedores

permissão fornecedores:read?formato=csv

Fornecedores da empresa.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/fornecedores" \
  -H "Authorization: Bearer $CHAVE"

Ler fornecedor

GET/v1/fornecedores/{fornecedor}

permissão fornecedores:read

Pelo id ou doc:CNPJ.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/fornecedores/doc:11222333000181" \
  -H "Authorization: Bearer $CHAVE"

Criar fornecedor

POST/v1/fornecedores

permissão fornecedores:writeaceita Idempotency-Key

Documento já cadastrado = 409.

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/fornecedores" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"razao_social":"Distribuidora Exemplo Ltda","cnpj_cpf":"11222333000181","telefone":"1133334444"}'

Alterar fornecedor

PATCH/v1/fornecedores/{fornecedor}

permissão fornecedores:writeaceita Idempotency-Key

Muda só os campos enviados.

Parâmetros

Exemplo

curl -X PATCH "https://app.erpconnectmobile.com.br/api/v1/fornecedores/doc:11222333000181" \
  -H "Authorization: Bearer $CHAVE"

Listar pedidos

GET/v1/pedidos

permissão pedidos:read?formato=csv

Pedidos de todos os canais (app, loja, site, marketplaces, API).

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/pedidos" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "numero": 812,
      "id_externo": "ERP-55821",
      "status": "faturado",
      "canal": "app",
      "valor_total": 129.9,
      "valor_frete": 0,
      "total_itens": 2,
      "cliente": {
        "id": "uuid",
        "nome": "Bom Preço",
        "documento": "12345678000190"
      },
      "created_at": "2026-11-07T10:00:00-03:00",
      "itens": [
        {
          "produto_id": "uuid",
          "erp_id": 1234,
          "referencia": "CP-01",
          "nome": "Coador de pano nº 3",
          "quantidade": 10,
          "preco_unitario": 12.99,
          "valor_total": 129.9
        }
      ]
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 100,
    "total": 1,
    "total_paginas": 1
  }
}

Ler pedido

GET/v1/pedidos/{pedido}

permissão pedidos:read

Pedido completo com itens, cliente, pagamento, frete e notas. Pelo id, pelo número (n:812) ou pelo seu id externo (ext:ERP-55821).

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/pedidos/n:812" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": {
    "id": "uuid",
    "numero": 812,
    "id_externo": "ERP-55821",
    "status": "faturado",
    "canal": "app",
    "valor_total": 129.9,
    "valor_frete": 0,
    "total_itens": 2,
    "cliente": {
      "id": "uuid",
      "nome": "Bom Preço",
      "documento": "12345678000190"
    },
    "created_at": "2026-11-07T10:00:00-03:00",
    "itens": [
      {
        "produto_id": "uuid",
        "erp_id": 1234,
        "referencia": "CP-01",
        "nome": "Coador de pano nº 3",
        "quantidade": 10,
        "preco_unitario": 12.99,
        "valor_total": 129.9
      }
    ]
  }
}

Erros específicos

Criar pedido

POST/v1/pedidos

permissão pedidos:writeaceita Idempotency-Key

O pedido entra em Processados como venda de outro canal, e o app dá a baixa do estoque pelo motor oficial (lote, cartela, kit). "id_externo" é obrigatório e único: reenviar o mesmo devolve o pedido já criado (nunca duplica). Todo item precisa achar o produto; se um não achar, o pedido inteiro é recusado e a resposta diz qual.

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/pedidos" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"id_externo":"ERP-55821","cliente":"doc:12345678000190","itens":[{"produto":"sku:CP-01","quantidade":10,"preco_unitario":12.99}],"observacoes":"Entregar pela manhã"}'

Resposta

{
  "dados": {
    "id": "uuid",
    "numero": 813,
    "id_externo": "ERP-55821",
    "status": "finalizado",
    "valor_total": 129.9
  },
  "criado": true
}

Erros específicos

Cancelar pedido criado pela API

POST/v1/pedidos/{pedido}/cancelar

permissão pedidos:write

Só cancela pedido criado pela API e que o app ainda não baixou do estoque. Os outros se cancelam pelo app (o app pergunta o que fazer com cartela e kit).

Parâmetros

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/pedidos/n:812/cancelar" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"motivo":"Cliente desistiu"}'

Erros específicos

Histórico do pedido

GET/v1/pedidos/{pedido}/historico

permissão pedidos:read

Cada mudança de status com data e motivo.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/pedidos/n:812/historico" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "status_anterior": "confirmado",
      "status_novo": "faturado",
      "motivo": null,
      "criado_em": "…"
    }
  ]
}

Cupom do pedido

GET/v1/pedidos/{pedido}/cupom

permissão pedidos:read?formato=txt?formato=html

Comprovante do pedido (não fiscal) pronto para imprimir: txt com 48 colunas (impressora térmica 80 mm; ?colunas=32 para 58 mm), html (A4 ou térmica pelo navegador) ou json com as linhas.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/pedidos/n:812/cupom" \
  -H "Authorization: Bearer $CHAVE"

Frete e rastreio

GET/v1/pedidos/{pedido}/envio

permissão pedidos:read

Transportadora, serviço, valor, prazo, código de rastreio, link de rastreio e o link da etiqueta de envio (PDF) quando já foi gerada.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/pedidos/n:812/envio" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "provedor": "melhor_envio",
      "transportadora": "Correios",
      "servico": "PAC",
      "valor_frete": 22.4,
      "prazo_dias": 5,
      "status": "postado",
      "codigo_rastreio": "AA123456789BR",
      "rastreio_url": "https://…",
      "etiqueta_url": "https://…",
      "volumes": 1,
      "peso_kg": 0.4
    }
  ]
}

Etiqueta do produto

GET/v1/produtos/{produto}/etiqueta

permissão produtos:read?formato=txt

Dados para imprimir a etiqueta de gôndola/produto: nome, preço, código de barras. Em ZPL (impressora Zebra/Elgin/Argox) com ?formato=zpl, ou json.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/produtos/sku:CP-01/etiqueta" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "nome": "Coador de pano nº 3",
  "referencia": "CP-01",
  "preco_venda": 13.19,
  "codigo_barras": "7890000000017",
  "simbologia": "EAN13",
  "unidade": "UN"
}

Etiquetas salvas

GET/v1/etiquetas

permissão produtos:read

Modelos de etiqueta feitos no app (código, título, tamanho, quantas vezes impressa).

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/etiquetas" \
  -H "Authorization: Bearer $CHAVE"

Listar notas

GET/v1/notas

permissão notas:read?formato=csv

NF-e (55) e NFC-e (65) emitidas.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/notas" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "pedido_id": "uuid",
      "modelo": "55",
      "serie": 1,
      "numero": 43,
      "chave": "3526…",
      "status": "autorizada",
      "valor_total": 129.9,
      "data_emissao": "…",
      "destinatario": {
        "nome": "Bom Preço",
        "documento": "12345678000190"
      }
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 100,
    "total": 1,
    "total_paginas": 1
  }
}

Ler nota

GET/v1/notas/{nota}

permissão notas:read

Pelo id ou pela chave (chave:44 dígitos).

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/notas/chave:35261154815379000117550010000000431000000431" \
  -H "Authorization: Bearer $CHAVE"

XML autorizado

GET/v1/notas/{nota}/xml

permissão notas:read?formato=xml

O XML da nota com o protocolo da SEFAZ (nfeProc), pronto para mandar ao contador ou ao marketplace.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/notas/chave:35261154815379000117550010000000431000000431/xml" \
  -H "Authorization: Bearer $CHAVE"

Erros específicos

Notas do pedido

GET/v1/pedidos/{pedido}/notas

permissão notas:read

Notas emitidas para o pedido.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/pedidos/n:812/notas" \
  -H "Authorization: Bearer $CHAVE"

Contas a receber

GET/v1/contas-receber

permissão financeiro:read?formato=csv

Parcelas a receber com vencimento, valor em aberto, pago, forma prevista e boleto (linha digitável).

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/contas-receber" \
  -H "Authorization: Bearer $CHAVE"

Vendas do caixa

GET/v1/pdv/vendas

permissão pdv:read?formato=csv

Vendas do PDV com itens, pagamentos e o cupom de desconto usado (cupom_regra_id).

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/pdv/vendas" \
  -H "Authorization: Bearer $CHAVE"

Cardápio

GET/v1/cardapio

permissão pdv:read

Seções e itens do cardápio com preço, foto e disponibilidade (estoque > 0). Mesmo formato de "item com complementos" do padrão Open Delivery (Abrasel).

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/cardapio" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": "uuid",
      "nome": "Lanches",
      "ordem": 1,
      "itens": [
        {
          "id": "uuid",
          "produto_id": "uuid",
          "nome": "X-Burguer",
          "preco": 25,
          "disponivel": true,
          "foto_url": "https://…",
          "complementos": [
            {
              "produto_erp_id": 99,
              "texto": "Bacon"
            }
          ]
        }
      ]
    }
  ]
}

Carga da balança

GET/v1/balanca/itens

permissão produtos:read?formato=toledo?formato=filizola

Itens com código de balança (PLU), preço por kg ou por unidade. ?formato=toledo devolve o arquivo ITENSMGV.TXT (Toledo MGV), ?formato=filizola o CADTXT.TXT; json para outros programas.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/balanca/itens" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "codigo_balanca": "01234",
      "nome": "Queijo minas",
      "unidade": "KG",
      "preco": 39.9,
      "por_peso": true,
      "validade_dias": null
    }
  ]
}

Feed de eventos

GET/v1/eventos

permissão eventos:read

Para quem não pode receber aviso automático: leia de tempos em tempos pedindo só o que veio depois do último id lido. Guardamos 30 dias.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/eventos" \
  -H "Authorization: Bearer $CHAVE"

Resposta

{
  "dados": [
    {
      "id": 1042,
      "tipo": "estoque.alterado",
      "recurso_id": "uuid",
      "criado_em": "…",
      "dados": {
        "saldo": 68
      }
    }
  ],
  "ultimo_id": 1042,
  "tem_mais": false
}

Listar avisos

GET/v1/webhooks

permissão webhooks:write

Endereços cadastrados (o segredo não volta).

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer $CHAVE"

Cadastrar aviso

POST/v1/webhooks

permissão webhooks:writeaceita Idempotency-Key

Cadastra um endereço https que recebe um POST a cada evento escolhido ("*" = todos, "pedido.*" = todos de pedido). O segredo de assinatura volta UMA vez: guarde.

Corpo (JSON)

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-pedido-55821" \
  -d '{"url":"https://meuerp.com.br/webhooks/erpconnect","eventos":["estoque.alterado","pedido.*"]}'

Resposta

{
  "dados": {
    "id": "uuid",
    "segredo": "whsec_…",
    "eventos": [
      "estoque.alterado",
      "pedido.*"
    ]
  }
}

Erros específicos

Remover aviso

DELETE/v1/webhooks/{webhook}

permissão webhooks:write

Para de mandar para o endereço.

Parâmetros

Exemplo

curl -X DELETE "https://app.erpconnectmobile.com.br/api/v1/webhooks/{webhook}" \
  -H "Authorization: Bearer $CHAVE"

Testar aviso

POST/v1/webhooks/{webhook}/teste

permissão webhooks:write

Manda um evento teste.ping no próximo minuto.

Parâmetros

Exemplo

curl -X POST "https://app.erpconnectmobile.com.br/api/v1/webhooks/{webhook}/teste" \
  -H "Authorization: Bearer $CHAVE"

Entregas do aviso

GET/v1/webhooks/{webhook}/entregas

permissão webhooks:write

Últimas 100 entregas: evento, tentativa, código HTTP que seu servidor respondeu e o erro.

Parâmetros

Exemplo

curl -X GET "https://app.erpconnectmobile.com.br/api/v1/webhooks/{webhook}/entregas" \
  -H "Authorization: Bearer $CHAVE"