Documentação técnica

Integre seu ERP ao LetsPOS.

Referência para software houses publicarem catálogo, importarem vendas e conectarem pedidos de retirada ao PDV.

https://app.letspos.com.br/api/v1

O ERP é a fonte de verdade para catálogo, preço, estoque, tributação, clientes, vendedores, vendas e conciliação. O LetsPOS mantém a venda como PENDING até o ERP confirmar a importação.

Autenticação e isolamento

Toda chamada exige uma chave adequada à finalidade e o estabelecimento:

Authorization: Bearer <CHAVE>
X-Establishment-Id: loja-01

Fluxo confiável de vendas

1. O ERP publica os cadastros permitidos.
2. O PDV baixa o bootstrap, valida e registra a venda.
3. O ERP consulta vendas PENDING.
4. Em uma transação, grava venda e recebimento.
5. Após o commit, chama acknowledge.

clientSaleId é a chave de idempotência. Em caso de reenvio, o ERP deve reconhecer a venda sem duplicar estoque ou financeiro.

Publicar cadastros

Estas rotas usam a chave de integração do ERP. Lotes fazem upsert por externalId dentro da loja. Para bloquear itens, envie active: false ou sellable: false.

{"items":[{"externalId":"PIZZA-01","name":"Pizza especial","categoryExternalId":"PIZZAS","price":3500,"stock":50,"sellable":true}]}

Pedidos para retirada

Qualquer canal de pedidos pode publicar pedidos para retirada no estabelecimento. Valor e itens ficam bloqueados no PDV.

{"items":[{"externalId":"CANAL-1042","source":"CANAL_PARCEIRO","customerName":"Maria Silva","total":4590,"status":"AWAITING_PAYMENT","fulfillment":"PICKUP","items":[{"name":"X-Burger","quantity":2,"unitPrice":1800}]}]}

Defina source com o identificador estável do seu canal. Status válidos: AWAITING_PAYMENT, PAID e CANCELLED.

Importar vendas no ERP

{"id":"4d88266b-dfb3-4a73-aea7-bd8ea0d42c24","status":"ACKNOWLEDGED","payloadPurged":true}

Após o acknowledge, o LetsPOS elimina o payload detalhado e conserva somente uma tombstone mínima para idempotência.

Cobrança rápida sem produto

A retaguarda pode solicitar uma cobrança direta no terminal. Esta operação não cria produto, carrinho, estoque ou documento fiscal.

{"terminalId":"caixa-01","reference":"PEDIDO-ERP-9001","amount":2590,"paymentCode":"DEBITO_AVISTA","installments":1}

Para importar: GET /integration/payment-requests?status=APPROVED&limit=100 e POST /integration/payment-requests/{id}/acknowledge. A chave de idempotência é reference.

Códigos HTTP

Segurança obrigatória

• Use TLS/HTTPS, chaves aleatórias de no mínimo 32 bytes e uma chave por loja e finalidade.
• Proteja os servidores do ERP com firewall, VPN ou allowlist; aplique rate limit.
• Não registre corpos de requisição/resposta em produção; trate dados pessoais conforme LGPD.
• Nunca envie ou armazene PAN, CVV, PIN, trilha magnética, senha ou segredo de adquirente.

Checklist de homologação

• Catálogo sincronizado por externalId; item bloqueado deixa de ser vendável.
• Variações, modificadores e preços são validados pelo servidor.
• Reenvio não duplica estoque ou financeiro.
• Venda e recebimento são gravados na mesma transação no ERP.
• A confirmação ocorre apenas após o commit.
• HTTPS, logs, backup, firewall e rate limit foram revisados.