Integração de PDV Externo

O Next recebe a operação de caixa de um PDV externo por uma API REST. O PDV monta um arquivo texto com o movimento do dia e o entrega por HTTP. Não há consulta ativa do lado do Next: quem inicia a comunicação é sempre o PDV.

São três coisas que podem ser enviadas, em dois formatos:

1.1Como o dado atravessa o sistema

O arquivo não vira venda imediatamente. Ele passa por uma área de estagiamento, onde cada linha é decomposta em pares campo/valor. Só depois que os códigos de produto e forma de pagamento estão correlacionados aos cadastros do Next (§7) o movimento é materializado. Os demais códigos — vendedor e motivos de desconto e cancelamento — apenas ficam sinalizados como pendentes e não retêm o dia.

2.1Endereço

Cada ambiente tem seu próprio subdomínio. A base é:

https://{entidade}.retaguarda.altec.app.br/webs/api

{entidade}  nome do ambiente da loja no Next, informado no provisionamento

2.2Autenticação

A autenticação é feita por um identificador fixo enviado no cabeçalho HTTP Apiguid. Não há OAuth, token de expiração ou renovação — o identificador é permanente até ser revogado.

Apiguid: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

Duas propriedades do identificador merecem atenção porque afetam o desenho da sua integração:

• Ele determina o destino. É o Apiguid — e não o subdomínio da URL — que define em qual ambiente os dados serão gravados. Um identificador enviado para o subdomínio errado ainda grava no ambiente correto. Mantenha o par identificador + subdomínio consistente por loja.
• Ele pode ser restrito por IP. A lista aceita apenas endereços literais separados por vírgula, comparados por igualdade exata — não há suporte a faixas ou notação CIDR, e informar 200.1.2.0/24 não autoriza ninguém. O endereço conferido é o IP de origem visto pelo servidor, que pode diferir do seu se houver proxy ou NAT no caminho. O padrão liberado é qualquer origem; só peça a lista restrita se a sua saída tiver IP fixo, e valide antes com a equipe do Next — do contrário a autenticação passa a falhar com cd_erro 2, indistinguível de identificador revogado.

2.3Limites técnicos

Transporte

HTTPS — certificado público válido

Corpo

multipart/form-data ou x-www-form-urlencoded

Tamanho máximo

200 MB por requisição — inclui a inflação de ~33% do Base64

Tempo máximo

1200 s no servidor — mas a resposta chega em segundos (§3.3). Configure o timeout do seu cliente com folga, por volta de 120 s

Codificação

Texto do arquivo em ASCII/UTF-8, sem BOM

Para dimensionar: um dia de movimento de uma casa com cerca de 95 contas e 640 linhas gera um arquivo de aproximadamente 50 KB. A folga em relação ao limite é de várias ordens de grandeza.

2.4O que você recebe no provisionamento

Antes do primeiro envio, a equipe do Next entrega — por canal seguro, nunca neste documento — os três valores abaixo, um conjunto por ambiente:

Do seu lado, informe: os IPs de origem (se quiser a lista restrita) e a relação de lojas a integrar, com o CNPJ de cada uma.

3.1A requisição

O arquivo não vai como upload binário: vai como um campo de formulário contendo o conteúdo em Base64.

POST /webs/api/venda HTTP/1.1
Host: {entidade}.retaguarda.altec.app.br
Apiguid: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}
Content-Type: multipart/form-data; boundary=----limite

------limite
Content-Disposition: form-data; name="cnpj"

00000000000000
------limite
Content-Disposition: form-data; name="nm_arquivo"

EXPORTACAO_OLGA_NEXT_00000000000000_20260817.txt
------limite
Content-Disposition: form-data; name="arquivo"

fFIwMXwyMDI2MDgxN3w5NXwyMDZ8Mjc2MjguOTB8...  (Base64 do .txt)
------limite--

3.2A resposta

A resposta é sempre JSON com dois campos:

{ "cd_erro": 1, "msg": "Sucesso!" }

