Cadastro conectado
Receba interessados no seu sistema e encaminhe pré-cadastros para complementação no 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.
Receba interessados no seu sistema e encaminhe pré-cadastros para complementação no SGDAT.
Ofereça produtos, planos e preços disponíveis para o cliente e a parceria.
Acompanhe pedidos, consulte títulos em aberto e obtenha XMLs das notas vinculadas ao pedido.
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.
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.
Content-Type: application/json e datas yyyy-MM-dd quando o campo representar um dia. Valores monetários usam ponto decimal.codigoCliente é texto; na captura de pedido, é inteiro.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]}'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 envelope | Formato de sucesso |
|---|---|
| Receber pré-cadastro | Objeto de situação cadastral. |
| Consultar pré-cadastros | Array de situações; até 100 documentos por requisição. |
| Receber pedido | Objeto de captura com protocolo e todas as linhas. |
| Consultar pedido individual | Objeto de situação atual e itens. |
| XML da NF-e | Arquivo ZIP binário, sem JSON. |
/api/E001/{parceiro}/bairros/consultar?page=1&size=50
{"nome":"centro"}Retorna codigoBairro e nome em cada elemento de dados.
/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.
/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 opcionais | Regras de uso |
|---|---|
| nomeFantasia, inscricaoEstadual, rg, email, telefone, telefoneAlternativo | Nome/fantasia até 60 caracteres; IE/RG até 17; e-mail até 200. Telefones brasileiros com DDD. RG não substitui IE. |
| codigoVendedor | Precisa existir e estar autorizado. Com um único vendedor no escopo, pode ser resolvido quando omitido; com vários, deve ser escolhido. |
| limiteCredito | Decimal não negativo; omitido grava zero. Não representa aprovação de compra. |
| dataConsultaCredito, orgaoConsultaCredito | Informar juntos. Data sem horário e órgão até 20 caracteres. |
| dataAberturaEmpresa, socios | Somente 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, longitude | Observações até 1.500 caracteres; latitude de -90 a 90, longitude de -180 a 180; zero é válido. |
| endereco | logradouro, 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.
/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ção | Interpretaçã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 / SituacaoIndefinida | Outros status / status ausente; não considerar concluído. |
| NaoEncontrado | Inexistente 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.
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.
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.
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.
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 alternativa | Uso |
|---|---|
| identificador, promocao | Identifica preço normal/dinâmico ou nome da campanha promocional. |
| precoUnitario, precoLiquidoComercial | Bruto unitário e líquido comercial calculado. Envie o bruto no pedido. |
| desconto1/2/3, descontoComercial, descontoFinanceiro | Percentuais com seus respectivos campos de valor. O comercial vai no cabeçalho do pedido. |
| desconto3PorAntecipacao, lote | Condição de antecipação e lote quando aplicáveis; não deduza antecipação novamente do líquido. |
| kit, composicaoKit | Composiçã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.
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.
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
}
}
]
}precoUnitario é o preço bruto unitário, com no máximo duas casas decimais. Envie os quatro descontos explicitamente, inclusive zeros. O desconto comercial fica no cabeçalho.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.
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.
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.
dadosOperacionaisDisponiveis: false quando seu detalhe operacional já não estiver disponível.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.
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.
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.
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.zipHTTP 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.
| HTTP | Como tratar |
|---|---|
| 200 / 201 | Leitura/reenvio ou nova criação, conforme operação. Captura não equivale a aprovação operacional. |
| 400 | Corrigir estrutura, tipos, identificação ou filtros. Não repetir sem correção. |
| 401 / 403 | Validar token ou permissões de rota, parceria, empresa e vendedor. Não contornar escopo. |
| 404 | Recurso não localizado no contexto autorizado, quando previsto no endpoint. |
| 409 | Conflito cadastral ou referência de pedido com conteúdo divergente; reconciliar antes de novo envio. |
| 422 em pedidos | Recusa comercial integral. Corrigir as condições usando erros por linha; não houve captura nessa tentativa. |
| 499 | Requisição cancelada pelo consumidor. Em escrita, verifique o resultado antes de repetir. |
| 503 | Contenção ou indisponibilidade; respeitar Retry-After quando retornado. Escritas exigem verificar resultado e proteção de duplicidade. |
| 500 | Registrar 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.
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.
Prefixo: /api/E001/{parceiro}/. O Swagger do ambiente descreve todos os schemas, campos e retornos da versão instalada. No menu do Integra, use Documentação → Swagger quando estiver habilitado.
| Operação / caminho | Finalidade |
|---|---|
POST clientes/consultar | Clientes e contexto comercial da parceria. |
POST bairros/consultar | Códigos e nomes de bairros. |
POST cidades/consultar | Códigos e nomes de cidades. |
POST clientes/pre-cadastros | Envio de pré-cadastro de cliente. |
POST clientes/pre-cadastros/consultar | Acompanhamento do pré-cadastro. |
POST planos-de-venda/consultar | Planos de venda permitidos para o contexto. |
POST produtos/consultar | Catálogo com preços e condições comerciais. |
POST pedidos | Recepção integral do pedido para processamento. |
POST pedidos/consultar | Situação atual de um pedido da parceria. |
POST pedidos/listar | Listagem de pedidos por cliente e filtros. |
POST contas-a-receber/consultar | Títulos em aberto e valores para pagamento. |
GET nfe/xml | Download ZIP com XMLs de NF-e do pedido SGDAT. |
As rotas antigas produtos e planos-de-venda são aliases; não são operações adicionais. Este guia cobre o contrato HTTP de integração, sem exigir conhecimento das tabelas internas do SGDAT.