Especificação

Padrão de arquivos

Dois arquivos CSV alimentam a maria.supply: a carteira de pedidos (enviada todo dia útil) e o cadastro de e-mails de fornecedores (enviado quando houver atualização). Esta página descreve o formato exato que esperamos.

Regras gerais de formato (valem para os dois arquivos)

Arquivo CSV com cabeçalho na primeira linha. Os nomes das colunas podem vir em maiúsculas ou minúsculas (ex.: Ticket e ticket são equivalentes) — mas devem seguir a grafia das tabelas abaixo.
Delimitador , (vírgula) ou ; (ponto e vírgula) — detectado automaticamente pela primeira linha. Não misture os dois no mesmo arquivo.
Codificação UTF-8 (com ou sem BOM).
Campos que contêm o delimitador, aspas ou quebra de linha devem vir entre aspas duplas; aspas internas são escapadas duplicando ("").
Linhas totalmente vazias são ignoradas.

Formatos de data aceitos

As colunas de data aceitam dois formatos: ISO (2026-02-05, preferido — com ou sem hora) ou serial do Excel (46058). Qualquer outro formato — inclusive 05/02/2026 — é tratado como data vazia, e o pedido pode ficar de fora dos disparos. Datas inexistentes (ex.: 2026-02-31) também são descartadas.

1 · Carteira de pedidos

Enviada todo dia útil, antes das 14:00 UTC, para o diretório de integração do seu ambiente:

Local e nome do arquivo

<seu-ambiente>/pedidos/<yyyy-mm-dd>.csv

Exemplo: acme/pedidos/2026-07-16.csv

O prefixo <seu-ambiente> é o identificador da sua operação, informado durante o onboarding.

O nome do arquivo é a data de referência do processamento (formato yyyy-mm-dd). A esteira procura exatamente o arquivo do dia — um arquivo com data errada não é processado.

Colunas

Uma linha por item de pedido. Colunas marcadas com Sim* são obrigatórias em contextos específicos, descritos na própria linha.

Coluna	Tipo	Obrigatória	Descrição
cod_fornecedor	número	Sim	Código do fornecedor. Linhas sem código não geram cadastro nem pedido — o nome cai na lista de "fornecedores não encontrados" do processamento.
desc_fornecedor	texto	Sim	Razão social / nome do fornecedor. Usado no assunto e no corpo dos e-mails.
cnpj_fornecedor	texto	Não	CNPJ do fornecedor.
cod_pedido	número	Sim	Número do pedido de compra. Sem ele a linha não gera pedido.
ticket	número	Não	Número do ticket de agendamento. 0 ou vazio significa "sem ticket".
flag_agendamento	texto	Sim	Define o fluxo do pedido. Valores aceitos: `agendado` ou `sem agenda` (maiúsculas/minúsculas indiferentes).
data_pedido	data	Sim	Data de emissão do pedido. Início da cadência de cobrança.
data_recebimento_previsto	data	Sim*	Previsão de recebimento. *Obrigatória para pedidos sem agenda: sem ela a cobrança nunca dispara.
data_agendamento	data	Sim*	Data agendada da entrega. *Obrigatória para pedidos agendados: é a partir dela que o lembrete é disparado (3 dias antes).
data_atualizacao	data	Não	Última atualização da linha na origem.
prazo_entrega	número	Sim*	Prazo de entrega em dias. *Usado para calcular a frequência da cadência de cobrança dos pedidos sem agenda.
qtde_pedido_pendente	número	Não	Quantidade pendente do pedido de compra.
local_entrega	texto	Não	Unidade / centro de distribuição. Os pedidos são agrupados por esse campo dentro do e-mail.
responsavel_pedido	texto	Não	Comprador/responsável interno pelo pedido.
status_prazo	texto	Não	Situação do pedido em relação ao prazo (ex.: no prazo, vencido).
qtde_dias_vencido	número	Não	Dias em atraso, quando aplicável.
cod_item	texto	Sim*	Código do item. *Necessário para registrar o item do pedido (a chave do item é pedido + cod_item).
cod_ref_item	texto	Não	Código de referência do item.
desc_item	texto	Não	Descrição do item.
embalagem_compra	texto	Não	Embalagem de compra.
origem	texto	Não	Origem do item.
ciclo_atual	texto	Não	Ciclo atual do item.
ciclo_proximo	texto	Não	Próximo ciclo do item.
curva_venda_bruta_item	texto	Não	Curva de venda bruta do item (classificação supply).
pontos_ruptura	número	Não	Pontos em ruptura. Junto com `pontos_ativos` gera o percentual de ruptura (`pontos_ruptura ÷ pontos_ativos × 100`).
pontos_ativos	número	Não	Pontos de venda ativos do item.
email_analista	e-mail	Sim*	*Ao menos um dos três e-mails comerciais deve estar preenchido — sem nenhum, o fornecedor não recebe notificação.
email_gerente_comercial	e-mail	Sim*	E-mail do gerente comercial responsável.
email_assistente_comercial	e-mail	Sim*	E-mail do assistente comercial responsável.

