Referência da API · versão 1.0.0

API do Prodio

Leia e grave os dados da sua fábrica a partir do sistema da sua empresa.

openapi.yaml openapi.json Guia passo a passo na Central de ajuda

Endereço

https://api.prodio.com.br — Produção. Os caminhos já levam o /v1.

A API do Prodio deixa o sistema da sua empresa (ERP, loja, planilha automatizada, BI) ler e gravar os mesmos dados que você vê nas telas. O endereço é https://api.prodio.com.br/v1, as respostas são JSON UTF-8 em português e o acesso é por um token da empresa, criado em Configurações › API por um administrador.

Versão. A versão 1.0.0 deste documento acompanha a rota /v1. Mudança aditiva (campo novo, rota nova, valor novo num enum) não muda a versão da API: ignore os campos que não conhece. Quebra de compatibilidade vira /v2.

Autenticação. Cabeçalho Authorization: Bearer prodio_live_… (token de 55 caracteres). Token na URL é recusado com 400 token_na_url. Cada rota exige o escopo indicado em x-prodio-escopo (qualquer = qualquer token); :escrever inclui :ler do mesmo recurso. custos:ler libera os campos em reais; sem ele eles vêm null e o resto da resposta continua igual.

Limites. 120 chamadas por minuto por token e 300 por minuto por empresa, em janela fixa de 1 minuto. Acima disso 429 limite_excedido com Retry-After (segundos). Toda resposta autenticada traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (instante Unix em segundos). Toda resposta traz X-Request-Id: cite-o ao pedir suporte.

Paginação e leitura incremental. Toda lista devolve { "dados": [ … ], "proximo_cursor": "…" }. limite padrão 50, máximo 200; ordem estável crescente por atualizado_em (ou criado_em nos movimentos) com desempate por id. Repita exatamente o proximo_cursor recebido no parâmetro cursor; null = acabou; cursor adulterado → 400 cursor_invalido. atualizado_desde e desde são inclusivos (a última linha da carga anterior volta: trate-a como atualização). Há uma janela de estabilização de 30 segundos: a lista só devolve linhas alteradas há mais de meio minuto, para uma gravação longa nunca ficar para trás. GET …/{id} não tem janela.

Datas e instantes. Datas AAAA-MM-DD. A API devolve instantes em UTC (2026-10-03T17:05:00+00:00). Nos filtros você pode enviar com qualquer fuso (-03:00, Z, frações de segundo); sem fuso → 400 parametro_invalido. Na query string, o sinal + de um fuso positivo tem de ir codificado como %2B (atualizado_desde=2026-10-01T05:30:00%2B02:00): + cru chega como espaço e a API recusa com 400.

Erros. Sempre JSON { "erro": { "codigo", "mensagem", "campo"?, "id_requisicao" } }, em português, com código estável em snake_case (esquema Erro). Além dos documentados em cada operação: 405 metodo_nao_permitido (com Allow), 413 corpo_grande_demais, 415 tipo_nao_suportado, 409 conflito/chave_idempotencia_reutilizada, 422 validacao, 500 erro_interno e 503 banco_indisponivel (repita com espera exponencial).

CORS fechado. A API é servidor-a-servidor: nenhuma resposta traz Access-Control-*; não a chame do navegador. Guarde o token num cofre de segredos, um token por sistema, e revogue em Configurações › API quando o sistema sair do ar. Quem criou o token deixou de ser admin da empresa → 403 token_sem_dono.

Dúvidas: Central de ajuda do Prodio.

Autenticação

Authorization: Bearer prodio_live_… (55 caracteres)

Token da empresa criado em Configurações › API. Só no cabeçalho Authorization; nunca na URL.

Primeiro teste

Com o token criado em Configurações › API, confirme o acesso pelo terminal:

curl -sS https://api.prodio.com.br/v1/eu -H "Authorization: Bearer prodio_live_SEU_TOKEN"

A resposta é a de GET /v1/eu.

Empresa e token

Quem sou eu — a empresa do token e o próprio token. Funciona com qualquer token.

GET `/v1/eu`

Empresa e token da chamada

Escopo: qualquer (qualquer token da empresa)

Use para confirmar que o token está certo e descobrir a empresa, o fuso, a hora de virada do dia de produção e os escopos do token.

Respostas

200

Empresa e token.

Esquema: Eu

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "empresa": {
    "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000001",
    "nome": "Confecção Aurora",
    "cnpj": "11222333000181",
    "fuso": "America/Sao_Paulo",
    "hora_virada": "06:00",
    "sku_prefixo": "AU"
  },
  "token": {
    "prefixo": "prodio_live_Ab12Cd34",
    "nome": "Sistema de loja",
    "escopos": [
      "produtos:ler",
      "estoque:ler"
    ],
    "expira_em": "2027-10-03T03:00:00+00:00",
    "limite_por_minuto": 120,
    "limite_empresa_por_minuto": 300
  }
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
429
limite_excedido

Locais

Locais de estoque (fábrica, terceiros, depósitos).

GET `/v1/locais`

Locais de estoque

Escopo: qualquer (qualquer token da empresa)

Todos os locais da empresa, ordenados por nome, no envelope de lista. Não há paginação aqui — proximo_cursor é sempre null.

Respostas

200

