Integração
Produtos
O que o seu ERP precisa expor para que o Amplia One leia o catálogo de produtos: as views, as colunas de cada uma, os tipos, as regras e exemplos preenchidos dos três casos que existem — produto simples, produto com embalagem e produto com grade.
O que pedimos ao ERP
As quatro views que o ERP precisa expor para o Amplia One ler o catálogo.
Nem todo ERP quer escrever no Amplia One. Muitos preferem apenas expor os dados e deixar que a gente busque. Para esse caminho, pedimos quatro views ligadas entre si pelo código do produto no ERP — duas obrigatórias, duas conforme o que o cliente vende.
| View | Uma linha por | Quando |
|---|---|---|
| vw_amplia_produtos | produto | Obrigatória |
| vw_amplia_embalagens | forma de venda (unidade, caixa, fardo) | Obrigatória |
| vw_amplia_variacoes | combinação de tamanho, cor etc. | Só se houver grade |
| vw_amplia_imagens | imagem | Só se houver foto |
Os nomes são sugestão. Se a convenção do ERP for outra, o que importa são as colunas — basta nos dizer os nomes reais.
Como acessamos
- Endpoint HTTP (preferido)
- Um GET por view devolvendo JSON, com a autenticação que o ERP já usa. Precisamos de atualizado_desde e de paginação.
- Acesso direto ao banco
- Um usuário somente leitura com permissão apenas nas quatro views, mais endereço, porta, base, credenciais e liberação de IP.
Colunas de cada view
O contrato campo a campo, com tipo e obrigatoriedade.
vw_amplia_produtos — uma linha por produto
| Coluna | Tipo | Obrig. | O que é |
|---|---|---|---|
| codigo_erp | VARCHAR(40) | Sim | O código do produto no ERP. É a chave de tudo e precisa ser estável. |
| nome | VARCHAR(200) | Sim | Descrição comercial. |
| marca | VARCHAR(80) | Sim | Nome da marca por extenso, não o código dela. |
| departamento | VARCHAR(80) | Sim | Nível mais alto da classificação. |
| grupo | VARCHAR(80) | Sim | Nível intermediário. |
| subgrupo | VARCHAR(80) | Sim | Nível mais baixo. É nele que o produto fica. |
| unidade | VARCHAR(4) | Sim | Sigla da MENOR unidade vendida: UN, KG, L, PR. |
| situacao | VARCHAR(15) | Sim | ativo, inativo ou descontinuado. |
| tem_grade | BOOLEAN | Sim | Verdadeiro quando o produto é vendido em variações. |
| atualizado_em | TIMESTAMP TZ | Sim | Última alteração da linha. É o que permite ler só o que mudou. |
| referencia | VARCHAR(60) | Não | Código do fabricante. |
| descricao | VARCHAR(1000) | Não | Texto livre. |
| ncm / cest | VARCHAR | Não | Só dígitos. |
| peso_liquido / peso_bruto | NUMERIC(14,4) | Não | Em quilogramas, da unidade base. |
| preco_venda | NUMERIC(14,4) | Não | Preço da unidade base. Um só para a conta inteira. |
| custo | NUMERIC(14,4) | Não | Custo da unidade base, da empresa em cnpj_empresa. |
| cnpj_empresa | VARCHAR(14) | Não | De qual empresa é o custo. Obrigatório se vier custo. |
vw_amplia_embalagens — uma linha por forma de venda
| Coluna | Tipo | Obrig. | O que é |
|---|---|---|---|
| codigo_erp | VARCHAR(40) | Sim | O produto a que a embalagem pertence. |
| unidade | VARCHAR(4) | Sim | Sigla do agrupamento: CX, FD, PC. Na linha da base, repete a do produto. |
| quantidade | INTEGER | Sim | Quantas unidades base cabem. 1 na base; a partir de 2 nas demais. |
| base | BOOLEAN | Sim | Verdadeiro só na unidade base. Uma por produto. |
| atualizado_em | TIMESTAMP TZ | Sim | Última alteração da linha. |
| codigo_barras | VARCHAR(14) | Não | EAN ou DUN desta embalagem. Só números. |
| preco_venda | NUMERIC(14,4) | Não | Preço da embalagem fechada. Nulo quando é o proporcional. |
| venda_padrao | BOOLEAN | Não | A forma em que o produto costuma ser vendido. No máximo uma. |
| peso_bruto | NUMERIC(14,4) | Não | Peso da embalagem fechada. |
vw_amplia_variacoes — só para produto com grade
| Coluna | Tipo | Obrig. | O que é |
|---|---|---|---|
| codigo_erp | VARCHAR(40) | Sim | O produto a que a variação pertence. |
| eixo_1 / valor_1 | VARCHAR(40) | Sim | Primeiro eixo e seu valor: Tamanho / 37/38. |
| atualizado_em | TIMESTAMP TZ | Sim | Última alteração da linha. |
| eixo_2 / valor_2 | VARCHAR(40) | Não | Segundo eixo e seu valor: Cor / PRETO. |
| codigo_barras | VARCHAR(14) | Não | EAN desta variação. Sem ele, geramos um. |
| preco_venda | NUMERIC(14,4) | Não | Só quando a variação foge do preço do produto. |
| custo | NUMERIC(14,4) | Não | Só quando a variação foge do custo do produto. |
| situacao | VARCHAR(15) | Não | Situação própria. Nula segue a do produto. |
vw_amplia_imagens
| Coluna | Tipo | Obrig. | O que é |
|---|---|---|---|
| codigo_erp | VARCHAR(40) | Sim | O produto a que a imagem pertence. |
| url | VARCHAR(500) | Sim | Endereço público da imagem, sem login. Até 10 MB. |
| atualizado_em | TIMESTAMP TZ | Sim | Última alteração da linha. |
| cor | VARCHAR(40) | Não | Prende a foto a uma cor da grade. |
| principal | BOOLEAN | Não | Foto de capa. Vale dentro da própria cor. |
| ordem | INTEGER | Não | Ordem de exibição, começando em 0. |
Regras e sincronização
O que reprova carga e como a leitura incremental funciona.
| Assunto | Regra |
|---|---|
| Código de barras | Só números, sem pontuação. Leitor não lê letra. |
| Texto | Não precisa vir em maiúscula — normalizamos. Sem código embutido no nome. |
| Números | Ponto decimal, sem separador de milhar, sem símbolo de moeda. |
| Nulo | Campo sem valor vem nulo, não vazio nem zero. Preço zero é preço zero. |
| Datas | ISO 8601 com fuso: 2026-08-27T14:32:10-03:00. |
| Grade e embalagem | Não convivem. Produto nas duas views é recusado. |
Como a sincronização roda
- Guardamos o instante da última leitura bem-sucedida.
- Pedimos vw_amplia_produtos com atualizado_desde, página a página.
- Para os produtos que vieram, pedimos as linhas das outras três views.
- Importamos produto por produto — um recusado não impede os outros.
- Devolvemos um relatório do que entrou e do que foi recusado, com o motivo.
Clientes e fornecedores
Uma view a mais, quando o cliente quiser que a gente leia o cadastro de pessoas.
O cadastro de pessoas segue o mesmo caminho do catálogo: ou o ERP escreve no Amplia One pela API, ou expõe uma view e nós buscamos. Aqui é uma view só, porque cliente e fornecedor são o mesmo cadastro — o que muda são dois campos de papel.
vw_amplia_pessoas — uma linha por documento
| Coluna | Tipo | Obrig. | O que é |
|---|---|---|---|
| documento | VARCHAR(14) | Sim | CNPJ ou CPF, só dígitos. É a chave — e é ela que faz dois ERPs convergirem no mesmo cadastro. |
| nome | VARCHAR(200) | Sim | Razão social ou nome completo. |
| cliente | BOOLEAN | Sim | Verdadeiro quando a pessoa compra de você. |
| fornecedor | BOOLEAN | Sim | Verdadeiro quando a pessoa vende para você. Os dois podem ser verdadeiros. |
| situacao | VARCHAR(15) | Sim | ativo, inativo ou bloqueado. |
| atualizado_em | TIMESTAMP TZ | Sim | Última alteração da linha. |
| codigo_erp | VARCHAR(40) | Não | O código dela no ERP. Guardamos como referência, não como identidade. |
| nome_fantasia | VARCHAR(200) | Não | Nome fantasia ou apelido. |
| inscricao_estadual | VARCHAR(20) | Não | Nulo quando isento. |
| isento_ie | BOOLEAN | Não | Isento de inscrição estadual. |
| inscricao_municipal / suframa | VARCHAR(20) | Não | Quando houver. |
| nascimento | DATE | Não | Só para CPF. |
| logradouro / numero / complemento | VARCHAR | Não | Endereço, em colunas separadas. |
| bairro / cidade / uf / cep | VARCHAR | Não | UF com 2 letras; CEP só dígitos. |
| codigo_ibge | VARCHAR(7) | Não | Código do município. Evita o município ambíguo entre estados. |
| telefone / telefone2 | VARCHAR(11) | Não | Só dígitos, com DDD. |
| VARCHAR(160) | Não | Um endereço por linha. | |
| observacoes | VARCHAR(1000) | Não | Texto livre. |
As regras da seção anterior valem igual: nulo é nulo, datas em ISO 8601 com fuso, e pessoa que sai do cadastro muda de situacao em vez de desaparecer da view.