Use exatamente os nomes da tabela acima

Os nomes abreviados das primeiras versões do layout (cnpj_forn, data_receb_prev, ptos_rupt, …) não são mais aceitos: a coluna é tratada como ausente e o valor fica vazio. O de/para completo está no changelog.

Como as linhas viram registros

Fornecedores são únicos por cod_fornecedor.
Pedidos são únicos por cod_pedido + cod_fornecedor — em linhas repetidas, vale a primeira.
Tickets são únicos por ticket + cod_fornecedor; ticket = 0 é ignorado.
Itens são únicos por cod_pedido + cod_item.

Exemplo mínimo

acme/pedidos/2026-07-16.csv

cod_fornecedor;desc_fornecedor;cnpj_fornecedor;cod_pedido;ticket;flag_agendamento;data_pedido;data_recebimento_previsto;data_agendamento;prazo_entrega;local_entrega;cod_item;desc_item;email_analista;email_gerente_comercial;email_assistente_comercial
10234;ALIMENTOS BOA MESA LTDA;12345678000190;557201;88412;agendado;2026-07-01;2026-07-20;2026-07-19;15;CD SAO PAULO;40021;ARROZ TIPO 1 5KG;analista@acme.com.br;gerente@acme.com.br;assistente@acme.com.br
10234;ALIMENTOS BOA MESA LTDA;12345678000190;557202;0;sem agenda;2026-07-10;2026-07-25;;12;CD SAO PAULO;40022;FEIJAO PRETO 1KG;analista@acme.com.br;;

2 · Cadastro de e-mails de fornecedores

Enviado sempre que houver atualização de contatos. Qualquer CSV colocado no prefixo abaixo dispara a atualização automaticamente:

Local do arquivo

<seu-ambiente>/emails/*.csv

Exemplo: acme/emails/emails-fornecedores.csv

Coluna	Tipo	Obrigatória	Descrição
cod_fornecedor	número	Sim	Código do fornecedor (mesmo código da carteira de pedidos).
email	e-mail	Sim	E-mail(s) do fornecedor. Vários endereços podem ser informados separados por `;`.
desc_fornecedor	texto	Não	Nome do fornecedor.

Linhas sem cod_fornecedor ou sem email são ignoradas.
Se o mesmo fornecedor aparecer mais de uma vez, a última linha prevalece.
A atualização só altera o e-mail de fornecedores já existentes na base — o cadastro do fornecedor vem da carteira de pedidos.

Exemplo

acme/emails/emails-fornecedores.csv

cod_fornecedor;email;desc_fornecedor
10234;contato@boamesa.com.br;ALIMENTOS BOA MESA LTDA
20871;"vendas@sulfrios.com.br;faturamento@sulfrios.com.br";SUL FRIOS DISTRIBUIDORA

Vários e-mails para o mesmo fornecedor

Informe os endereços na mesma célula, separados por ; — nesse caso a célula precisa vir entre aspas duplas se o delimitador do arquivo também for ;, como em "vendas@x.com;faturamento@x.com".