Locais da empresa.

Esquema: PaginaDeLocais

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "dados": [
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000010",
      "nome": "Fábrica",
      "tipo": "fabrica",
      "ativo": true
    },
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000011",
      "nome": "Depósito da loja",
      "tipo": "deposito",
      "ativo": true
    }
  ],
  "proximo_cursor": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
429
limite_excedido

Produtos

Cadastro de produtos e kits, com custo da ficha.

GET `/v1/produtos`

Listar produtos

Escopo: produtos:ler

Produtos e kits da empresa, em ordem crescente de atualizado_em com desempate por id. Excluídos só com incluir_excluidos=true (vêm com excluido_em).

Parâmetros

Nome	Onde	Tipo	Descrição
`limite`	query	inteiropadrão `50` · de 1 a 200	Linhas por página. Padrão 50, máximo 200. Fora de 1..200 → 400 `parametro_invalido`.
`cursor`	query	textoformato `^[A-Za-z0-9_-]{1,400}$`	Página seguinte — repita exatamente o `proximo_cursor` recebido. Opaco (base64url); adulterado ou de outra lista → 400 `cursor_invalido`.
`atualizado_desde`	query	texto (date-time)	Só linhas com `atualizado_em` a partir deste instante, inclusive. ISO 8601 com fuso (`2026-10-01T00:00:00-03:00`, `2026-10-01T03:00:00Z`, frações de segundo aceitas); sem fuso, data impossível ou texto → 400 `parametro_invalido`. Fuso positivo: codifique o `+` como `%2B` na query string (`2026-10-01T05:30:00%2B02:00`), senão ele chega como espaço.
`sku`	query	texto1 a 200 caracteres	SKU exato (até 200 caracteres).
`status`	query	texto: `ativo` · `inativo`	Situação do produto.
`familia`	query	texto1 a 200 caracteres	Família exata, como está no cadastro.
`tipo`	query	texto: `produto` · `kit`	Produto simples ou kit.
`incluir_excluidos`	query	booleanopadrão `false`	`true` traz também os cadastros excluídos, com `excluido_em` preenchido, para o outro sistema apagar do lado dele. Excluir move o `atualizado_em`, então a exclusão aparece na leitura incremental.

Respostas

200

Página de produtos.

Esquema: PaginaDeProdutos

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "dados": [
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000101",
      "sku": "CAM-AZUL-M",
      "nome": "Camiseta básica azul M",
      "familia": "Camisetas",
      "atributos": {
        "cor": "Azul",
        "tamanho": "M"
      },
      "ean": "7891234567890",
      "ncm": "61091000",
      "status": "ativo",
      "tipo": "produto",
      "apelidos": [
        "CAMAZM-ML",
        "CAMAZM-SHOPEE"
      ],
      "tem_ficha": true,
      "peso_kg": 0.18,
      "peso_cubado_kg": 0.3,
      "largura_cm": 30,
      "altura_cm": 2,
      "comprimento_cm": 40,
      "ipi_pct": 0,
      "icms_pct": null,
      "importado": false,
      "variacao": {
        "grupo_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000100",
        "base": false,
        "eixos": [
          "cor",
          "tamanho"
        ]
      },
      "custo_ficha": 12.35,
      "custo_ficha_bruto": 13.1,
      "custo_manual": null,
      "criado_em": "2026-09-21T12:00:00+00:00",
      "atualizado_em": "2026-10-03T14:05:00+00:00",
      "excluido_em": null
    }
  ],
  "proximo_cursor": "eyJ1IjoiMjAyNi0xMC0wM1QxNDowNTowMC4wMDAwMDBaIiwiaSI6IjBhN2YxYzJlLTVkM2ItNGY4YS05ZTIxLTAwMDAwMDAwMDEwMSJ9"
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
429
limite_excedido

GET `/v1/produtos/{id}`

Obter um produto

Escopo: produtos:ler

O produto pelo id, inclusive excluído (com excluido_em). Id de outra empresa → 404, como id inexistente.

Parâmetros

Nome	Onde	Tipo	Descrição
`id`obrigatório	caminho	texto (uuid)	Id do registro (uuid). Id de outra empresa responde 404, igual a id inexistente.

Respostas

200

O produto.

Esquema: Produto

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000101",
  "sku": "CAM-AZUL-M",
  "nome": "Camiseta básica azul M",
  "familia": "Camisetas",
  "atributos": {
    "cor": "Azul",
    "tamanho": "M"
  },
  "ean": "7891234567890",
  "ncm": "61091000",
  "status": "ativo",
  "tipo": "produto",
  "apelidos": [
    "CAMAZM-ML",
    "CAMAZM-SHOPEE"
  ],
  "tem_ficha": true,
  "peso_kg": 0.18,
  "peso_cubado_kg": 0.3,
  "largura_cm": 30,
  "altura_cm": 2,
  "comprimento_cm": 40,
  "ipi_pct": 0,
  "icms_pct": null,
  "importado": false,
  "variacao": {
    "grupo_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000100",
    "base": false,
    "eixos": [
      "cor",
      "tamanho"
    ]
  },
  "custo_ficha": 12.35,
  "custo_ficha_bruto": 13.1,
  "custo_manual": null,
  "criado_em": "2026-09-21T12:00:00+00:00",
  "atualizado_em": "2026-10-03T14:05:00+00:00",
  "excluido_em": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
