Zé Delivery
Pedidos, catálogo, disponibilidade de loja, logística, relatórios financeiros e webhooks do Zé Delivery.
Authentication
This connector uses Token-based authentication.
info
Set up your connection in the Abstra Console before using it in your workflows.
How to use
Using the Smart Chat
Execute the action "CHOOSE_ONE_ACTION_BELOW" from my connector "YOUR_CONNECTOR_NAME" using the params "PARAMS_HERE".
Using the Web Editor
from abstra.connectors import run_connection_action
result = run_connection_action(
connection_name="your_connection_name",
action_name="your_action_name",
params={
"param1": "value1",
"param2": "value2"
})
Available Actions
This connector provides 37 actions:
| Action | Purpose | Parameters |
|---|---|---|
| get_orders_by_order_number | Objetivo Recuperar os detalhes de um pedido a partir do seu número na plataforma Zé Delivery. Quando usar Utilize este endpoint somente quando: - For necessário consultar o estado e dados completos de um pedido items, total, merchant, delivery, customer — conforme permissões. - Houver um orderNumber válido gerado pela plataforma. - O parceiro tiver autorização para ver os dados sensíveis aplicável somente se houver acordo legal. Quando NÃO usar Este endpoint não deve ser utiliz | orderNumber (string) |
| post_orders_by_order_number_confirm | Objetivo Confirmar/aceitar um pedido no sistema do Zé aceitação pelo estabelecimento/parceiro. Quando usar Utilize este endpoint somente quando: - O estabelecimento/parceiro confirma que irá preparar o pedido. - É necessário informar preparationTime, orderExternalCode ou createdAt adicionais opcionais. Quando NÃO usar Este endpoint não deve ser utilizado para: - Cancelar pedidos usar /requestCancellation ou /cancel. - Confirmar pedidos já confirmados sem validação verificar st | orderNumber (string) data required |
| post_orders_by_order_number_request_cancellation | Objetivo Solicitar o cancelamento ou rejeição de um pedido, informando o código de motivo apropriado. Quando usar Utilize este endpoint somente quando: - O estabelecimento não puder atender o pedido ex.: UNAVAILABLE_ITEM, RESTAURANT_WITHOUT_DELIVERY_PERSON etc.. - O pedido ainda estiver em status que permite requestCancellation conforme regras de negócio. Quando NÃO usar Este endpoint não deve ser utilizado para: - Cancelamentos feitos por entregador use endpoints de logística | orderNumber (string) data required |
| post_orders_by_order_number_cancel | Objetivo Cancelar um pedido em qualquer status fluxo administrativo/operacional. Quando usar Utilize este endpoint somente quando: - For necessário cancelar o pedido por motivos operacionais ex.: falta de estoque, operação com problema. - O parceiro tiver autorização para executar cancelamentos diretos. Quando NÃO usar Este endpoint não deve ser utilizado para: - Rejeição de pedido antes de confirmação sem usar os códigos corretos em requestCancellation conforme política/fluxo | orderNumber (string) data required |
| get_events_polling | Objetivo Expor eventos de alteração de pedidos CREATED, CONFIRMED, DISPATCHED, CANCELLED, CONCLUDED via polling. Quando usar Para sincronização assíncrona de eventos: consumir mudanças de status de pedidos. Quando o parceiro não usa webhook e prefere polling. Quando NÃO usar Não usar para consultas ad-hoc de detalhes do pedido chamar /orders/orderNumber para detalhes. Não usar sem informar x-polling-merchants header com os merchantIds. Importante Requer header x-polling-me | x-polling-merchants (array) required eventType (array) |
| post_events_acknowledgment | Objetivo Acknowledge — notificar a API que eventos foram consumidos para que não sejam retornados novamente no polling. Quando usar Após consumir com sucesso eventos obtidos por GET /events:polling, envie ack com lista de EventAcknowledgementInput. Quando NÃO usar Não usar para sinalizar falha de processamento ack indica consumo bem-sucedido. Importante Requer Authorization. Recebe array de objetos com id, orderId, eventType. Retorna 202 informando que vai ser processada a | data (array) required |
| patch_webhooks | Objetivo Registrar ou atualizar a configuração de webhook do cliente autenticado na Seller Public API: URL de entrega dos eventos, se o webhook está ativo e quais categorias de eventos o parceiro deseja receber. Quando usar Quando o parceiro optar por notificações enviadas pela plataforma para um endpoint próprio em substituição ao fluxo de polling. Quando NÃO usar Não usar apenas para ler a configuração atual — para isso utilize GET /webhooks. Este endpoint não entrega a fila d | data: { . endpoint (string) . active (boolean) . subscribedEvents (array) } (object) required |
| get_webhooks | Objetivo Consultar a configuração de webhook associada ao cliente autenticado na Seller Public API. Quando usar Para exibir ou auditar URL, estado ativo/inativo e inscrições de eventos em painéis ou ferramentas internas. Para confirmar se já existe webhook cadastrado antes de um PATCH /webhooks, ou para recuperar o hash quando a configuração já existia e o segredo ainda é o mesmo persistido na plataforma. Quando NÃO usar Não lista eventos como no GET - events:polling. Para criar | No parameters |
| post_merchants_by_merchant_id_availability | Objetivo Abrir ou fechar um estabelecimento operational availability no Zé. Quando usar Para operação de abertura operation: AVAILABLE ou fechamento operation: CLOSED do PDV com razão obrigatória quando CLOSED. Quando NÃO usar Não usar para alterar disponibilidade de produtos individuais use products/availability. Importante Body com operation enum AVAILABLE | CLOSED; reasons obrigatório quando CLOSED. Requer Authorization. Retornos: 200/422 conforme validação. mermaid se | merchantId (string) data required |
| post_merchants_by_merchant_id_products_items | Objetivo Criar POST um item de produto para um estabelecimento inclui price, images, category, tags. Quando usar POST: criar SKUs exclusivos do parceiro para o merchant catálogo externo/partner-managed. Quando NÃO usar Não usar para criar SKUs que pertencem ao catálogo padrão do Zé sem autorização. Evitar duplicar productId vs externalProductId — a regra do Swagger indica que exatamente um dos identificadores é obrigatório. Importante Regras de validação: exatamente um de | merchantId (string) data: { . externalProductId (string) . name (string) . description (string) . images (array) . price (object) . category (string) . tags (array) } (object) required |
| put_merchants_by_merchant_id_products_items | Objetivo Atualizar PUT um item de produto para um estabelecimento inclui price, images, category, tags. Quando usar PUT: atualizar metadados do item nome, descrição, preço, imagens. Quando NÃO usar Não usar para alterar SKUs que pertencem ao catálogo padrão do Zé sem autorização. Evitar duplicar productId vs externalProductId — a regra do Swagger indica que exatamente um dos identificadores é obrigatório. Importante Regras de validação: exatamente um de productId ou extern | merchantId (string) data: { . productId (integer) . externalProductId (string) . name (string) . description (string) . images (array) . price (object) . category (string) . tags (array) } (object) required |
| put_merchants_products_items | Objetivo Upsert em lote atualizar múltiplos produtos — sincronização inicial ou periódica de catálogo parceiro. Quando usar Onboarding inicial de catálogo exclusivo do parceiro ou sincronização de muitos SKUs. Quando NÃO usar Para atualizações unitárias frequentes usar endpoints unitários; não criar produtos no catálogo oficial do Zé. Importante Recurso assíncrono: retorna 202 para processamento; validações por item podem retornar 422. Requer Authorization. Limitações de t | data required |
| put_merchants_products_promos | Objetivo Atualizar promoções de produtos para múltiplos estabelecimentos em lote. Quando usar Aplicar/retirar campanhas/promos para vários merchants de uma só vez. Quando NÃO usar Para promoções que impactam catálogo padrão sem acordo; não usar para promoções ad-hoc sem campos obrigatórios. Importante Estrutura: array de ProductPromoInput. Regras: se isEnabled=true, percentage e scheduleType são obrigatórios, caso contrário não devem ser enviados. Deve ser usado productId | data (array) required |
| post_merchants_by_merchant_id_products_availability | Objetivo Atualizar disponibilidade on/off de um SKU do estabelecimento produto ou externalProductId. Quando usar Quando o parceiro precisa marcar um produto específico como disponível ou indisponível no PDV. Quando NÃO usar Para atualizar produtos do catálogo padrão do Zé aplicável somente a SKUs gerenciados pelo parceiro quando apropriado. Importante Body aceita productId integer ou externalProductId string e available boolean. Requer Authorization. Retorna 200 com objeto | merchantId (string) data: { . productId (integer) . externalProductId (string) . available (boolean) } (object) required |
| get_logistics_delivery_by_order_number | Objetivo Recuperar detalhes de entrega de um pedido nome do cliente, entregador, preços, pickupCode, endereço. Quando usar Utilize este endpoint somente quando: - For necessário realizar consultas operacionais sobre rota e dados do entregador para execução da entrega. - For preciso verificar o pickupCode para coleta do pedido no PDV. Quando NÃO usar Este endpoint não deve ser utilizado para: - Alterar o status de entrega do pedido use os endpoints POST do grupo Logistics. - Ob | orderNumber (string) |
| post_logistics_order_picked_by_order_number | Objetivo Informar que o entregador pegou o pedido no PDV marcar pickup. Quando usar Utilize este endpoint somente quando: - For necessário confirmar que o entregador recebeu fisicamente o pedido no ponto de venda. - O body obrigatório com o email do entregador estiver disponível. Quando NÃO usar Este endpoint não deve ser utilizado para: - Indicar chegada ao endereço do cliente ou entrega final — use /logistics/arrived/orderNumber ou /logistics/finishDelivery/orderNumber. - Re | orderNumber (string) data required |
| post_logistics_start_route_by_order_number | Objetivo Informar início de rota/coleta pelo entregador rota iniciada. Quando usar Utilize este endpoint somente quando: - O entregador iniciar a rota de entrega após coletar o pedido no PDV. - O body com o email do entregador estiver disponível. Quando NÃO usar Este endpoint não deve ser utilizado para: - Sinalizar chegada ao endereço do cliente — use /logistics/arrived/orderNumber. - Confirmar a entrega final — use /logistics/finishDelivery/orderNumber. Importante Requ | orderNumber (string) data required |
| post_logistics_arrived_by_order_number | Objetivo Informar que o pedido chegou ao destino entregador chegou no endereço do cliente. Quando usar Utilize este endpoint somente quando: - For necessário sinalizar a chegada do entregador ao endereço do cliente, antes da tentativa de entrega ou entrega final. - O body com o email do entregador estiver disponível. Quando NÃO usar Este endpoint não deve ser utilizado para: - Confirmar que a entrega foi concluída — use /logistics/finishDelivery/orderNumber. - Registrar outros | orderNumber (string) data required |
| post_logistics_validate_code_by_order_number | Objetivo Validar o código de entrega deliveryCode informado no momento da entrega ou retirada do pedido. Quando usar Utilize este endpoint somente quando: - For necessário verificar se o deliveryCode informado pelo entregador ou cliente é válido para o pedido em questão. Quando NÃO usar Este endpoint não deve ser utilizado para: - Autorização de pagamento ou verificação de identidade além da validação do código de entrega. - Confirmar a conclusão da entrega — use /logistics/fi | orderNumber (string) data required |
| post_logistics_finish_delivery_by_order_number | Objetivo Marcar o pedido como entregue finalizar rota e status do pedido. Quando usar Utilize este endpoint somente quando: - A entrega foi concluída com sucesso pelo entregador. - O body com o email do entregador estiver disponível; lat/long são opcionais para registro de geolocalização. Quando NÃO usar Este endpoint não deve ser utilizado para: - Cancelar ou reverter o status de entrega — use /logistics/cancel/orderNumber para cancelamentos pelo entregador. - Sinalizar etapa | orderNumber (string) data required |
| post_logistics_cancel_by_order_number | Objetivo Permitir que o entregador solicite o cancelamento do pedido por motivos operacionais ex.: NOT_FOUND, RISK_AREA. Quando usar Utilize este endpoint somente quando: - O entregador não conseguir completar a entrega por motivos documentados no enum de razões disponível. Quando NÃO usar Este endpoint não deve ser utilizado para: - Cancelamentos administrativos que não passaram pelo fluxo do entregador — use /orders/orderNumber/cancel conforme escopo e permissões do parceiro | orderNumber (string) data required |
| get_v2_merchants_by_merchant_id_menu_items | Objetivo Buscar itens do menu de um estabelecimento paginação e filtro por externalProductIds. Quando usar Para listar produtos expostos de um merchant paginação via page e pageSize. Quando NÃO usar Não usar para modificar itens; para detalhes completos do produto usar endpoints de produto. Importante Requer Authorization. pageSize tem limites min=5, max=30 e page padrão = 1 segundo Swagger. Schema de resposta: merchantItemsResponse. mermaid sequenceDiagram participant | merchantId (string) page (number) pageSize (number) externalProductIds (string) |
| get_merchants_by_merchant_id | Objetivo Recuperar informações do estabelecimento status, availability, basicInfo, idealPortfolio, etc. Quando usar Quando precisar do status operacional do PDV e metadados úteis para operação/decisões. Quando NÃO usar Não usar como substituto de integrações profundas de catálogo/WMS; dados são informativos. Importante Requer Authorization. Schema de resposta: MerchantInformationResponse. Campos como idealPortfolio fornecem métricas totalProducts, totalActiveProducts. mer | merchantId (string) |
| post_merchants_by_merchant_id_products_item_offer | Objetivo Atualizar/definir oferta price/discount de um item no estabelecimento. Quando usar Aplicar preço ou promoção em um item específico do merchant price + originalValue. Quando NÃO usar Para alterar o catálogo global do Zé ou preços de SKUs do catálogo padrão sem acordo. Importante Requer merchantId e price com value e originalValue value 0, originalValue ≥ value. Requer Authorization. Retorna 202 quando processado. mermaid sequenceDiagram participant Parceiro as | merchantId (string) data: { . productId (string) . externalProductId (string) . price (object) } (object) required |
| get_merchants_by_merchant_id_kpis | Objetivo Permitir que o integrador consulte, de forma programática, os principais KPIs operacionais de um PDV seller para utilização em dashboards próprios, monitoramento de performance e automações. O endpoint fornece métricas consolidadas por período granularidade e data de referência, retornando indicadores estruturados por grupo. Quando usar Utilize este endpoint somente quando: O integrador precisar consultar KPIs consolidados de um PDV específico. For necessário alimentar dashbo | merchantId (string) granularity (string) referenceDate (string) |
| get_merchants_by_merchant_id_reimbursements_orders_summaries | Objetivo Essa consulta faz parte do grupo de 3 relatórios financeiros de repasses do Zé aos estabelecimentos que operam conosco: 1. Repasses calculados por pedido 2. Repasses de incentivos operacionais semanais 3. Repasses de pagamentos manuais Essa consulta retorna, de forma paginada, o item 1: o resumo dos repasses financeiros diretamente calculados por pedido, e atrelados a um estabelecimento merchantId em um período financeiro. Os valores retornados por pedido são: - Markup: markup n | merchantId (string) startDate (string) required endDate (string) required page (integer) pageSize (integer) orderNumber (string) |
| get_merchants_by_merchant_id_reports_operational_incentives | Objetivo Essa consulta faz parte do grupo de 3 relatórios financeiros de repasses do Zé aos estabelecimentos que operam conosco: 1. Repasses calculados por pedido 2. Repasses de incentivos operacionais semanais 3. Repasses de pagamentos manuais Essa consulta retorna o item 2: o resumo dos repasses de incentivos operacionais semanais apurados para um estabelecimento merchantId em uma semana ISO específica. Incentivos operacionais são valores repassados ao estabelecimento quando há apur | merchantId (string) isoYear (integer) required isoWeek (integer) required |
| get_merchants_by_merchant_id_reports_manual_payments | Objetivo Essa consulta faz parte do grupo de 3 relatórios financeiros de repasses do Zé aos estabelecimentos que operam conosco: 1. Repasses calculados por pedido 2. Repasses de incentivos operacionais semanais 3. Repasses de pagamentos manuais Essa consulta retorna, de forma paginada, o item 3: os pagamentos manuais lançados para um estabelecimento merchantId em um período financeiro. O intervalo informado em startDate e endDate é convertido em semanas ISO fechadas, e a resposta agrupa o | merchantId (string) startDate (string) required endDate (string) required page (integer) pageSize (integer) |
| get_merchants_by_merchant_id_orders_history | Objetivo Consultar, de forma paginada, o histórico de pedidos finalizados de um estabelecimento merchantId em um determinado período. A resposta traz uma visão resumida de cada pedido — cliente, pagamento, valores, avaliação e histórico de status — adequada para construção de relatórios, dashboards e telas de consulta. Quando usar Utilize este endpoint somente quando: - For necessário listar pedidos já finalizados de um estabelecimento por exemplo, pedidos concluídos ou cancelados, d | merchantId (string) startDate (string) endDate (string) page (integer) pageSize (integer) sort (string) |
| post_orders_by_order_number_restore | Objetivo Reverter as alterações feitas nos itens de um pedido confirmado, restaurando a composição anteriormente vigente na plataforma, quando essa operação é suportada pelo estado atual do pedido. Quando usar Utilize este endpoint somente quando: - Já tiver sido aplicada uma atualização de itens no pedido e for necessário desfazê-la. - O pedido estiver em condições que permitem restauração segundo as regras de negócio expostas pela API. Quando NÃO usar Este endpoint não deve s | orderNumber (string) |
| put_orders_by_order_number_items | Objetivo Ajustar os itens de um pedido já confirmado, removendo produtos indisponíveis ou substituindo-os por alternativas equivalentes, sem alterar o restante do contrato público descrito no Swagger. Quando usar Utilize este endpoint somente quando: - O pedido estiver em status que permite edição de itens após a confirmação pelo estabelecimento conforme regras da plataforma. - For necessário registrar remoções ou substituições antes da preparação ou da operação logística subsequente | orderNumber (string) data: { . removedItems (array) . replacedItems (array) } (object) required |
| post_external_catalog_merchants_by_merchant_id_products_availability | Objetivo Atualizar a disponibilidade on/off de SKUs exclusivos criados pelo parceiro, destinados a uma vertical específica dentro do Zé Delivery. Quando usar Utilize este endpoint somente quando: - O SKU foi criado pelo parceiro via integração. - O SKU não existe no catálogo padrão do Zé. - O produto será consumido exclusivamente dentro da vertical associada a esta integração. Quando NÃO usar Este endpoint não deve ser utilizado para: - Produtos do catálogo padrão do Zé. - SKU | merchantId (string) data: { . productId (string) . externalCode (string) . available (boolean) } (object) required |
| put_external_catalog_merchants_by_merchant_id_options_by_external_code_price | Objetivo Atualizar o preço de uma option variante/topping pertencente a um SKU exclusivo do catálogo externo, identificado por externalCode. Quando usar Utilize este endpoint somente quando: - A option variante pertence a um SKU criado via integração externa. - O parceiro precisa ajustar preços de variantes/toppings gerenciadas no catálogo externo. Quando NÃO usar Este endpoint não deve ser utilizado para: - Atualizar preços de produtos do catálogo padrão do Zé. - Atualizações | merchantId (string) externalCode (string) data: { . price (number) } (object) required |
| put_external_catalog_merchants_by_merchant_id_products_by_external_code_price | Objetivo Atualizar o preço de venda de um SKU exclusivo criado pelo parceiro, identificado por externalCode. Quando usar Utilize este endpoint somente quando: - O SKU foi criado via integração externa e não existe no catálogo oficial do Zé. - For necessário ajustar o preço de venda do SKU em produção. Quando NÃO usar Este endpoint não deve ser utilizado para: - Atualizar preços de SKUs do catálogo padrão do Zé. - Alterar preços de itens que são compartilhados entre verticais s | merchantId (string) externalCode (string) data: { . price (number) . fullPrice (number) } (object) required |
| put_external_catalog_catalog_products | Objetivo Realizar upsert criação/atualização em lote do catálogo exclusivo do parceiro — sincronização em lote de SKUs destinados à vertical da integração. Quando usar Utilize este endpoint somente quando: - For necessário fazer onboarding inicial do catálogo exclusivo do parceiro. - Realizar sincronizações periódicas de muitos SKUs bulk criados pelo parceiro. - O catálogo enviado refere-se exclusivamente a produtos que não existem no catálogo oficial do Zé. Quando NÃO usar Est | data: { . merchantId (string) . brandId (integer) . externalProductId (string) . title (string) . description (string) . images (array) . price (object) . category (string) . tags (array) . optionGroups (array) } (object) required |
| post_external_catalog_merchants_by_merchant_id_options_availability | Objetivo Controlar a disponibilidade granular on/off de options variantes/toppings de SKUs exclusivos do parceiro. Quando usar Utilize este endpoint somente quando: - For necessário marcar uma option como disponível ou indisponível para um merchant específico. - A option pertence a um SKU gerenciado no catálogo externo. Quando NÃO usar Este endpoint não deve ser utilizado para: - Controlar availability de opções que pertencem a produtos do catálogo padrão do Zé. - Controlar op | merchantId (string) data: { . optionId (string) . available (boolean) } (object) required |
| custom | Call any endpoint of the connected service while reusing the connection auth. Pass the full URL as _url. Other reserved keys: _method, _query, _body, _headers. Remaining params flow naturally — empty → GET, non-empty → POST JSON body. | _url (string) required _method (string) _query (object) _body _headers (object) |
Webhook Events
This connector emits 1 event back to your workflow. To receive one, create a hook whose path is <connection-name>/<event> — the connection name you configured plus the event from the table below.
| Event | Description |
|---|---|
| order-events | Notificações do ciclo de vida do pedido criação, confirmação, cancelamento e atualizações de status/logística. |