Skip to main content
Octofood is a Brazilian e-commerce platform built for food and beverage stores, covering online ordering, scheduled delivery, meal kits and subscriptions. Every Octofood store serves its own integration API from its own domain, and the connector reads the store’s customers, orders, products, subscriptions, store credits, abandoned carts and custom shipping ranges. Access to the API is issued per store by Octofood support and depends on your plan: it is not included in the Basic plan. If you do not have API credentials yet, ask Octofood support to enable the API for your store.

​
Configuring Octofood as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Octofood option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

Octofood authenticates every request with a webservice user and password issued for your store. These are not the same as your store panel login. To get them, contact Octofood support and ask them to enable the API and send you the webservice credentials. You will need three values:
  • Store address: the address of your own store, including https, for example https://minhaloja.com.br. Each Octofood store serves its API from its own domain, so this is your store’s address and not a shared Octofood address.
  • Webservice user: the API user issued by Octofood support.
  • Webservice password: the password issued together with the user.
If the connection is refused, check the store address first. It has to be the domain customers use to reach your store, with no path after it.
The following configurations are also available:
  • Initial sync date: The earliest date from which orders, customers, subscriptions and abandoned carts will be synced. Products, store credits and shipping ranges are always read in full.
  • Lookback (days): How many days before the last synced point each run re-reads, 30 by default. See the note on changed records below for why this matters.
Once you’re done, click Next.

​
2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data - which is good if, for example, you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data - which is good if, for example, you don’t want to have deleted data in your catalog.
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
How the extraction works

  • Orders, customers, subscriptions and abandoned carts are read through the API’s date-range filters and synced incrementally.
  • Products, store credits and shipping ranges have no date filter in the API and are read in full on every run. Store credits are read in full on purpose, because the remaining balance falls as the customer spends it.
  • Timestamps are returned by Octofood in the store’s local time, with no time zone attached. The connector keeps them exactly as the store sent them rather than assuming an offset. Calendar dates such as birthdays and delivery dates are kept as dates.
  • Numbers arrive as text, because the API answers in XML. Prices, quantities and identifiers are converted to numeric columns, and empty values become null. Nested structures such as order line items, extra addresses, subscription cycles and nutritional tables are stored as JSON text columns.
Changed records are only re-read inside the lookback window. The Octofood API can only filter by the date a record was created, not by when it last changed. An order’s status, a subscription’s cycles and a customer’s address all change after that date. Each run therefore re-reads the last few days again, controlled by the Lookback (days) setting. If your orders often change status long after they are placed, raise it so those changes are still picked up.
Records marked as imported disappear from the Octofood listings. Octofood lets an integration mark an order or a customer as imported, and a marked record stops being returned by the API. This connector never marks anything, it only reads. But if another integration on your store marks records as imported, those records become invisible to Nekt as well. If you already run an ERP integration over this same API, check this before treating the tables as complete.

​
Available streams

​
Fields by stream

Below you’ll find all available data streams from Octofood and their corresponding fields:
One row per customer registered in the store. Extra delivery addresses travel as a JSON column.Slug: customers
Primary key: cod_cliente
Replication: Incremental (data_cadastro)Fields:
  • cod_cliente - Unique identifier of the customer in the store
  • importado - Whether the record was already marked as imported by an integration: 0 = not imported, 1 = imported. Customers marked as imported stop appearing in this listing
  • status - Registration status of the customer, either ‘Ativo’ (active) or ‘Inativo’ (inactive)
  • nome - First name of the customer
  • sobrenome - Last name of the customer
  • responsavel - Name of the person responsible for the company, when the registration is a legal entity (CNPJ)
  • sexo - Gender of the customer: ‘f’ for female and ‘m’ for male
  • email - Email address of the customer
  • cnpj - Brazilian company tax identifier (CNPJ), present when the customer is a legal entity
  • cpf - Brazilian individual tax identifier (CPF), present when the customer is an individual
  • inscricao_estadual - State tax registration of the company
  • endereco - Street of the customer’s main address
  • numero - Street number of the main address
  • complemento - Address complement of the main address, such as apartment or block
  • bairro - Neighbourhood of the main address
  • cidade - City of the main address
  • estado - Two-letter Brazilian state code of the main address
  • cep - Postal code (CEP) of the main address, formatted as ‘99999-999’
  • telefone - Landline phone number of the customer
  • celular - Mobile phone number of the customer
  • como_conheceu - Answer to the store’s ‘how did you hear about us’ question
  • como_conheceu_texto - Free-text detail for the ‘how did you hear about us’ answer
  • data_cadastro - Date the customer registered in the store, used as the incremental replication key
  • data_nascimento - Date of birth of the customer
  • data_ultimo_pedido - Date of the customer’s most recent order
  • enderecos - Additional delivery addresses registered by the customer (JSON object holding a list of addresses, each with cod_endereco, titulo, responsavel, endereco, numero, complemento, bairro, cidade, estado and cep)