404
nao_encontrado
429
limite_excedido

Insumos

Cadastro de insumos (matéria-prima), com saldo e custo médio.

GET `/v1/insumos`

Listar insumos

Escopo: insumos:ler

Insumos da empresa, em ordem crescente de atualizado_em com desempate por id. saldo é a soma de todos os locais; por local use /v1/estoque/saldos.

Parâmetros

Nome	Onde	Tipo	Descrição
`limite`	query	inteiropadrão `50` · de 1 a 200	Linhas por página. Padrão 50, máximo 200. Fora de 1..200 → 400 `parametro_invalido`.
`cursor`	query	textoformato `^[A-Za-z0-9_-]{1,400}$`	Página seguinte — repita exatamente o `proximo_cursor` recebido. Opaco (base64url); adulterado ou de outra lista → 400 `cursor_invalido`.
`atualizado_desde`	query	texto (date-time)	Só linhas com `atualizado_em` a partir deste instante, inclusive. ISO 8601 com fuso (`2026-10-01T00:00:00-03:00`, `2026-10-01T03:00:00Z`, frações de segundo aceitas); sem fuso, data impossível ou texto → 400 `parametro_invalido`. Fuso positivo: codifique o `+` como `%2B` na query string (`2026-10-01T05:30:00%2B02:00`), senão ele chega como espaço.
`sku`	query	texto1 a 200 caracteres	SKU exato (até 200 caracteres).
`ativo`	query	booleano	Só ativos (`true`) ou só inativos (`false`).
`familia`	query	texto1 a 200 caracteres	Família exata, como está no cadastro.
`incluir_excluidos`	query	booleanopadrão `false`	`true` traz também os cadastros excluídos, com `excluido_em` preenchido, para o outro sistema apagar do lado dele. Excluir move o `atualizado_em`, então a exclusão aparece na leitura incremental.

Respostas

200

Página de insumos.

Esquema: PaginaDeInsumos

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "dados": [
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000201",
      "sku": "MAL-AZ",
      "nome": "Malha fio 30 azul",
      "familia": "Malhas",
      "ativo": true,
      "unidade_compra": "kg",
      "unidade_consumo": "m",
      "fator_conversao": 3.2,
      "ncm": "60062200",
      "minimo": 40,
      "lead_time_dias": 7,
      "fornecedor_padrao_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000301",
      "saldo": 130.5,
      "custo_medio": 31.2,
      "custo_medio_bruto": 34.8,
      "custo_referencia": null,
      "criado_em": "2026-09-21T12:00:00+00:00",
      "atualizado_em": "2026-10-03T13:40:12+00:00",
      "excluido_em": null
    }
  ],
  "proximo_cursor": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
429
limite_excedido

GET `/v1/insumos/{id}`

Obter um insumo

Escopo: insumos:ler

O insumo pelo id, inclusive excluído (com excluido_em). Id de outra empresa → 404.

Parâmetros

Nome	Onde	Tipo	Descrição
`id`obrigatório	caminho	texto (uuid)	Id do registro (uuid). Id de outra empresa responde 404, igual a id inexistente.

Respostas

200

O insumo.

Esquema: Insumo

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000201",
  "sku": "MAL-AZ",
  "nome": "Malha fio 30 azul",
  "familia": "Malhas",
  "ativo": true,
  "unidade_compra": "kg",
  "unidade_consumo": "m",
  "fator_conversao": 3.2,
  "ncm": "60062200",
  "minimo": 40,
  "lead_time_dias": 7,
  "fornecedor_padrao_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000301",
  "saldo": 130.5,
  "custo_medio": 31.2,
  "custo_medio_bruto": 34.8,
  "custo_referencia": null,
  "criado_em": "2026-09-21T12:00:00+00:00",
  "atualizado_em": "2026-10-03T13:40:12+00:00",
  "excluido_em": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
404
nao_encontrado
429
limite_excedido

Fornecedores

Cadastro de fornecedores. O contato (pessoa) não é exposto.

GET `/v1/fornecedores`

Listar fornecedores

Escopo: fornecedores:ler

Fornecedores da empresa, em ordem crescente de atualizado_em com desempate por id. O contato (nome e telefone de pessoa) e o e-mail de XML não são expostos.

Parâmetros

Nome	Onde	Tipo	Descrição
`limite`	query	inteiropadrão `50` · de 1 a 200	Linhas por página. Padrão 50, máximo 200. Fora de 1..200 → 400 `parametro_invalido`.
`cursor`	query	textoformato `^[A-Za-z0-9_-]{1,400}$`	Página seguinte — repita exatamente o `proximo_cursor` recebido. Opaco (base64url); adulterado ou de outra lista → 400 `cursor_invalido`.
`atualizado_desde`	query	texto (date-time)	Só linhas com `atualizado_em` a partir deste instante, inclusive. ISO 8601 com fuso (`2026-10-01T00:00:00-03:00`, `2026-10-01T03:00:00Z`, frações de segundo aceitas); sem fuso, data impossível ou texto → 400 `parametro_invalido`. Fuso positivo: codifique o `+` como `%2B` na query string (`2026-10-01T05:30:00%2B02:00`), senão ele chega como espaço.
`ativo`	query	booleano	Só ativos (`true`) ou só inativos (`false`).
`cnpj`	query	texto1 a 200 caracteres	CNPJ exato. Pontuação é ignorada (`11.222.333/0001-81` acha `11222333000181`); só casa 14 dígitos. Fornecedor pessoa física (CPF, 11 dígitos) nunca é achado por aqui.
`incluir_excluidos`	query	booleanopadrão `false`	`true` traz também os cadastros excluídos, com `excluido_em` preenchido, para o outro sistema apagar do lado dele. Excluir move o `atualizado_em`, então a exclusão aparece na leitura incremental.

