Guia para clientes e desenvolvedores · E001

Sua operação comercial.
Conectada ao SGDAT.

Integre clientes, condições comerciais, pedidos e pós-venda em uma jornada documentada para o seu sistema.

A E001 permite que o backend de um parceiro consulte informações autorizadas e envie operações para o SGDAT. Este guia cobre as 12 operações disponíveis e explica como combiná-las.

Integra.com · Digital Sistemas
Edição de 9 de novembro de 2026 · Exemplos fictícios
Para PDF, use Imprimir → Salvar como PDF, em A4, sem cabeçalhos e rodapés automáticos. Os schemas completos permanecem no Swagger da instalação.
01 · Valor e escopo

Uma jornada comercial entre sistemas

Cadastro conectado

Receba interessados no seu sistema e encaminhe pré-cadastros para complementação no SGDAT.

Condições do negócio

Ofereça produtos, planos e preços disponíveis para o cliente e a parceria.

Pós-venda integrado

Acompanhe pedidos, consulte títulos em aberto e obtenha XMLs das notas vinculadas ao pedido.

Cliente → Plano → Catálogo → Captura → Acompanhamento → Pós-venda

Portais comerciais, CRMs e aplicações de parceiros podem usar essa jornada. IA é opcional. O desenvolvimento da aplicação consumidora e a liberação das operações devem ser alinhados no projeto de integração.

A captura de pedido não aprova crédito nem reserva estoque. A conclusão cadastral e o processamento operacional continuam no SGDAT. As consultas não concedem permissões adicionais: empresa, cliente, vendedor e parceria precisam estar no escopo autorizado.

Para indicadores, histórico analítico e resumos por dimensão, consulte o guia Analytics A001–A004. A E001 não substitui essas operações.

02 · Acesso e convenções

Prepare o backend da integração

Obtenha a URL HTTPS, credenciais, identificador da parceria e ambiente de homologação com a implantação. Use POST /api/Auth/login:

{"usuario":"USUARIO_DA_INTEGRACAO","senha":"SENHA_DA_INTEGRACAO"}

A resposta de sucesso contém token. Envie Authorization: Bearer JWT nas próximas chamadas. O login de um usuário E001 verifica a autorização da parceria. O comprador não acessa a API diretamente: o backend do parceiro identifica o cliente autorizado.

O prefixo é /api/E001/{parceiro}. O valor da URL deve corresponder à parceria autenticada. Não escolha outro parceiro para consultar dados. Confirme o nome na implantação: pré-cadastros aceitam até 40 caracteres; novas capturas de pedidos, até 42; consultas de pedidos preservam compatibilidade com nomes históricos de até 50.

Primeira chamada com cURL

Defina INTEGRA_URL sem barra final, INTEGRA_TOKEN e INTEGRA_PARCEIRO no ambiente seguro de execução:

curl --request POST \
  "$INTEGRA_URL/api/E001/$INTEGRA_PARCEIRO/clientes/consultar?page=1&size=50" \
  --header "Authorization: Bearer $INTEGRA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"codigoEmpresa":1,"codigosClientes":[19]}'
03 · Leitura das respostas

Listas, objetos e arquivos

Clientes, planos, produtos, bairros, cidades, listagem de pedidos e contas a receber usam page/size na query. Página inicial 1, tamanho padrão 50. Ausência, nulo ou zero utiliza o padrão; negativos são recusados. Não use pageSize como parâmetro de entrada E001.

{
  "dados": [],
  "number": 1,
  "totalPages": 1,
  "pageSize": 50,
  "numberOfElements": 0,
  "totalElements": 0,
  "last": true,
  "first": true,
  "empty": true
}

pageSize é capacidade; numberOfElements é o número efetivo de registros. Conjunto vazio mantém uma página. Incremente page até last: true, mantendo filtros e contexto. Não presuma que páginas consultadas em momentos distintos formam um snapshot: a base pode mudar.

Operação sem esse envelopeFormato de sucesso
Receber pré-cadastroObjeto de situação cadastral.
Consultar pré-cadastrosArray de situações; até 100 documentos por requisição.
Receber pedidoObjeto de captura com protocolo e todas as linhas.
Consultar pedido individualObjeto de situação atual e itens.
XML da NF-eArquivo ZIP binário, sem JSON.
04 · Localidades