3.3A confirmação é antecipada

Este é o ponto do contrato mais fácil de interpretar errado. O processamento de um arquivo com milhares de linhas leva tempo — mais do que o tempo de espera típico de um cliente HTTP. Para evitar que o PDV conclua por engano que o envio falhou e reenvie em laço, o Next responde assim que o arquivo está gravado com segurança e só depois processa.

O que isso significa na prática

• Ao receber cd_erro 1, marque o arquivo como entregue e não reenvie. Reenvio em laço é justamente o que este desenho evita.
• Não espere confirmação de processamento pela API. Ela não existe neste canal. O acompanhamento do resultado é feito na tela de importações do Next, pelo operador da loja.
• Um arquivo aceito pode ficar retido aguardando correlação de cadastros (§7). Isso é esperado no início da operação e não indica erro de envio.
• Se um arquivo aceito aparecer na tela de importações sem nenhuma linha, houve falha depois da resposta. A recuperação é reenviar o mesmo nm_arquivo, que reaproveita o registro e reprocessa do zero (§8.2) — isso não contradiz a regra acima, que veta o reenvio em laço logo após o cd_erro 1.

3.4Rotina diária recomendada

A prática consolidada em produção é um envio por loja, uma vez ao dia, após o fechamento da casa — tipicamente por volta das 22h. A ordem importa quando há cupom fiscal:

1. Envie o arquivo de vendas (POST /venda) e aguarde cd_erro 1.
2. Envie os XMLs (POST /nfce), um por chamada, referenciando o número da conta.

4.1Regras do formato

Delimitador

barra vertical |

Cada linha

começa e termina com |

Primeiro campo

o tipo do registro: R01 … R99

Fim de linha

CRLF ou LF — ambos aceitos

Codificação

ASCII / UTF-8 sem BOM

Campo vazio

dois delimitadores seguidos: ||

4.2Estrutura

O arquivo é hierárquico e ordenado. Um cabeçalho, um rodapé, e no meio as contas — cada uma seguida de seus itens e pagamentos.

4.3R01 · Cabeçalho do movimento

Nove campos. Abre o arquivo e define a data de referência.

pagamentos = venda_bruta − cancelamentos − descontos + taxas_adicionais
   [9]           [5]            [6]             [7]           [8]

4.4R02 · Conta

Doze campos. Uma linha por conta fechada.

4.5R03 · Item vendido

Dezesseis campos. O produto propriamente dito.

4.6R04 · Modificador

Quinze campos: idêntico ao R03, sem o campo 8 (modo de pedido). Todos os campos a partir da posição 8 deslocam uma casa à esquerda.

4.7R05 · Pagamento

Oito campos. Uma linha por transação de pagamento.

Troco e repique são identificados pelo nome

Esta é a regra mais sutil do layout. O Next classifica cada linha R05 lendo o nome da forma de pagamento (campo 7), sem diferenciar maiúsculas de minúsculas — não o código:

4.8R99 · Rodapé

Três campos. Deve ser a última linha do arquivo.

4.9Exemplo completo

Um arquivo mínimo válido, com uma conta, dois itens, um modificador e dois pagamentos (um deles repique):

|R01|20260817|1|2|108,10|0|0,0000|10,80|118,90|
|R02|14|MARIA|1000501|12|19:40|21:05|2|118,90|10,80|2|0|
|R03|14|MARIA|1000501|19:42|201002|AGUA C/ GAS|1|0|0|16,00|2.000|0,0000|0|1T1800|3|
|R03|14|MARIA|1000501|19:55|102043|FILE AO MOLHO|1|0|0|92,10|1.000|0,0000|0|1T1800|3|
|R04|14|MARIA|1000501|19:55|103009|PONTO AO PONTO|0|0|0,00|1.000|0,0000|0|1T1800|3|
|R05|10|CAIXA|1000501|21:05|50|MASTER CREDITO|118,95|
|R05|10|CAIXA|1000501|21:05|1|REPIQUE|-0,05|
|R99|8|00000000000000|