Respostas

200

Página de fornecedores.

Esquema: PaginaDeFornecedores

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "dados": [
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000301",
      "nome": "Malharia Sul",
      "cnpj": "11222333000181",
      "regime": "simples",
      "uf": "SC",
      "lead_time_dias": 10,
      "condicao_pagamento": [
        30,
        60
      ],
      "ativo": true,
      "criado_em": "2026-09-21T12:00:00+00:00",
      "atualizado_em": "2026-09-30T09:12:40+00:00",
      "excluido_em": null
    }
  ],
  "proximo_cursor": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
429
limite_excedido

GET `/v1/fornecedores/{id}`

Obter um fornecedor

Escopo: fornecedores:ler

O fornecedor pelo id, inclusive excluído (com excluido_em). Id de outra empresa → 404.

Parâmetros

Nome	Onde	Tipo	Descrição
`id`obrigatório	caminho	texto (uuid)	Id do registro (uuid). Id de outra empresa responde 404, igual a id inexistente.

Respostas

200

O fornecedor.

Esquema: Fornecedor

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000301",
  "nome": "Malharia Sul",
  "cnpj": "11222333000181",
  "regime": "simples",
  "uf": "SC",
  "lead_time_dias": 10,
  "condicao_pagamento": [
    30,
    60
  ],
  "ativo": true,
  "criado_em": "2026-09-21T12:00:00+00:00",
  "atualizado_em": "2026-09-30T09:12:40+00:00",
  "excluido_em": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
404
nao_encontrado
429
limite_excedido

Fichas técnicas

Ficha técnica ativa de cada produto.

GET `/v1/fichas`

Listar fichas técnicas ativas

Escopo: fichas:ler

A ficha ativa de cada produto, em ordem crescente de atualizado_em (o instante em que a versão foi criada) com desempate pelo id da versão. Produto sem ficha ativa não aparece.

Parâmetros

Nome	Onde	Tipo	Descrição
`limite`	query	inteiropadrão `50` · de 1 a 200	Linhas por página. Padrão 50, máximo 200. Fora de 1..200 → 400 `parametro_invalido`.
`cursor`	query	textoformato `^[A-Za-z0-9_-]{1,400}$`	Página seguinte — repita exatamente o `proximo_cursor` recebido. Opaco (base64url); adulterado ou de outra lista → 400 `cursor_invalido`.
`atualizado_desde`	query	texto (date-time)	Só linhas com `atualizado_em` a partir deste instante, inclusive. ISO 8601 com fuso (`2026-10-01T00:00:00-03:00`, `2026-10-01T03:00:00Z`, frações de segundo aceitas); sem fuso, data impossível ou texto → 400 `parametro_invalido`. Fuso positivo: codifique o `+` como `%2B` na query string (`2026-10-01T05:30:00%2B02:00`), senão ele chega como espaço.
`produto_id`	query	texto (uuid)	Só a ficha deste produto.

Respostas

200

Página de fichas.

Esquema: PaginaDeFichas

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "dados": [
    {
      "produto_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000101",
      "versao": 3,
      "ativa": true,
      "atualizado_em": "2026-10-01T16:30:00+00:00",
      "linhas": [
        {
          "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000401",
          "tipo": "insumo",
          "insumo_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000201",
          "consumo": 0.85,
          "unidade": "m",
          "perda_pct": 0.03
        },
        {
          "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000402",
          "tipo": "produto",
          "componente_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000103",
          "consumo": 1,
          "unidade": "un",
          "perda_pct": 0
        }
      ],
      "custo": 12.3456
    }
  ],
  "proximo_cursor": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
429
limite_excedido

GET `/v1/fichas/{produto_id}`

Obter a ficha técnica de um produto

Escopo: fichas:ler

A ficha ativa do produto. Produto inexistente, de outra empresa ou sem ficha ativa → 404 nao_encontrado.

Parâmetros

Nome	Onde	Tipo	Descrição
`produto_id`obrigatório	caminho	texto (uuid)	Id do produto (uuid).

Respostas

200

A ficha ativa.

Esquema: Ficha

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "produto_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000101",
  "versao": 3,
  "ativa": true,
  "atualizado_em": "2026-10-01T16:30:00+00:00",
  "linhas": [
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000401",
      "tipo": "insumo",
      "insumo_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000201",
      "consumo": 0.85,
      "unidade": "m",
      "perda_pct": 0.03
    },
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000402",
      "tipo": "produto",
      "componente_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000103",
      "consumo": 1,
      "unidade": "un",
      "perda_pct": 0
    }
  ],
  "custo": 12.3456
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
404
nao_encontrado
429
limite_excedido