Consulte referências antes de cadastrar

POST bairros/consultar

/api/E001/{parceiro}/bairros/consultar?page=1&size=50

{"nome":"centro"}

Retorna codigoBairro e nome em cada elemento de dados.

POST cidades/consultar

/api/E001/{parceiro}/cidades/consultar?page=1&size=50

{"nome":"paulo","uf":"SP"}

Retorna codigoCidade, nome, uf e codigoIbge. Nome é trecho literal, até 60 caracteres, sem distinguir maiúsculas. UF é opcional e validada. Corpo ausente ou {} consulta todo o cadastro por páginas. Ambas ordenam por nome e código.

Envie os códigos retornados no endereço do pré-cadastro. Cada código tem precedência independente sobre os respectivos textos: cidade sobre cidade/UF, bairro sobre bairro. Código inexistente gera 400, sem recorrer ao nome.

05 · Entrada de clientes

Pré-cadastrar e acompanhar a análise

POST clientes/pre-cadastros

/api/E001/{parceiro}/clientes/pre-cadastros, sem paginação, corpo até 32 KiB. Obrigatórios: CPF/CNPJ válido e nome/razão social.

{
  "cpfCnpj": "529.982.247-25",
  "nomeRazaoSocial": "Pessoa Exemplo",
  "email": "cadastro@example.com",
  "telefone": "+55 (11) 99999-1234",
  "codigoVendedor": 7
}

Documento de exemplo para homologação; não é uma instrução para criar um cadastro em produção. CPF/CNPJ são textos e aceitam máscara usual. A validação de documento não consulta a situação fiscal externa.

Campos opcionaisRegras de uso
nomeFantasia, inscricaoEstadual, rg, email, telefone, telefoneAlternativoNome/fantasia até 60 caracteres; IE/RG até 17; e-mail até 200. Telefones brasileiros com DDD. RG não substitui IE.
codigoVendedorPrecisa existir e estar autorizado. Com um único vendedor no escopo, pode ser resolvido quando omitido; com vários, deve ser escolhido.
limiteCreditoDecimal não negativo; omitido grava zero. Não representa aprovação de compra.
dataConsultaCredito, orgaoConsultaCreditoInformar juntos. Data sem horário e órgão até 20 caracteres.
dataAberturaEmpresa, sociosSomente pessoa jurídica. Abertura não pode ser futura. Sócio exige nome e CPF válido; não repetir CPF no body.
observacoes, latitude, longitudeObservações até 1.500 caracteres; latitude de -90 a 90, longitude de -180 a 180; zero é válido.
enderecologradouro, numero, complemento, codigoBairro, codigoCidade, bairro, cidade, uf e cep. Complemento exige logradouro; sem código, cidade exige UF.

Endereço: logradouro/complemento até 60 caracteres, número até 10. Para cidade e bairro por texto, limite de 60 bytes UTF-8 após normalização; prefira códigos. Na cópia de cobrança há limite de 20 bytes para o nome do bairro. Não trunque nomes para contornar validações.

Cada sócio pode incluir rg, orgaoEmissorRg, ufRg, endereco, bairro, cidade, uf, cep, observacoes, percentualParticipacao, valorParticipacao, cargo e dataNascimento. Cidade/UF devem vir juntas; percentual entre 0 e 100, valor não negativo e nascimento não futuro. Consulte limites individuais no Swagger.

Sucesso novo: HTTP 201, por exemplo:

{
  "cpfCnpj": "52998224725",
  "codigoCliente": "000020",
  "statusCadastro": -5,
  "situacao": "AguardandoComplementacao",
  "cadastroConcluido": false,
  "criadoAgora": true,
  "mensagem": "Pré-cadastro recebido; aguardando complementação no SGDAT."
}

O mesmo documento já existente retorna 200, criadoAgora: false e situação atual, sem atualizar seus dados. Documento ambíguo gera 409. Não envie status ou código de cliente no body; campos desconhecidos são rejeitados.

POST clientes/pre-cadastros/consultar

/api/E001/{parceiro}/clientes/pre-cadastros/consultar

