Nova API V1.0 · Referência
Referência da Nova API V1.0
Endpoints implementados na nova API externa da Takeat. Selecione um endpoint para consultar parâmetros, respostas e exemplos.
Endpoints
postEmitir ou renovar tokensSuporta duas formas de iniciar uma sessão:
- API key: envie a chave completa `tk_live_...` ou `tk_test_...` como
`api_key` com `grant_type=api_key`. Não informe `client_id` ou
`client_secret`.
- App instalável: envie o código recebido no callback, o client ID
público, a redirect URI exata e o `code_verifier` com
`grant_type=authorization_code`. O app não possui client secret.
O parâmetro `scope` restringe o token a um subconjunto dos escopos da
chave no grant `api_key`. A resposta contém um access token curto e um
refresh token rotativo. Para renovar uma sessão de API key, envie
somente o refresh token atual. Para um app instalável, envie o refresh
token atual e seu `client_id`. Sempre substitua o refresh token pelo
novo valor da resposta.
Alterar as permissões de um app instalável (adição ou remoção de escopos)
revoga todas as autorizações e tokens existentes, mantendo o client ID.
Códigos e refresh tokens anteriores retornam `invalid_grant`; os access
tokens anteriores deixam de acessar os recursos. Cada restaurante deve
repetir o consentimento com PKCE para obter tokens com as permissões atuais.
postRevogar um access tokenRevoga antecipadamente um access ou refresh token. A operação é
idempotente. Apps públicos `tk_app_...` enviam `client_id` e não possuem
client secret. Para encerrar todas as sessões de uma API key, revogue a
chave no AI Builders.
getConsultar cardápio publicadoRetorna as seções vendidas ao cliente, seus produtos e, opcionalmente,
os grupos de complementos. Com OAuth, exige o escopo `menu:read`; a
sessão do restaurante também é aceita sem escopos de integração.
O contrato remove registros excluídos, categorias de embalagem e
espelhos internos do iFood. Preços, disponibilidade e apresentação são
agrupados em objetos. `pricing.resolved.base` aplica a prioridade dos
preços do canal; `pricing.resolved.minimum` soma as escolhas obrigatórias.
Disponibilidade avalia canal, horários, esgotamento e escolhas válidas.
Não retorna objeto de restaurante nem aliases do contrato anterior.
Não substitui validação de checkout, abertura da loja ou capacidade de entrega.
getListar sessões de comandaRetorna comandas abertas e fechadas com contas, pedidos, pagamentos e
dados fiscais. O intervalo máximo é de três dias e as datas são UTC.
Com OAuth, exige o escopo `table-sessions:read`; a sessão do
restaurante também é aceita sem escopos de integração.
A resposta preserva o contrato publicado: chaves `snake_case`, valores
monetários como strings com escala e relações aninhadas.
`status_timings` sempre está presente e agrupa os horários persistidos
do ciclo do pedido. Etapas ainda não atingidas retornam `null`; a API
não infere transições ausentes nem calcula durações.
`bills[].buyer.delivery_address` é o destino selecionado pela sessão por
`buyer_delivery_address_id`, nunca um endereço arbitrário do cadastro do comprador.
Retorna null para sessões sem entrega, retirada, destino ausente ou de outro
restaurante; um comprador ausente também permanece null.
getListar métodos de pagamentoRetorna os métodos habilitados para o restaurante. Com OAuth, exige o
escopo `payment-methods:read`; a sessão do restaurante também é aceita.
getListar produtos por categoriaRetorna categorias e produtos no formato compatível com o API Legado,
incluindo `pdv_codes` e o objeto adicional `fiscal` em cada produto.
Com OAuth, exige o escopo `products:read`; a
sessão do restaurante também é aceita.
postCriar produtoCria um produto em uma categoria não removida do restaurante. Com OAuth,
exige `products:write`; a sessão do restaurante também é aceita. Não
existe exclusão de produtos nesta API.
Uma categoria indisponível pode receber produtos, mas não aparece no menu
com only_available=true. Envie preços como números, não strings.
Veja a [referência de campos](/externo/v1/campos-do-produto) para padrões
de criação e efeitos sobre preços, disponibilidade e esgotamento.
getConsultar produtoRequer products:read. Retorna um produto ativo do restaurante autorizado e sua versão updated_at.putEditar produtoAtualização parcial: campos ausentes permanecem intactos. Com OAuth,
exige `products:write`; a sessão do restaurante também é aceita.
null limpa descrição e preços opcionais; zero define preço zero.
Alterar o preço base não encerra uma promoção existente.
Consulte a [referência de campos](/externo/v1/campos-do-produto).
putEditar vários produtos atomicamenteRequer products:write ou sessão de restaurante. Corpo é um array de
1–100 edições parciais. IDs repetidos causam 400 duplicate_product_ids.
Qualquer falha impede todas as alterações. Zero é permitido nos preços.
expected_updated_at permite impedir a aplicação de uma revisão obsoleta.
Os campos têm os mesmos efeitos da edição individual; consulte a
[referência de campos](/externo/v1/campos-do-produto).
patchAlterar disponibilidade por canalAltera `available` (presencial) e/ou `available_in_delivery`
(delivery). Ao menos um campo é obrigatório. Com OAuth, exige
`products:write`; a sessão do restaurante também é aceita.
Os canais são independentes. Para marcar ou reverter esgotamento,
envie sold_off no PUT individual ou em lote, não nesta rota.
getListar complementos por categoriaRetorna categorias de complementos e seus itens no formato compatível
com o API Legado. Com OAuth, exige o escopo `complements:read`; a
sessão do restaurante também é aceita.
getConsultar complementoRequer complements:read ou sessão de restaurante. Tenant validado pelo restaurante autorizado. Consulte /externo/v1/gerenciar-complementos.putEditar complementoRequer complements:write ou sessão de restaurante. Tenant validado pelo restaurante autorizado. Consulte /externo/v1/gerenciar-complementos. Edição parcial; campos omitidos são preservados. expected_updated_at detecta revisões obsoletas; conflitos retornam 409. Bulk aplica 1–100 itens atomicamente na ordem recebida.putEditar vários complementos atomicamenteRequer complements:write ou sessão de restaurante. Tenant validado pelo restaurante autorizado. Consulte /externo/v1/gerenciar-complementos. Edição parcial; campos omitidos são preservados. expected_updated_at detecta revisões obsoletas; conflitos retornam 409. Bulk aplica 1–100 itens atomicamente na ordem recebida.patchAlterar disponibilidade por canalRequer complements:write ou sessão de restaurante. Tenant validado pelo restaurante autorizado. Consulte /externo/v1/gerenciar-complementos. Edição parcial; campos omitidos são preservados. expected_updated_at detecta revisões obsoletas; conflitos retornam 409. Bulk aplica 1–100 itens atomicamente na ordem recebida.getListar categorias de complementosEscopo complements:read, ou sessão autenticada do restaurante. Vínculos são compartilhados; todas as referências são validadas no restaurante e marca.postCriar categoria de complementosEscopo complements:write, ou sessão autenticada do restaurante. Vínculos são compartilhados; todas as referências são validadas no restaurante e marca.putAtualizar categoria de complementosEscopo complements:write, ou sessão autenticada do restaurante. Vínculos são compartilhados; todas as referências são validadas no restaurante e marca.postCriar complementoEscopo complements:write, ou sessão autenticada do restaurante. Vínculos são compartilhados; todas as referências são validadas no restaurante e marca.getListar clientes do Clube de FidelidadeRetorna uma página de clientes do Clube. Com OAuth, exige o escopo
`clube:read`; a sessão do restaurante também é aceita. O restaurante
precisa ter o Clube configurado.
getListar lançamentos financeirosReplica os lançamentos da Área do Gestor, com pais e itens aninhados,
totais do período e página fixa de 100. Com OAuth, exige
`financial:read`; a sessão do restaurante também é aceita.
getListar insumosRegistros não cancelados do restaurante, ordenados por nome e por ID
em empates. Com OAuth exige `inputs:read`; aceita também a sessão
do restaurante. Página fixa de 100 registros; não permite escrita.
Quantidades mantêm o texto e os valores monetários têm duas casas decimais.
Valores inválidos já armazenados preservam a string NaN do PostgreSQL.
getListar produtos intermediáriosRegistros não cancelados do restaurante, ordenados por nome e por ID
em empates. Com OAuth exige `intermediaries:read`; aceita também a sessão
do restaurante. Página fixa de 100 registros; não permite escrita.
Quantidades mantêm o texto e os valores monetários têm duas casas decimais.
Valores inválidos já armazenados preservam a string NaN do PostgreSQL.
getListar marcas do restauranteOAuth exige brands:read; também aceita sessão autenticada de restaurante. Retorna marcas não excluídas, ativas ou inativas, ordenadas por padrão primeiro, nome e id. Não expõe credenciais fiscais nem cursor de distribuição.getListar NF-e recebidasOAuth exige nfe-received:read; também aceita sessão autenticada de restaurante. Somente notas autorizada e sem cancelamento local, por emissão crescente e id. Intervalo máximo de 92 dias. Array completo, sem paginação; divida intervalos muito grandes. Não inclui transferências de estoque nem solicita manifestação. Valores locais podem diferir da consulta atual do detalhe.getConsultar detalhe de NF-e recebidaOAuth exige nfe-received:read; também aceita sessão autenticada de restaurante. Consulta a Focus no servidor usando a marca vinculada ou padrão quando a nota não possui marca. Não modifica a nota nem manifesta. Usa timeout de 15 segundos e resposta máxima de 5 MiB. Nota resumida pode retornar invoice/protocol null. Campos locais de correção, cancelamento e referências continuam sendo snapshots locais. Erros do provedor não são expostos.