Estoque

Saldos por local e o ledger de movimentos.

GET `/v1/estoque/saldos`

Listar saldos por local

Escopo: estoque:ler

Uma linha por insumo e local com saldo, em ordem crescente de atualizado_em com desempate por insumo e local (o cursor carrega os três).

Parâmetros

Nome	Onde	Tipo	Descrição
`limite`	query	inteiropadrão `50` · de 1 a 200	Linhas por página. Padrão 50, máximo 200. Fora de 1..200 → 400 `parametro_invalido`.
`cursor`	query	textoformato `^[A-Za-z0-9_-]{1,400}$`	Página seguinte — repita exatamente o `proximo_cursor` recebido. Opaco (base64url); adulterado ou de outra lista → 400 `cursor_invalido`.
`atualizado_desde`	query	texto (date-time)	Só linhas com `atualizado_em` a partir deste instante, inclusive. ISO 8601 com fuso (`2026-10-01T00:00:00-03:00`, `2026-10-01T03:00:00Z`, frações de segundo aceitas); sem fuso, data impossível ou texto → 400 `parametro_invalido`. Fuso positivo: codifique o `+` como `%2B` na query string (`2026-10-01T05:30:00%2B02:00`), senão ele chega como espaço.
`insumo_id`	query	texto (uuid)	Só este insumo.
`local_id`	query	texto (uuid)	Só este local de estoque.

Respostas

200

Página de saldos.

Esquema: PaginaDeSaldos

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "dados": [
    {
      "insumo_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000201",
      "local_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000010",
      "saldo": 118.5,
      "unidade": "m",
      "custo_medio": 31.2,
      "valor": 3697.2,
      "atualizado_em": "2026-10-03T13:40:12+00:00"
    },
    {
      "insumo_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000201",
      "local_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000011",
      "saldo": 12,
      "unidade": "m",
      "custo_medio": 31.2,
      "valor": 374.4,
      "atualizado_em": "2026-10-03T13:40:12+00:00"
    }
  ],
  "proximo_cursor": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
429
limite_excedido

GET `/v1/estoque/movimentos`

Listar movimentos de estoque

Escopo: estoque:ler

O ledger de movimentos, em ordem crescente de criado_em com desempate por id; a janela de 30 s vale sobre criado_em. quantidade é o delta (negativo nas saídas). Quem fez o movimento não é exposto.

Parâmetros

Nome	Onde	Tipo	Descrição
`limite`	query	inteiropadrão `50` · de 1 a 200	Linhas por página. Padrão 50, máximo 200. Fora de 1..200 → 400 `parametro_invalido`.
`cursor`	query	textoformato `^[A-Za-z0-9_-]{1,400}$`	Página seguinte — repita exatamente o `proximo_cursor` recebido. Opaco (base64url); adulterado ou de outra lista → 400 `cursor_invalido`.
`desde`	query	texto (date-time)	Só linhas com `criado_em` a partir deste instante, inclusive. ISO 8601 com fuso (`-03:00`, `Z`); sem fuso → 400 `parametro_invalido`. Fuso positivo: codifique o `+` como `%2B` na query string.
`insumo_id`	query	texto (uuid)	Só este insumo.
`local_id`	query	texto (uuid)	Só este local de estoque.
`tipo`	query	texto: `entrada_nfe` · `entrada_manual` · `baixa_producao` · `ajuste` · `perda` · `estorno` · `saldo_inicial`	Tipo do movimento.

Respostas

200

Página de movimentos.

Esquema: PaginaDeMovimentos

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "dados": [
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000501",
      "insumo_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000201",
      "local_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000010",
      "tipo": "entrada_nfe",
      "quantidade": 160,
      "unidade": "m",
      "custo_unitario": 30.78,
      "referencia": "NF 1234",
      "motivo": null,
      "origem": "nfe",
      "criado_em": "2026-10-02T18:20:05+00:00"
    },
    {
      "id": "0a7f1c2e-5d3b-4f8a-9e21-000000000502",
      "insumo_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000201",
      "local_id": "0a7f1c2e-5d3b-4f8a-9e21-000000000010",
      "tipo": "ajuste",
      "quantidade": -3.5,
      "unidade": "m",
      "custo_unitario": 31.2,
      "referencia": null,
      "motivo": "Diferença de contagem",
      "origem": "api",
      "criado_em": "2026-10-03T13:40:12+00:00"
    }
  ],
  "proximo_cursor": null
}

400
Requisição malformada
401
Sem token válido
403
Token reconhecido, mas sem direito
429
limite_excedido

Erros

Todo erro responde JSON no esquema Erro, com código estável e mensagem em português.

400ErroRequisicao

Requisição malformada: parametro_invalido (parâmetro desconhecido, repetido, vazio ou fora do formato; campo diz qual), cursor_invalido, token_na_url ou corpo_invalido (escritas). Os parâmetros são lidos depois de autenticar, então a chamada conta no limite e a resposta traz os X-RateLimit-*; só token_na_url (recusado antes do token) sai sem eles.

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "erro": {
    "codigo": "parametro_invalido",
    "mensagem": "Parâmetro atualizado_desde inválido: instante ISO 8601 com fuso, como 2026-10-01T00:00:00-03:00.",
    "campo": "atualizado_desde",
    "id_requisicao": "8c1e0d2f-7a4b-4c6d-9e8f-000000000999"
  }
}