{"documentos":["529.982.247-25","11.222.333/0001-81"]}

Aceita de 1 a 100 documentos, normaliza e elimina repetições. Retorna um array de situações, sem paginação.

SituaçãoInterpretação
AguardandoComplementacao (-5)Pré-cadastro recebido; completar no SGDAT.
Concluido (0 a 7)Cadastro concluído; demais regras comerciais continuam aplicáveis.
Bloqueado (8)Cadastro concluído, mas bloqueado. Liberação cabe ao processo financeiro.
EmAnalise / SituacaoIndefinidaOutros status / status ausente; não considerar concluído.
NaoEncontradoInexistente ou fora do escopo; não divulga código/status.

Em contenção, pode retornar 503 com Retry-After: 2. Após perda de resposta ou falha de confirmação, consulte a situação antes de concluir que não houve cadastro.

06 · Clientes

Identifique o contexto comercial

POST /api/E001/{parceiro}/clientes/consultar?page=1&size=50

{"codigoEmpresa":1,"codigosClientes":[19,123]}

Todos os filtros são opcionais. Use codigosClientes ou cnpjs, sem combinar as duas listas. Para pessoa física, use o código. Sem filtros, retorna clientes autorizados por páginas. Código/CNPJ de empresa podem ser usados; sem ambos, utiliza a empresa ativa configurada.

Cada cliente informa identificação, cidade/UF, statusCadastro, bloqueado, limiteCredito, creditoUtilizado, creditoDisponivel, quantidadeTitulosEmAberto, valorMinimoPedido, dataUltimaConsultaCredito, codigosRepresentantes e planosDeVenda.

Crédito é global. O utilizado soma saldos abertos do cliente em todas as empresas da base, inclusive fora do recorte de empresas do usuário, publicando somente o agregado. Disponível pode ser negativo; limite nulo mantém disponível nulo. O resultado não inclui reserva de pedidos nem constitui aprovação de crédito.

bloqueado representa o status específico de bloqueio: false não autoriza automaticamente comprar. Clientes bloqueados continuam visíveis. A consulta não executa nova consulta externa de crédito.

codigosRepresentantes contém as opções autorizadas. Se houver representante fixo configurado na parceria, apenas ele é aceito. Lista vazia impede nova captura até ajuste cadastral/configuração. Use uma opção da lista no campo obrigatório codigoRepresentante do pedido.

planosDeVenda contém codigo, nome, condicaoEspecial e padrao. A lista expressa as opções elegíveis; pode estar vazia. Não há uma flag pública separada de permissão de escolha.

07 · Planos de venda

Respeite as condições permitidas ao cliente

POST /api/E001/{parceiro}/planos-de-venda/consultar?page=1&size=50

{"codigoEmpresa":1,"codigoCliente":19}

Cliente é obrigatório, por codigoCliente ou cnpjCliente. Empresa é opcional, por código ou CNPJ; ausência usa a empresa ativa. Identificações simultâneas precisam corresponder.

A lista em dados descreve cada plano: código comercial (como AP/02), tipo/tabela, descrição, vigência, status, prazos, descontos e configurações comerciais previstas no schema. Nulos podem ser omitidos: preserve a distinção entre ausência, zero e false.

Sem escolha liberada, só o padrão efetivo elegível é oferecido. Com escolha, a lista ainda é limitada aos planos autorizados do cliente/canal e condições especiais vigentes do próprio cliente, respeitando empresa e status. Um plano existir não o torna elegível para qualquer cliente.

A configuração do plano não é uma cotação de produto. Obtenha o preço calculado no catálogo comercial. O endereço anterior planos-de-venda permanece como alias, mas novas integrações devem usar /consultar.

08 · Catálogo e preços

Escolha uma oferta elegível

POST /api/E001/{parceiro}/produtos/consultar?page=1&size=50

{
  "codigoEmpresa": 1,
  "codigoCliente": "19",
  "planoDeVendas": "AP/02",
  "codigosSkus": ["123"],
  "codigosBarras": ["7890000000000"]
}

