API para sistemas de loja

Para quem é esta página

Para quem desenvolve o sistema que o restaurante já usa. O lojista não precisa ler nada aqui: ele gera uma chave dentro do aplicativo do parceiro e entrega para você.

O desenho é o mesmo que você já conhece de outras plataformas de delivery: o seu sistema pergunta ao Inksa se há pedido novo. Não precisamos de endereço público, porta aberta, IP fixo nem webhook do seu lado. Se o PDV da loja ficar sem internet por vinte minutos, nada se perde — na próxima pergunta os pedidos daquele período vêm juntos.

Começar em três passos

1. O lojista gera a chave. No aplicativo do parceiro: Integração → Chaves de acesso → Gerar chave. A chave aparece uma única vez; ele copia e entrega para você.
2. Você confere a chave chamando /status. A resposta diz de qual loja ela é. Se o nome não for o esperado, pare aqui.
3. Você passa a perguntar por pedidos em /pedidos, a cada 30 ou 60 segundos.

Endereço e autenticação

https://inksa-auth-flask-dev.onrender.com/api/parceiro/v1

Toda chamada leva a chave no cabeçalho Authorization:

Authorization: Bearer ink_live_xxxxxxxxxxxxxxxxxxxx

A chave vale para uma loja só. Rede com várias unidades usa uma chave por unidade. Tudo é JSON, em UTF-8.

Conferir a chave

# pedido
curl -H "Authorization: Bearer $CHAVE" \
  https://inksa-auth-flask-dev.onrender.com/api/parceiro/v1/status

# resposta
{
  "ok": true,
  "versao": "1.0",
  "ambiente": "live",
  "loja": {
    "id": "7a9057cb-cbcd-4c29-8799-65632b3ebd8d",
    "nome": "Yo!Frango frito e comida Coreana",
    "aberta": true
  },
  "servidor_em": "2026-09-02T23:39:51.265628+00:00"
}

Chame isto antes de qualquer outra coisa. É barato e evita o erro mais caro da integração: configurar a chave de uma loja no sistema de outra e só descobrir quando um pedido não chega — no movimento, com o cliente esperando.

Buscar pedidos

Devolve os pedidos alterados depois de desde, do mais antigo para o mais novo. Sem desde, devolve as últimas 24 horas.

curl -H "Authorization: Bearer $CHAVE" \
  ".../pedidos?desde=2026-09-02T14:30:00Z"

{
  "pedidos": [ { /* ver formato abaixo */ } ],
  "quantidade": 1,
  "proximo_desde": "2026-09-02T14:52:07.113000+00:00"
}

O filtro é por última alteração, não por criação. Assim você recebe também o pedido antigo que mudou de estado — um cancelamento, por exemplo. Pedidos ainda aguardando pagamento e pedidos arquivados não aparecem.

Um pedido específico

O número é o mesmo que a loja vê na tela: 1001, 1002…

Formato do pedido

{
  "numero": 1001,
  "id": "65fea81c-b4c5-455f-ba5f-750516e574ff",
  "status": "pending",
  "criado_em": "2026-08-29T01:04:12.885694+00:00",
  "atualizado_em": "2026-08-30T00:41:38.268293+00:00",
  "pagamento": { "forma": "pix", "pago": true },
  "valores": { "itens": 79.87, "entrega": 5.0, "total": 79.87 },
  "entrega": {
    "tipo": "platform",
    "endereco": "Rua das Flores, 120 - Centro - Lages/SC — apto 302"
  },
  "cliente": { "nome": "Maria Oliveira", "telefone": "(49) 99999-0000" },
  "itens": [
    {
      "nome": "Trio Coreano Crocante (Individual) + refri",
      "quantidade": 1,
      "preco_unitario": 79.87,
      "observacao": null
    }
  ],
  "observacoes": ""
}

Em entrega.tipo, platform significa que um entregador do Inksa vai retirar; own significa que a própria loja entrega.

Mudar o status

São os três passos da cozinha, nesta ordem:

pending  ──aceitar──▶  accepted  ──preparar──▶  preparing  ──pronto──▶  ready

Se a loja faz a própria entrega

Existe um quarto passo, e ele vale só para loja que entrega com gente dela. Nesse caso o fluxo continua depois do pronto:

ready  ──saiu-para-entrega──▶  delivering