401NaoAutenticado

Sem token válido: token_ausente, token_invalido (fora do formato ou desconhecido), token_revogado ou token_vencido. Token revogado ou vencido é um token que o banco achou: a primeira recusa conta no limite dele e traz os X-RateLimit-*; repetir o mesmo token nos 60 s seguintes é recusado pelo cache do servidor, sem contar e sem os X-RateLimit-*. token_ausente e token_invalido saem sempre sem eles (nada para contar).

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "erro": {
    "codigo": "token_ausente",
    "mensagem": "Informe o token no cabeçalho Authorization: Bearer.",
    "id_requisicao": "8c1e0d2f-7a4b-4c6d-9e8f-000000000999"
  }
}

403SemPermissao

Token reconhecido, mas sem direito: escopo_insuficiente (falta o escopo da rota), empresa_suspensa, token_sem_dono (quem criou o token deixou de ser admin da empresa) ou sem_permissao. A chamada conta no limite.

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "erro": {
    "codigo": "escopo_insuficiente",
    "mensagem": "O token não tem o escopo necessário para esta rota.",
    "id_requisicao": "8c1e0d2f-7a4b-4c6d-9e8f-000000000999"
  }
}

404NaoEncontrado

nao_encontrado: id inexistente ou de outra empresa (a API não revela qual). rota_inexistente para caminho que não existe.

Cabeçalhos: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "erro": {
    "codigo": "nao_encontrado",
    "mensagem": "Não encontrado.",
    "id_requisicao": "8c1e0d2f-7a4b-4c6d-9e8f-000000000999"
  }
}

429LimiteExcedido

limite_excedido: mais de 120 chamadas no minuto com este token ou mais de 300 com a empresa. Espere o Retry-After e repita.

Cabeçalhos: X-Request-Id · Retry-After · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

{
  "erro": {
    "codigo": "limite_excedido",
    "mensagem": "Limite de chamadas por minuto excedido. Espere o Retry-After.",
    "id_requisicao": "8c1e0d2f-7a4b-4c6d-9e8f-000000000999"
  }
}

Cabeçalhos de resposta

Cabeçalho	Tipo	Descrição
`X-Request-Id`	texto (uuid)	Id desta requisição (uuid). Vem em toda resposta; cite-o ao pedir suporte.
`X-RateLimit-Limit`	inteiro	Limite de chamadas por minuto do token (120).
`X-RateLimit-Remaining`	inteiro	Chamadas que ainda cabem nesta janela de 1 minuto.
`X-RateLimit-Reset`	inteiro	Instante Unix (segundos) em que a janela reinicia.
`Retry-After`	inteiro	Segundos a esperar antes de repetir a chamada.
`Idempotency-Replayed`	texto: `true`	`true` quando a resposta é a repetição de uma escrita anterior com a mesma `Idempotency-Key` e o mesmo corpo (nada foi gravado de novo). Ausente nas demais respostas.

Esquemas

Chave em negrito vem sempre na resposta (ou é obrigatória no corpo); as demais podem faltar.

Erro

Envelope de todo erro da API. codigo é estável; mensagem é em português e pode mudar; campo aponta o parâmetro, cabeçalho ou chave do corpo recusado.

Chave	Tipo	Descrição
`erro`	objeto
`erro.codigo`	texto: `corpo_invalido` · `cursor_invalido` · `parametro_invalido` · `token_na_url` · `token_ausente` · `token_invalido` · `token_revogado` · `token_vencido` · `escopo_insuficiente` · `empresa_suspensa` · `token_sem_dono` · `sem_permissao` · `nao_encontrado` · `rota_inexistente` · `metodo_nao_permitido` · `conflito` · `chave_idempotencia_reutilizada` · `corpo_grande_demais` · `tipo_nao_suportado` · `validacao` · `limite_excedido` · `erro_interno` · `banco_indisponivel`
`erro.mensagem`	texto
`erro.campo`	texto	Parâmetro, cabeçalho ou chave do corpo (`itens[2].qtd`) a que o erro se refere.
`erro.id_requisicao`	texto (uuid)	O mesmo valor do cabeçalho `X-Request-Id`.

Eu

A empresa do token e o próprio token (GET /v1/eu).

Chave	Tipo	Descrição
`empresa`	objeto
`empresa.id`	texto (uuid)
`empresa.nome`	texto
`empresa.cnpj`	texto	Só dígitos.
`empresa.fuso`	texto	Fuso IANA da empresa (`America/Sao_Paulo`). As respostas da API vêm em UTC; este é o fuso para interpretar o dia de produção.
`empresa.hora_virada`	texto	Hora (`HH:MM`) em que vira o dia de produção, no fuso da empresa.
`empresa.sku_prefixo`	texto	Prefixo do SKU automático e das etiquetas.
`token`	objeto
`token.prefixo`	texto	Os 20 primeiros caracteres do token (`prodio_live_` + 8), como aparecem em Configurações › API.
`token.nome`	texto
`token.escopos`	lista de texto
`token.expira_em`	texto \| nulo (date-time)	`null` = sem validade.
`token.limite_por_minuto`	inteiro	Chamadas por minuto deste token (120).
`token.limite_empresa_por_minuto`	inteiro	Chamadas por minuto somando todos os tokens da empresa (300).