Os filtros são opcionais. As listas de SKU e barras, quando ambas preenchidas, formam união. Sem lista, consulte o catálogo por páginas; sem empresa, usa a ativa. Também aceita cnpjEmpresa e cnpjCliente, sujeitos à correspondência quando códigos forem enviados. O alias produtos existe por compatibilidade.

Cada produto retorna codigoProduto, codigoBarras, nome, marca, unidade, fornecedor e precos. Esta lista contém alternativas, não apenas um preço. Não escolha automaticamente a menor nem acumule campanhas.

Campos da alternativaUso
identificador, promocaoIdentifica preço normal/dinâmico ou nome da campanha promocional.
precoUnitario, precoLiquidoComercialBruto unitário e líquido comercial calculado. Envie o bruto no pedido.
desconto1/2/3, descontoComercial, descontoFinanceiroPercentuais com seus respectivos campos de valor. O comercial vai no cabeçalho do pedido.
desconto3PorAntecipacao, loteCondição de antecipação e lote quando aplicáveis; não deduza antecipação novamente do líquido.
kit, composicaoKitComposição, quantidades mínimas, preços, lotes e bonificações do conjunto; preço total do kit.

A consulta avalia ofertas unitárias para uma unidade; kits pela composição completa de um kit. Promoções dependem de vigência, cliente/plano/parceria, quantidade, valor e demais restrições. Uma oferta não aparecer para uma unidade não permite inventar a condição para outra quantidade.

Produtos candidatos sem oferta elegível podem retornar precos: []. totalElements conta produtos, não alternativas. Não trate lista vazia como preço zero. Custos, markup e preço mínimo de negociação não são publicados.

Envio de kit exige uma linha por componente e proporção inteira de kits; brindes têm preço e descontos do item zerados. Identifique a campanha em nomePromocao e o lote quando necessário. A recepção revalida condições e quantidades efetivas; o catálogo não reserva estoque.

09 · Pedidos

Do catálogo ao acompanhamento do pedido

O prefixo é /api/E001/{parceiro}. Substitua {parceiro} pela identificação autorizada, fornecida na implantação. Ela não é um identificador arbitrário escolhido pelo comprador.

Captura de um pedido

POST /api/E001/{parceiro}/pedidos, sem paginação. Preços, descontos, plano e representante devem corresponder ao contexto retornado nas consultas; os valores abaixo são apenas didáticos.

{
  "codigoEmpresa": 1,
  "codigoCliente": 19,
  "codigoRepresentante": 7,
  "identificadorExterno": "CRM-000123",
  "planoDeVendas": "AP/02",
  "descontoComercial": 0.00,
  "itens": [
    {
      "identificadorExterno": "linha-1",
      "codigoProduto": 123,
      "quantidade": 2,
      "precoUnitario": 100.00,
      "descontos": {
        "desconto1": 10.00,
        "desconto2": 0.00,
        "desconto3": 0.00,
        "descontoFinanceiro": 0.00
      }
    }
  ]
}
CAPTURADO não significa aprovado ou faturado. A recepção não reserva estoque nem aprova crédito. Bloqueios e atendimento operacional são tratados pelo SGDAT. Uma divergência comercial detectada na captura impede o envio inteiro; não há captura comercial parcial.

Reenvio e duplicidade

Com o controle de idempotência instalado e acessível, a mesma referência externa, no mesmo contexto, com o mesmo conteúdo retorna a captura original (HTTP 200). Conteúdo divergente retorna HTTP 409. Uma captura nova bem-sucedida retorna HTTP 201.

A deduplicação depende da instalação. A API pode capturar pedidos mesmo sem o controle de idempotência; nesse caso, repetir a chamada pode criar outro pedido. Confirme sua ativação e homologue o reenvio antes de habilitar tentativas automáticas. Em resultado incerto, reconcilie a referência/protocolo antes de criar uma nova referência.

Consultar o estado atual

POST /api/E001/{parceiro}/pedidos/consultar:

{
  "codigoEmpresa": 1,
  "codigoCliente": 19,
  "identificadorExterno": "CRM-000123"
}

Também é possível consultar pelo protocolo devolvido na captura. A resposta atual inclui status e itens, com quantidades solicitadas e atendidas quando disponíveis. Não substitua essa consulta pelo reenvio: o replay devolve a recepção original.