Conferindo o exemplo — vale usar como teste do seu gerador:

• Itens: 16,00 + 92,10 + 0,00 = 108,10 — é a venda bruta do R01, sem a taxa.
• Total da conta: 108,10 + 10,80 de taxa = 118,90 — campo 9 do R02.
• Pagamentos: 118,95 − 0,05 de repique = 118,90 — fecha com o total da conta.
• Linhas: 8 no arquivo, 8 declaradas no R99.
• Unitários derivados pelo Next: 16,00 ÷ 2 = 8,00 e 92,10 ÷ 1 = 92,10.

O envio de cupom fiscal é opcional e independente do arquivo de vendas. Serve para que o Next guarde o documento fiscal e o vincule à venda correspondente.

5.1Requisição

Mesma autenticação do §2.2. Um XML por chamada. O corpo tem um campo a mais:

5.2Tipos aceitos

O tipo é determinado pelo primeiro elemento filho da raiz — não pela raiz em si. Essa distinção importa na hora de escolher qual arquivo enviar:

• Para cancelar NFC-e: envie o XML do evento (tpEvento 110111).
• Para cancelar CF-e (SAT): envie o XML de cancelamento gerado pelo equipamento. Não existe evento tpEvento para SAT — enviar um evento não cancela nada.
• Em ambos, o venda_id deve ser o mesmo da venda original.
• XML que não possa ser interpretado retorna cd_erro 12.

As três subseções abaixo concentram os pontos que costumam falhar em silêncio — sem mensagem de erro, com número errado gravado. Vale conferir cada uma contra o gerador do seu PDV.

6.1Números: dois formatos no mesmo arquivo

Valores monetários e quantidade não são convertidos da mesma forma. Isso não aparece em operação normal — e é justamente por isso que merece atenção.

Resumo prático:

• Quantidade: ponto decimal, três casas — 1.000, 2.500, 0.750. Sem separador de milhar.
• Valores monetários: vírgula decimal, duas casas, sem milhar — 92,10, 1234,56. O sinal negativo é preservado (troco e repique).
• Valor é sempre o total da linha, já multiplicado pela quantidade. O Next divide pela quantidade para obter o unitário — enviar o unitário multiplica o faturamento pela quantidade.

6.2Datas e horas

As horas são concatenadas à data do R01, e o Next acrescenta os segundos. Envie exatamente HH:MM, com dois dígitos — 09:05, não 9:5 — e não inclua segundos: 19:42:31 produz uma data e hora malformada.

6.3Índice fiscal

O campo de índice fiscal do R03/R04 é composto, separado pela letra T:

  1 T 1800
  │   │    │
  │   │    └── alíquota sem separador decimal → 18.00 %
  │   └─────── separador literal, sempre a letra T
  └─────────── índice da alíquota no equipamento fiscal

A alíquota é lida por posição: os dois primeiros dígitos são a parte inteira, o restante são as casas decimais.

O Next não conhece a codificação de produtos do seu PDV. Quando um código chega pela primeira vez, ele fica em espera até que um operador da loja o associe a um cadastro do Next. Essa associação é aprendida — mas só passa a valer para os arquivos seguintes depois que o arquivo em que ela foi feita for concluído. Um arquivo que continua pendente não ensina nada ao próximo.

7.1O que bloqueia e o que não bloqueia

A distinção é importante para você calibrar as expectativas da loja:

7.2Recomendações para reduzir o atrito

• Use códigos estáveis. A associação é feita por código. Se o código de um produto mudar no seu PDV, ele volta a ser desconhecido para o Next.
• Envie descrições legíveis. O operador escolhe o cadastro correto olhando a descrição do campo 7. FILE AO MOLHO MADEIRA resolve rápido; PROD-4471 não.
• Não conte com a homologação para adiantar a associação. O Next só reaproveita uma associação dentro do mesmo ambiente e depois que o arquivo em que ela foi feita for concluído. O que a loja associar em homologação não migra para produção. Planeje a associação para o primeiro arquivo real — ele fica retido até que ela seja feita — e use a homologação para validar formato e conteúdo.
• Avise a loja quando lançar produtos novos. Cada código novo exige uma associação, e até lá o dia fica retido.