Local

Chave	Tipo	Descrição
`id`	texto (uuid)
`nome`	texto
`tipo`	texto: `fabrica` · `terceiro` · `deposito`
`ativo`	booleano

Produto

Produto ou kit. Percentuais como fração (0.05 = 5 %). Campos em reais exigem custos:ler. Toda chave vem sempre (com null quando não há valor).

Chave	Tipo	Descrição
`id`	texto (uuid)
`sku`	texto	Letras, números e hífen, até 40.
`nome`	texto
`familia`	texto \| nulo
`atributos`	objeto	Atributos livres do cadastro (`cor`, `tamanho`…).
`ean`	texto \| nulo
`ncm`	texto \| nulo	8 dígitos.
`status`	texto: `ativo` · `inativo`
`tipo`	texto: `produto` · `kit`
`apelidos`	lista de texto	SKUs externos (De-Para dos hubs), em ordem alfabética.
`tem_ficha`	booleano	Existe uma versão ativa da ficha técnica.
`peso_kg`	número \| nulo
`peso_cubado_kg`	número \| nulo
`largura_cm`	número \| nulo
`altura_cm`	número \| nulo
`comprimento_cm`	número \| nulo
`ipi_pct`	número \| nulo	Fração (`0.05` = 5 %).
`icms_pct`	número \| nulo	Fração (`0.05` = 5 %).
`importado`	booleano
`variacao`	objeto \| nulo	`null` em produto sem grupo de variação. `base: true` no produto que encabeça o grupo (`grupo_id` igual ao próprio `id`).
`variacao.grupo_id`	texto (uuid)
`variacao.base`	booleano
`variacao.eixos`	lista de texto
`custo_ficha`	número \| nulo	Custo calculado pela ficha ativa, em reais, arredondado a 2 casas (a mesma conta da tela de fichas). Exige `custos:ler`; `null` também quando não há ficha.
`custo_ficha_bruto`	número \| nulo	Custo da ficha com os impostos de entrada, em reais, 2 casas. Exige `custos:ler`.
`custo_manual`	número \| nulo	Custo informado à mão, em reais. Exige `custos:ler`.
`criado_em`	texto (date-time)
`atualizado_em`	texto (date-time)	Base da leitura incremental.
`excluido_em`	texto \| nulo (date-time)	Preenchido quando o produto foi excluído.

Insumo

Insumo (matéria-prima). saldo soma todos os locais; por local use /v1/estoque/saldos. Toda chave vem sempre.

Chave	Tipo	Descrição
`id`	texto (uuid)
`sku`	texto
`nome`	texto
`familia`	texto \| nulo
`ativo`	booleano
`unidade_compra`	texto	Unidade em que se compra (`kg`, `rolo`…), das Unidades da empresa.
`unidade_consumo`	texto	Unidade em que a ficha consome (`m`, `un`…).
`fator_conversao`	número	Quantas unidades de consumo há em uma de compra.
`ncm`	texto \| nulo
`minimo`	número \| nulo	Estoque mínimo, em unidade de consumo.
`lead_time_dias`	inteiro \| nulo
`fornecedor_padrao_id`	texto \| nulo (uuid)
`saldo`	número	Soma dos saldos de todos os locais, em unidade de consumo. Sempre visível (não exige custos:ler).
`custo_medio`	número \| nulo	Custo médio ponderado dos saldos, em reais por unidade de consumo. Exige `custos:ler`.
`custo_medio_bruto`	número \| nulo	Custo médio com os impostos de entrada, em reais. Exige `custos:ler`.
`custo_referencia`	número \| nulo	Custo de referência do cadastro (usado quando não há saldo), em reais. Exige `custos:ler`.
`criado_em`	texto (date-time)
`atualizado_em`	texto (date-time)
`excluido_em`	texto \| nulo (date-time)

Fornecedor

Fornecedor. O contato (nome e telefone de pessoa) e o e-mail de XML não são expostos. Toda chave vem sempre.

Chave	Tipo	Descrição
`id`	texto (uuid)
`nome`	texto
`cnpj`	texto \| nulo	CNPJ só dígitos (14). Fornecedor pessoa física (cadastrado com CPF, 11 dígitos) vem `null`: CPF é dado pessoal e não sai pela API.
`regime`	texto \| nulo: `simples` · `normal`	Regime tributário.
`uf`	texto \| nulo	UF de origem esperada nas compras.
`lead_time_dias`	inteiro \| nulo
`condicao_pagamento`	lista de inteiro \| nulo	Dias das parcelas (`[30, 60]`).
`ativo`	booleano
`criado_em`	texto (date-time)
`atualizado_em`	texto (date-time)
`excluido_em`	texto \| nulo (date-time)

LinhaDaFicha

Uma linha da ficha. tipo: insumo traz insumo_id; tipo: produto (componente de kit ou semiacabado) traz componente_id.

Chave	Tipo	Descrição
`id`	texto (uuid)
`tipo`	texto: `insumo` · `produto`
`insumo_id`	texto (uuid)	Só quando `tipo` é `insumo`.
`componente_id`	texto (uuid)	Id do produto componente; só quando `tipo` é `produto`.
`consumo`	número	Quantidade consumida por unidade produzida, na `unidade`.
`unidade`	texto
`perda_pct`	número	Perda como fração (`0.03` = 3 %).