Para XML: GET /api/E001/{parceiro}/nfe/xml?codigoEmpresa=1&codigoCliente=19&numeroPedido=123. O número deve ser o pedido no SGDAT, não o protocolo nem a referência externa. O sucesso retorna ZIP binário, mesmo com uma única NF-e; não tente interpretá-lo como JSON. Essa operação entrega XML, não DANFE em PDF.

10 · Pesquisa de pedidos

Liste os pedidos do cliente

POST /api/E001/{parceiro}/pedidos/listar?page=1&size=50

{
  "codigoCliente": 19,
  "codigoEmpresa": 1,
  "dataInicial": "2026-10-01",
  "dataFinal": "2026-10-31",
  "protocolos": [123456,123457],
  "identificadoresExternos": ["CRM-000123","CRM-000124"]
}

Somente codigoCliente é obrigatório; não aceita CNPJ no lugar dele. Empresa omitida considera todas as empresas autorizadas. Datas são de recepção, com dias inicial e final inclusivos. Sem datas, considera o histórico operacional disponível.

Filtros são cumulativos: se enviar protocolos e referências, o pedido precisa corresponder a ambos. Cada lista aceita até 1.000 valores. Referências preservam letras, caixa e zeros; ABC e abc são diferentes. Nas consultas, o limite histórico é 120 bytes UTF-8 por referência, mesmo que novas capturas aceitem somente 50.

Retorna protocolo, identificadorExterno, codigoEmpresa, razaoSocialEmpresa, dataPedido e status, por data mais recente e protocolo decrescente, com desempate por empresa. Sem resultados: HTTP 200 e lista vazia.

A lista cobre somente pedidos ainda presentes no armazenamento operacional de recepção do SGDAT. Ela não é um arquivo permanente de todas as capturas. Na consulta individual, uma captura conhecida pode retornar dadosOperacionaisDisponiveis: false quando seu detalhe operacional já não estiver disponível.

Interprete a consulta individual

pedidos/consultar exige empresa, cliente e protocolo ou referência. Empresa/cliente podem ser informados por código ou CNPJ; identificações simultâneas devem corresponder. Protocolo e referência enviados juntos são cumulativos. Não há paginação; o corpo admite até 32 KiB.

A resposta possui recebidoEm, consultadoEm, dadosOperacionaisDisponiveis, status, numeroOrcamento, numeroPedidoEmpresa, plano, valores comerciais e itens. Cada status contém codigo, situacao e descricao; trate valores futuros desconhecidos sem convertê-los em aprovação. Quantidades atendidas podem ser nulas quando indisponíveis.

Contexto incorreto ou pedido ausente retorna 404. Se uma referência localizar mais de um pedido, informe o protocolo exigido pela resposta 400. Pedidos antigos podem não preservar a referência textual ou a identidade externa dos itens; não reconstrua zeros ou letras que não foram armazenados.

11 · Contas a receber

Mostre os títulos em aberto

POST /api/E001/{parceiro}/contas-a-receber/consultar?page=1&size=50

{"codigoCliente":19,"codigoEmpresa":1}

Cliente inteiro positivo obrigatório; empresa opcional. Omissão inclui todas as empresas autorizadas. Os títulos podem ter origem em outros canais de venda: a seleção é por cliente e empresa autorizados, não apenas pelos pedidos da parceria.

Retorna apenas títulos não quitados com saldo positivo. Cada linha informa codigoEmpresa, numero, parcela, dataEmissao, dataVencimento e valorEmAberto. Número/parcela são textos.

diasAtraso, juros, multa, codigoBarras e linhaDigitavel são omitidos quando não aplicáveis. Juros/multa usam a data do banco na consulta e as regras SGDAT, inclusive pagamento parcial e tolerância de multa. Valores publicados têm duas casas decimais.

Não é uma cotação de liquidação. A operação não publica total a pagar, não incorpora todas as negociações/descontos financeiros e não gera nem atualiza boletos. Apresente os campos conforme seu significado, sem prometer que a soma corresponde ao valor exigido pelo banco.

Cliente sem títulos elegíveis, inexistente ou fora do escopo produz lista vazia. Não confunda esse recorte com o agregado global de crédito retornado pela consulta de clientes.