Store credit balances held by customers. Read in full on every run, because the remaining balance falls as the customer spends it.Slug: customer_credits
Primary key: cod_cliente, cod_pedido, data_inserido
Replication: Full tableFields:
  • cod_cliente - Unique identifier of the customer who holds the credit
  • cod_pedido - Identifier of the order that generated the credit. Documented as always present, but absent from some responses
  • nome - Full name of the customer who holds the credit
  • email - Email address of the customer who holds the credit
  • data_inserido - Date the credit was granted
  • data_validade - Date the credit expires
  • valor_credito - Remaining balance of the credit. This value decreases as the customer spends it
  • valor_credito_inicial - Original value of the credit when it was granted
One row per product left in a cart without an order being placed, not one row per cart.Slug: abandoned_carts
Primary key: cod_carrinho_abandonado
Replication: Incremental (data_inserido)Fields:
  • cod_carrinho_abandonado - Unique identifier of the abandoned cart entry
  • cod_cliente - Unique identifier of the customer who left the product in the cart
  • data_inserido - Timestamp the product was added to the cart, used as the incremental replication key. Expressed in the store’s local time, without a UTC offset
  • data_ultima_compra - Timestamp of the customer’s most recent order in the store, in the store’s local time
  • nome_cliente - Full name of the customer, as named in the specification’s field table
  • email_cliente - Email address of the customer, as named in the specification’s field table
  • nome - Full name of the customer, as returned by the specification’s own response example. Populated instead of nome_cliente on stores that follow the example
  • email - Email address of the customer, as returned by the specification’s own response example. Populated instead of email_cliente on stores that follow the example
  • descricao - Description of the product as it was added to the cart, including the chosen size or variation
  • produto_nome - Name of the product in the store catalogue
  • quantidade - Quantity of the product left in the cart
  • valor - Unit price of the product at the time it was added to the cart
  • codigo - Code of the product variation, also used as the product code when the product has a single variation
  • imagem - URL of the product image
One row per price variation of a product. A product sold in three sizes has three rows sharing the same product id, which is why the key is the pair. The nutritional table and the components of kits and dishes travel as JSON columns.Slug: products
Primary key: cod_produto, cod_valor
Replication: Full tableFields:
  • cod_produto - Unique identifier of the product in the store
  • cod_valor - Unique identifier of the product’s price variation. A product with several sizes or weights has one entry per variation
  • publicar - Whether the product is visible in the store: 0 = hidden, 1 = published
  • tipo - Type of the product: ‘produto’ (single product), ‘kit’ or ‘prato’ (dish)
  • nome - Name of the product
  • codigo - Store code or SKU of the product variation
  • url - URL of the product page in the store
  • url_imagem - URL of the product’s main image
  • desconto - Price of the product after discount
  • valor - Price of the product before discount
  • unidade - Unit the product is sold in: g (grams), ml (millilitre), l (litre), cx (box), pct (pack), um (unit) or tam (size)
  • unidade_valor - Amount of the unit the price refers to, for example 100 for a price per 100 grams
  • calorias - Calorie count of the kit or dish
  • descricao - Short description of the product. Returned only because this connector always requests the description fields
  • detalhamento - Full description of the product
  • descricao_nutricional - Free-text nutritional description of the product
  • seo_title - Page title used for search engine optimisation
  • seo_description - Meta description used for search engine optimisation
  • seo_robots - Robots directive for the product page, for example ‘noindex, nofollow’
  • seo_keywords - Keywords used for search engine optimisation
  • tabela_nutricional - Nutritional table of the product (JSON object with quant_por_porcao, the amount each value refers to, and the list of nutritional values, each with nome, quantidade and valor_diario)
  • produtos - Products that make up a kit or dish (JSON object holding a list, each entry with periodo, ordem, dia, nome, unidade, unidade_valor, codigo, cod_produto and cod_valor). Empty for a single product