8.1A chave é o nome do arquivo

A verificação de duplicidade usa o nome informado em nm_arquivo — não o conteúdo. Não há verificação de integridade por hash. Duas consequências práticas:

• Mesmo nome, conteúdo diferente é tratado como reenvio do mesmo arquivo. Se você corrigir o conteúdo de um dia, o nome precisa se manter para que o Next reconheça a correção — e o dia não pode ter sido concluído ainda.
• Nomes diferentes, mesmo conteúdo são dois arquivos distintos. Evite carimbar hora ou número aleatório no nome: use um nome determinístico por loja e dia (§3.1).

8.2Comportamento no reenvio

8.3Falhas parciais

O processamento não é uma transação única do arquivo: cada venda é gravada individualmente. Se ocorrer uma falha no meio, as vendas já gravadas permanecem e o arquivo fica pendente. O reenvio completa o que faltou — as vendas já existentes são reconhecidas e não são duplicadas.

A equipe do Next disponibiliza um ambiente de testes com identificador próprio. Sugerimos percorrer os passos abaixo na ordem — cada um isola uma classe de problema.

9.1Conectividade e autenticação

• Ping responde. GET /webs/api/ — com a barra final — retorna cd_erro 11.
• Tudo em HTTPS. Nenhuma chamada da integração usa http://.
• Identificador aceito. Um POST /venda com o Apiguid correto não retorna cd_erro 2.
• Identificador inválido é recusado. Repetindo o POST /venda com um dígito alterado, o retorno é cd_erro 2 com HTTP 401.
• Seu cliente lê o corpo. Confirme que a integração decide por cd_erro, e não por HTTP 200 — e que resposta não-JSON é tratada como falha de transporte.
• CNPJ conferido com o suporte. A API não recusa CNPJ divergente (§3.2). Confirme o valor correto de cada loja antes do primeiro envio.

9.2Estrutura do arquivo

• Contagem de campos. R01 = 9, R02 = 12, R03 = 16, R04 = 15, R05 = 8, R99 = 3.
• Delimitação. Toda linha começa e termina com |.
• Sem aspas duplas em nenhuma descrição.
• R01 primeiro, R99 último, um de cada.
• R99 confere. O total de linhas bate com o arquivo e o CNPJ está sem pontuação.
• Um único dia de movimento por arquivo.

9.3Conteúdo e valores

• Quantidade com ponto decimal. Teste um item fracionado, como 0.500.
• Valor é o total da linha. Teste um item com quantidade 2 e confira o unitário no Next.
• Data do R01 em AAAAMMDD.
• Soma dos R05 bate com o total das contas, considerando troco e repique negativos.
• Repique nomeado corretamente — literal REPIQUE, valor negativo.
• Item cancelado chega com o indicador 1 e não soma no faturamento.

9.4Operação

• Correlação completa. Todos os produtos e formas de pagamento associados (§7).
• Reenvio não duplica. Envie o mesmo arquivo duas vezes e confira o faturamento.
• Cupom vinculado. Um XML enviado com venda_id aparece na venda correta.
• Conferência de fechamento. Os totais do Next batem com o relatório do seu PDV.

10.1Códigos de retorno

10.2Glossário

Entidade

Nome do ambiente de uma loja no Next; compõe o subdomínio da URL.

Apiguid

Identificador permanente de acesso à API, específico por loja.

Conta

Uma venda fechada. Equivale a mesa, comanda ou cupom, conforme a operação.

Repique

Gorjeta ao garçom. Trafega como pagamento de valor negativo.

Correlação

Associação entre um código do seu PDV e um cadastro do Next.

Movimento

O conjunto da operação de um dia em uma loja.

Fechamento

Consolidação do movimento por forma de pagamento, gerada pelo Next.

10.3Resumo do contrato