12 · Documentos fiscais

Obtenha os XMLs da NF-e

GET /api/E001/{parceiro}/nfe/xml?codigoEmpresa=1&codigoCliente=19&numeroPedido=123

Os três códigos são obrigatórios, positivos e enviados na query, sem corpo. numeroPedido identifica o pedido SGDAT; não é o protocolo de recepção nem a referência externa do CRM. Use o número do pedido da empresa identificado no acompanhamento.

curl --fail-with-body \
  "$INTEGRA_URL/api/E001/$INTEGRA_PARCEIRO/nfe/xml?codigoEmpresa=1&codigoCliente=19&numeroPedido=123" \
  --header "Authorization: Bearer $INTEGRA_TOKEN" \
  --output nfe-pedido.zip

HTTP 200 retorna application/zip com um arquivo <chave>-procNfe.xml por NF-e, inclusive diferentes ordens de faturamento. Mesmo uma nota vem compactada. Verifique status e Content-Type antes de abrir o download: respostas de erro não são ZIP.

A operação valida emitente, destinatário e vínculo com o pedido. Arquivo ausente, conteúdo fiscal inconsistente ou falha interna não deve ser tratado como download bem-sucedido. O ZIP é preparado integralmente; não há paginação nem manifesto JSON. O acesso pode abranger pedidos originados em outros canais, respeitando escopo.

Não há geração de DANFE PDF nessa operação. Preserve o XML entregue sem alterar seu conteúdo fiscal.

13 · Tratamento e homologação

Uma integração preparada para exceções

HTTPComo tratar
200 / 201Leitura/reenvio ou nova criação, conforme operação. Captura não equivale a aprovação operacional.
400Corrigir estrutura, tipos, identificação ou filtros. Não repetir sem correção.
401 / 403Validar token ou permissões de rota, parceria, empresa e vendedor. Não contornar escopo.
404Recurso não localizado no contexto autorizado, quando previsto no endpoint.
409Conflito cadastral ou referência de pedido com conteúdo divergente; reconciliar antes de novo envio.
422 em pedidosRecusa comercial integral. Corrigir as condições usando erros por linha; não houve captura nessa tentativa.
499Requisição cancelada pelo consumidor. Em escrita, verifique o resultado antes de repetir.
503Contenção ou indisponibilidade; respeitar Retry-After quando retornado. Escritas exigem verificar resultado e proteção de duplicidade.
500Registrar rastreio e acionar suporte; não deduzir uma causa a partir de textos genéricos.

No pré-cadastro, códigos públicos incluem JSON_INVALIDO, DADOS_INVALIDOS, ACESSO_NEGADO, CONFLITO_CADASTRAL, CADASTRO_OCUPADO e FALHA_INTERNA. O erro pode incluir rastreio, etapa e campos. Não presuma esse formato em todas as operações.

Na captura, o 422 informa capturado: false e erros, com identificador do item, código, mensagem e condição esperada quando calculável. O desconto comercial divergente pertence ao cabeçalho. Campos livres de diagnóstico não são códigos estáveis para regras de negócio.

Antes de operar em produção

  1. Valide parceria, empresas e vendedores em homologação, incluindo tentativas fora do escopo.
  2. Confira página inicial, intermediária, final e vazia; não totalize apenas a primeira página.
  3. Teste pré-cadastro mínimo, documento existente, conflito e consulta de situação.
  4. Teste cliente sem plano, sem representante, bloqueado e produto sem oferta.
  5. Teste pedido regular, promoção e kit; capture recusas sem reenviar automaticamente condições antigas.
  6. Confirme que o controle de idempotência está instalado e acessível. Teste replay idêntico, conflito e perda de resposta.
  7. Confira acompanhamento, listagem, títulos e ZIP contra registros conhecidos do SGDAT.
  8. Defina frequência de consultas, monitoramento e reconciliação. Não presuma webhooks, aprovação imediata ou atualização automática do pedido enviado.

Não há neste contrato operações para cancelar/editar pedidos capturados, liquidar títulos ou liberar cadastros. Alinhe esses processos com a operação do SGDAT.