Ficha

A ficha técnica ativa de um produto. atualizado_em é o instante em que esta versão foi criada.

Chave	Tipo	Descrição
`produto_id`	texto (uuid)
`versao`	inteiro
`ativa`	booleano
`atualizado_em`	texto (date-time)
`linhas`	lista de LinhaDaFicha
`custo`	número \| nulo	Custo da ficha, em reais (4 casas). Exige `custos:ler`.

Saldo

Saldo de um insumo em um local. unidade é a unidade de consumo do insumo.

Chave	Tipo	Descrição
`insumo_id`	texto (uuid)
`local_id`	texto (uuid)
`saldo`	número
`unidade`	texto
`custo_medio`	número \| nulo	Custo médio neste local, em reais por unidade. Exige `custos:ler`.
`valor`	número \| nulo	`saldo × custo_medio`, em reais. Exige `custos:ler`.
`atualizado_em`	texto (date-time)

Movimento

Um movimento do ledger de estoque (append-only). quantidade é o delta — negativo nas saídas.

Chave	Tipo	Descrição
`id`	texto (uuid)
`insumo_id`	texto (uuid)
`local_id`	texto (uuid)
`tipo`	texto: `entrada_nfe` · `entrada_manual` · `baixa_producao` · `ajuste` · `perda` · `estorno` · `saldo_inicial`
`quantidade`	número	Delta na unidade de consumo (negativo nas saídas).
`unidade`	texto
`custo_unitario`	número \| nulo	Custo unitário do movimento, em reais. Exige `custos:ler`.
`referencia`	texto \| nulo	Documento de origem: `NF 1234`, `OC 1042` ou o serial da etiqueta; `null` quando não há.
`motivo`	texto \| nulo
`origem`	texto: `tela` · `api` · `producao` · `nfe` · `inventario`	Por onde o movimento entrou.
`criado_em`	texto (date-time)	Base da ordem e do filtro `desde`.

PaginaDeLocais

Chave	Tipo	Descrição
`dados`	lista de Local
`proximo_cursor`	texto \| nulo	Sempre `null` nesta rota.

PaginaDeProdutos

Chave	Tipo	Descrição
`dados`	lista de Produto
`proximo_cursor`	texto \| nulo	Cursor da página seguinte; `null` = acabou.

PaginaDeInsumos

Chave	Tipo	Descrição
`dados`	lista de Insumo
`proximo_cursor`	texto \| nulo	Cursor da página seguinte; `null` = acabou.

PaginaDeFornecedores

Chave	Tipo	Descrição
`dados`	lista de Fornecedor
`proximo_cursor`	texto \| nulo	Cursor da página seguinte; `null` = acabou.

PaginaDeFichas

Chave	Tipo	Descrição
`dados`	lista de Ficha
`proximo_cursor`	texto \| nulo	Cursor da página seguinte; `null` = acabou.

PaginaDeSaldos

Chave	Tipo	Descrição
`dados`	lista de Saldo
`proximo_cursor`	texto \| nulo	Cursor da página seguinte; `null` = acabou.

PaginaDeMovimentos

Chave	Tipo	Descrição
`dados`	lista de Movimento
`proximo_cursor`	texto \| nulo	Cursor da página seguinte; `null` = acabou.

API do Prodio

Endereço

Autenticação

Primeiro teste

Empresa e token

GET /v1/eu

Respostas

Locais

GET /v1/locais

Respostas

Produtos

GET /v1/produtos

Parâmetros

Respostas

GET /v1/produtos/{id}

Parâmetros

Respostas

Insumos

GET /v1/insumos

Parâmetros

Respostas

GET /v1/insumos/{id}

Parâmetros

Respostas

Fornecedores

GET /v1/fornecedores

Parâmetros

Respostas

GET /v1/fornecedores/{id}

Parâmetros

Respostas

Fichas técnicas

GET /v1/fichas

Parâmetros

Respostas

GET /v1/fichas/{produto_id}

Parâmetros

Respostas

Estoque

GET /v1/estoque/saldos

Parâmetros

Respostas

GET /v1/estoque/movimentos

Parâmetros

Respostas

Erros

400ErroRequisicao

401NaoAutenticado

403SemPermissao

404NaoEncontrado

429LimiteExcedido

Cabeçalhos de resposta

Esquemas

Erro

Eu

Local

Produto

Insumo

Fornecedor

LinhaDaFicha

Ficha

Saldo

Movimento

PaginaDeLocais

PaginaDeProdutos

PaginaDeInsumos

PaginaDeFornecedores

PaginaDeFichas

PaginaDeSaldos

PaginaDeMovimentos

GET `/v1/eu`

GET `/v1/locais`

GET `/v1/produtos`

GET `/v1/produtos/{id}`

GET `/v1/insumos`

GET `/v1/insumos/{id}`

GET `/v1/fornecedores`

GET `/v1/fornecedores/{id}`

GET `/v1/fichas`

GET `/v1/fichas/{produto_id}`

GET `/v1/estoque/saldos`

GET `/v1/estoque/movimentos`