Confirmar a entrega continua fora da API, inclusive na entrega própria: o cliente mostra um código de quatro dígitos e alguém da loja digita no aplicativo. Esse código é a única prova de que o pedido chegou, e é por isso que ele não vira uma chamada de API.

aceitar aceita um corpo opcional com a previsão de preparo:

curl -X POST -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"tempo_preparo_min": 25}' \
  .../pedidos/1001/aceitar

{ "ok": true, "numero": 1001, "status": "accepted" }

Chamar fora de ordem devolve 409 com o estado atual, para você decidir o que fazer:

{
  "erro": "transicao_invalida",
  "mensagem": "Pedido #1001 está em 'ready'. 'aceitar' só vale quando está em 'pending'.",
  "status_atual": "ready"
}

Estados possíveis

Os quatro últimos você lê, mas não escreve — veja o porquê no fim da página.

Cardápio

O envio cria ou atualiza: pode mandar o cardápio inteiro quantas vezes quiser sem duplicar nada. A reconciliação usa o ean quando existe e, na falta dele, o nome do item dentro daquela loja.

curl -X POST -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "teste": true,
    "itens": [
      {"nome":"Guaraná 2L","preco":"12,90","categoria":"Bebidas","ean":"7891234567890","estoque":40},
      {"nome":"Coxinha","preco":8.5,"categoria":"Salgados"}
    ]
  }' .../cardapio

{
  "ok": true, "teste": true,
  "recebidos": 2, "criados": 0, "atualizados": 0,
  "ignorados": [], "total_ignorados": 0
}

preco aceita 12,90, 12.90, "R$ 12,90" e 1.234,56. Centavos como número inteiro não são aceitos, por ser ambíguo demais.

estoque é opcional. Zero não some do cardápio: o item fica visível e marcado como indisponível, porque o cliente precisa saber que a loja trabalha com aquele produto. Sem o campo, o item fica disponível.

A Inksa dá baixa sozinha entre as suas sincronizações

Quando um pedido fecha, a Inksa desconta do estoque os itens vendidos; pedido cancelado devolve. Ao chegar a zero, o item sai da vitrine automaticamente e volta assim que houver saldo.

Isso existe por causa da janela entre duas sincronizações. Se você manda o catálogo de hora em hora e há uma unidade em estoque, sem a baixa dois clientes compram a mesma unidade e o segundo descobre na entrega.

Só é afetado o item que tem estoque definido. Item que nunca recebeu o campo continua com estoque nulo, e nulo significa “esta loja não controla quantidade” — nada é descontado e o item nunca sai da vitrine por essa razão. É o caso da maioria dos restaurantes.

Campo em branco não apaga o que já existe — em especial a descrição, que o lojista costuma caprichar no aplicativo e que quase nenhuma planilha de ERP carrega. Limite de 2.000 itens por chamada.

Erros

Todo erro devolve erro (código estável, para o seu switch) e mensagem (texto em português, que pode mudar). Trate pelo código, nunca pelo texto.

Limites de chamada

Passando disso, a resposta é 429. Perguntar por pedidos a cada 30 segundos usa 2 das 120 chamadas — há folga de sobra, e não há motivo para perguntar de segundo em segundo.

O que a versão 1 não faz, e por quê

Duas coisas ficaram de fora de propósito, e não por falta de tempo:

Cancelar pedido. Cancelar um pedido já pago dispara o estorno ao cliente, e essa regra vive num único lugar do nosso sistema. Abrir um segundo caminho para devolver dinheiro é o tipo de duplicação que cedo ou tarde paga em dobro ou não paga. O lojista cancela pelo aplicativo.

Marcar "entregue". Passa por um código de quatro dígitos que o cliente mostra — é o que prova que a entrega aconteceu. Uma rota de API que pulasse o código permitiria fechar um pedido sem entregar nada.

"Saiu para entrega" saiu desta lista e virou rota, mas só para loja com entrega própria — está logo acima, em Mudar o status. O motivo de estar fora era o código de entrega, e o código só existe quando quem entrega é o entregador da Inksa.

Se a sua integração precisar de algo que não está aqui, fale com a gente. Esta versão continua no ar mesmo quando existir uma versão 2: quando o formato mudar, nasce /v2 e você migra quando puder. Nada quebra no meio do movimento.