One row per order, with the customer, delivery address, payment method and totals. Line items travel as a JSON column, including the products inside kits and dishes.Slug: orders
Primary key: cod_pedido
Replication: Incremental (data_pedido)Fields:
  • cod_pedido - Unique identifier of the order in the store, also used as the order number shown to the customer
  • cod_cliente - Unique identifier of the customer who placed the order
  • cpf - Brazilian individual tax identifier (CPF) of the customer
  • cnpj - Brazilian company tax identifier (CNPJ), when the order was placed by a legal entity
  • status - Current status of the order: Novo, Pendente, Pago, Enviado, Entregue, Impresso or Cancelado
  • status_data - Timestamp the current status was set, in the store’s local time without a UTC offset
  • status_descricao - Free-text description attached to the current status
  • data_programada - Date the order is scheduled to be delivered
  • hora_programada - Time or delivery window the order is scheduled for, as free text such as ‘08:00 / 18:00’
  • data_pedido - Timestamp the order was placed, used as the incremental replication key. Expressed in the store’s local time, without a UTC offset
  • portaria - Whether the order may be left at the building’s reception: ‘S’ for yes and ‘N’ for no. Only meaningful when the store enables the option at checkout
  • ent_responsavel - Name of the person who will receive the order at the delivery address
  • ent_endereco - Street of the delivery address
  • ent_numero - Street number of the delivery address
  • ent_complemento - Address complement of the delivery address
  • ent_bairro - Neighbourhood of the delivery address
  • ent_cidade - City of the delivery address
  • ent_estado - Two-letter Brazilian state code of the delivery address
  • ent_cep - Postal code (CEP) of the delivery address, formatted as ‘99999-999’
  • forma_entrega - Delivery method chosen for the order, such as ‘Correios PAC’, ‘Correios Sedex’, ‘Transportadora’, ‘Retirada no local’ or ‘Loggi’
  • codigo_pagamento - Numeric code of the payment method. For example 1 = Gateway Boleto, 2 = cash at the store, 7 = PayPal, 10 = Gateway Visa, 11 = Gateway Mastercard, 16 = Sodexo meal voucher
  • forma_pagamento - Human-readable description of the payment method
  • observacoes - Notes attached to the order by the customer
  • certificado - Code of the discount certificate applied to the order
  • valor_total - Value of the order before discounts and before shipping
  • valor_frete - Shipping charged on the order
  • valor_certificado - Value of the discount certificate applied, expressed as a negative number
  • valor_desconto - Discount applied to the order, expressed as a negative number
  • valor_troco - Change the customer expects to receive, for orders paid in cash on delivery
  • itens - Line items of the order (JSON object holding a list, each item with cod_item, cod_valor, codigo, descricao, quantidade, valor and valor_real; items that are kits or dishes also carry ‘produtos’, the products they contain, and ‘cardapio’, the menu breakdown by period and day)
One row per recurring subscription, with its plan, delivery settings and totals. Billing cycles travel as a JSON column.Slug: subscriptions
Primary key: cod_assinatura
Replication: Incremental (data_assinatura)Fields:
  • cod_assinatura - Unique identifier of the subscription in the store, also used as the subscription number
  • descricao - Description of the subscription plan, such as ‘Assinatura / Por mês / Entrega Quinzenal’
  • cod_cliente - Unique identifier of the subscribing customer
  • cpf - Brazilian individual tax identifier (CPF) of the customer
  • cnpj - Brazilian company tax identifier (CNPJ), when the subscriber is a legal entity
  • status - Current status of the subscription. Documented as Ativa, Pendente or Cancelada, but some stores return a numeric status code instead, so the value is kept as text
  • intervalo - Billing interval unit of the subscription: ‘semana’ (week), ‘mes’ (month) or ‘ano’ (year)
  • intervalo_contador - Number of interval units between charges. A monthly plan is intervalo ‘mes’ with intervalo_contador 1
  • data_assinatura - Timestamp the subscription was created, used as the incremental replication key. Expressed in the store’s local time, without a UTC offset
  • data_cancelamento - Timestamp the subscription was cancelled, in the store’s local time
  • data_proximo_cobranca - Timestamp of the next scheduled charge, in the store’s local time
  • entrega_dia - Day of the week the subscription is delivered. Only set for subscriptions configured with a physical delivery
  • entrega_frequencia - Delivery frequency of the subscription, such as ‘quinzenal’. Only set for subscriptions with a physical delivery
  • entrega_horario - Delivery time window of the subscription. Only set for subscriptions with a physical delivery
  • entrega_responsavel - Name of the person who will receive the delivery
  • entrega_endereco - Street of the delivery address
  • entrega_numero - Street number of the delivery address
  • entrega_complemento - Address complement of the delivery address
  • entrega_bairro - Neighbourhood of the delivery address
  • entrega_cidade - City of the delivery address
  • entrega_estado - Two-letter Brazilian state code of the delivery address
  • entrega_cep - Postal code (CEP) of the delivery address, formatted as ‘99999-999’
  • observacoes - Notes attached to the subscription
  • desconto_ciclos - Number of billing cycles that receive the discount
  • certificado - Code of the discount voucher applied to the subscription
  • valor_total - Value of the subscription before discounts and shipping
  • valor_certificado - Value of the discount voucher applied, expressed as a negative number
  • ciclos - Billing cycles of the subscription (JSON object holding a list, each cycle with ciclo, its status, valor, data_inicio, data_fim, data_pagamento and data_cobranca). Cycle status values are Pendente, Pago, Cancelado or a failed charge, and some stores return them as numeric codes
Postal code ranges configured for custom shipping rates.Slug: shipping_zip_codes
Primary key: cod_regiao
Replication: Full tableFields:
  • cod_regiao - Unique identifier of the shipping region in the store
  • local - Name of the location or city the postal code range covers
  • estado - Two-letter Brazilian state code of the range
  • cep_inicial - First postal code (CEP) of the range, formatted as ‘99999-999’
  • cep_final - Last postal code (CEP) of the range, formatted as ‘99999-999’
  • valor - Shipping price charged for this postal code range
  • valor_minimo - Minimum order value required for this postal code range