Conectar seu sistema pela API

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: produtos, insumos, fornecedores, fichas técnicas, estoque, pedidos, compras, produção e notas. O endereço é https://api.prodio.com.br/v1, as respostas são JSON em português e o acesso é por um token da empresa, criado em Configurações › API. A referência completa de rotas e campos está em prodio.com.br/api.

Quando usar

• Quando um sistema precisa dos dados sem alguém abrir o Prodio: puxar o cadastro de produtos para a loja, mandar o saldo de estoque para o ERP, montar um painel com os apontamentos do dia.
• Quando o cadastro nasce em outro lugar e você não quer digitar duas vezes: o outro sistema cria e atualiza produtos, insumos e fornecedores em lote.
• Quando a sua loja ou o seu ERP é um dos hubs que o Prodio já conhece (BaseLinker, Bling, Tiny, Kamino), use o conector: ele já traz os pedidos, recebe a produção bipada e busca as NF-e. A API é para o que o conector não cobre ou para um sistema próprio.
• A API é servidor a servidor. Ela não aceita chamadas feitas direto do navegador (sem CORS), de propósito: o token nunca deve chegar ao computador de um cliente.

Criar o token

Só um administrador da empresa cria, vê e revoga tokens; a tela não aparece para os outros papéis.

1. Abra Configurações no menu e escolha API (endereço /configuracoes/api).
2. Clique em Novo token e dê um nome que diga qual sistema vai usá-lo (por exemplo, "ERP da loja" ou "Painel de produção").
3. Marque os escopos: para cada recurso, Nenhum, Ler ou Ler e escrever. Os botões de preset ("Só leitura", "Cadastros", "Estoque e compras") preenchem os casos comuns; Custos é uma chave à parte, só de leitura.
4. Escolha a validade: 30, 90 ou 365 dias (o padrão) ou sem validade. Prefira uma validade: trocar o token de tempos em tempos é a proteção mais barata que existe.
5. Clique em Criar. O token aparece uma única vez, numa janela com o botão Copiar. Guarde-o agora no cofre de segredos do outro sistema: o Prodio não mostra o token de novo, nem para você.

Depois disso a lista mostra só o começo do token (prodio_live_ e os oito caracteres seguintes), quem criou, quando, o último uso, a validade e a situação (ativo, vencido, revogado ou sem dono). O token tem 55 caracteres e sempre começa com prodio_live_. Cada empresa pode ter até 10 tokens ativos.

Escopos

O escopo diz o que o token pode fazer. Cada rota exige um; chamar uma rota sem o escopo certo devolve 403 escopo_insuficiente.

• produtos, insumos, fornecedores, fichas, estoque, compras e producao têm :ler e :escrever. Escrever inclui ler do mesmo recurso: produtos:escrever já lê produtos.
• pedidos e notas só têm :ler: pedidos nascem nos hubs e as notas chegam por e-mail ou pelo conector.
• custos:ler é separado e libera os campos em reais (custo_medio, custo_ficha, valor, preco…). Sem ele, esses campos vêm null, e o resto da resposta continua igual. Uma integração de loja não precisa ver o custo da ficha.
• GET /v1/eu e GET /v1/locais funcionam com qualquer token: use-os para confirmar que o token está certo e descobrir a empresa, o fuso e os escopos que ele tem.

Peça só os escopos que o sistema usa. Se depois ele precisar de mais, crie outro token: os escopos de um token não mudam depois de criado.

Primeiro teste

Troque prodio_live_SEU_TOKEN pelo token copiado e rode no terminal:

curl -sS https://api.prodio.com.br/v1/eu -H "Authorization: Bearer prodio_live_SEU_TOKEN"
curl -sS "https://api.prodio.com.br/v1/produtos?limite=50&atualizado_desde=2026-10-01T00:00:00-03:00" -H "Authorization: Bearer prodio_live_SEU_TOKEN"

A primeira chamada devolve a empresa e o próprio token (nome, prefixo, escopos, validade e limites). A segunda lista os produtos alterados desde 1º de outubro, no fuso de Brasília. Se a primeira funcionar e a segunda devolver 403, o token não tem produtos:ler.

O token vai sempre no cabeçalho Authorization: Bearer …. Na URL ele é recusado (400 token_na_url), para não parar em log nem em histórico de navegador. Toda resposta traz um X-Request-Id: anote-o ao pedir suporte.

Paginação e sincronização

Toda lista devolve { "dados": [ … ], "proximo_cursor": "…" }.

• limite: quantas linhas por página, padrão 50, máximo 200.
• proximo_cursor: para a página seguinte, repita exatamente esse valor no parâmetro cursor. Quando vier null, acabou. O cursor é opaco: não monte nem edite um à mão (400 cursor_invalido).
• A ordem é estável e crescente por atualizado_em (criado_em nos movimentos de estoque, o instante em nos apontamentos), com desempate por id. O cursor marca o ponto exato onde a página anterior parou, então a página seguinte nunca pula uma linha. Uma linha alterada no meio do percurso ganha um atualizado_em novo e pode voltar numa página mais à frente: trate-a como atualização (grave por id), nunca como registro novo.

Para manter o outro sistema sincronizado sem baixar tudo todo dia:

1. Na primeira carga, percorra a lista inteira seguindo o proximo_cursor.
2. Guarde o maior atualizado_em que você viu.
3. Nas cargas seguintes, chame com atualizado_desde= esse instante. O filtro é inclusivo (a partir do instante, inclusive), então a última linha da carga anterior volta: trate-a como atualização, não como novidade.
4. Mande o instante com fuso (2026-10-01T00:00:00-03:00 ou …Z). Sem fuso a API recusa com 400 parametro_invalido, porque "meia-noite" sem fuso é ambígua. As respostas sempre vêm em UTC (+00:00).
5. Nos cadastros, incluir_excluidos=true traz também o que foi excluído, com excluido_em preenchido, para o outro sistema apagar do lado dele.

Há uma janela de 30 segundos: a lista só devolve linhas alteradas há mais de meio minuto. Isso garante que uma gravação longa nunca fique para trás. Uma alteração feita agora aparece na API em até 30 segundos.

Idempotência

Rede cai, servidor demora, o seu sistema tenta de novo. Para a repetição não criar um movimento de estoque duas vezes, as escritas usam o cabeçalho Idempotency-Key:

• Mande uma chave sua, única por operação (1 a 100 caracteres: letras, números, _, ., : e -). O id do registro no seu sistema costuma servir.
• Ela é obrigatória ao criar movimento de estoque e ordem de compra, e opcional nos lotes de cadastro, nos PUT (ficha técnica e plano do dia), no estorno e no cancelamento.
• Repetir a mesma chave com o mesmo corpo devolve a mesma resposta de antes, com Idempotency-Replayed: true, sem gravar de novo. A ordem das chaves do JSON e os espaços não importam.
• A mesma chave com um corpo diferente é recusada com 409 chave_idempotencia_reutilizada.
• A chave vale por 24 horas, por token.

Lotes (POST …/lote) aceitam até 100 itens por chamada e respondem item a item: { "resultados": [ { "sku": "CAM-AZUL-M", "ok": true, "id": "…" }, { "sku": "CAM-AZUL-G", "ok": false, "erro": "NCM inválido." } ] }. O HTTP é 200 mesmo com item recusado; confira o ok de cada um.

Limites

• 120 chamadas por minuto por token e 300 por minuto por empresa, somando todos os tokens dela.
• Toda resposta autenticada traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (instante Unix, em segundos, em que a janela zera).
• Passou do limite: 429 limite_excedido com Retry-After em segundos. Espere esse tempo e repita; não repita antes.
• Corpo das escritas: Content-Type: application/json, até 256 KB.
• Para carregar muita coisa, use páginas de 200 e lotes de 100: são bem menos chamadas do que uma por registro.

Erros comuns

Todo erro vem como { "erro": { "codigo": "…", "mensagem": "…", "campo": "…", "id_requisicao": "…" } }, em português. O codigo é estável; a mensagem é para ler.

• 401 token_ausente ou token_invalido. O cabeçalho Authorization: Bearer não foi (token_ausente) ou o token não tem o formato do Prodio (token_invalido): faltou ou sobrou caractere, ou é um token de outro sistema. Espaço, tabulação ou quebra de linha nas pontas e bearer em minúsculas são tolerados; o problema está no token em si. Confira o token copiado inteiro (55 caracteres, começando com prodio_live_).
• 401 token_vencido ou token_revogado. O token passou da validade ou alguém o revogou em Configurações › API. Crie um novo e troque no outro sistema.
• 403 escopo_insuficiente. A rota pede um escopo que o token não tem. Veja o escopo da rota na referência e crie um token com ele.
• 403 token_sem_dono. Quem criou o token deixou de ser admin da empresa; o token morreu junto. Um admin atual cria outro.
• 403 empresa_suspensa. A assinatura da empresa está suspensa; a API recusa até regularizar.
• 400 parametro_invalido. Um filtro veio errado; campo diz qual. O caso mais comum é instante sem fuso em atualizado_desde.
• 400 cursor_invalido. O cursor foi montado ou editado à mão. Repita o proximo_cursor exatamente como veio.
• 404 nao_encontrado. O id não existe para a sua empresa. A API responde o mesmo para id de outra empresa, de propósito.
• 409 chave_idempotencia_reutilizada. A mesma Idempotency-Key já foi usada com outro corpo. Use uma chave nova para uma operação nova.
• 413 corpo_grande_demais ou 415 tipo_nao_suportado. Corpo acima de 256 KB ou sem Content-Type: application/json.
• 422 validacao. Um campo está inválido ou é desconhecido; campo aponta onde (por exemplo, itens[2].qtd). Nos lotes, o item recusado volta com ok: false e o motivo em erro, sem derrubar o resto.
• 429 limite_excedido. Espere o Retry-After e repita.
• 500 erro_interno ou 503 banco_indisponivel. Repita com espera crescente (1 s, 2 s, 4 s…) e a mesma Idempotency-Key. Se persistir, mande o id_requisicao ao suporte.

Segurança

• Guarde o token num cofre de segredos (variável de ambiente, gerenciador de segredos do servidor). Nunca em repositório, planilha, log, URL ou mensagem. Se ele vazou, revogue na hora e crie outro.
• Um token por sistema. Assim você revoga a loja sem derrubar o ERP, e o "último uso" da lista diz quem está chamando.
• Peça só os escopos necessários e dê uma validade. Um token só de leitura não grava nada, mesmo que vaze.
• Revogue em Configurações › API quando o sistema sair do ar ou trocar de fornecedor. Revogar é imediato e não tem volta; a chamada seguinte recebe 401 token_revogado.
• O token morre com quem o criou. Se a pessoa que criou o token deixar de ser administradora da empresa, o token para de valer (403 token_sem_dono). Antes de remover um admin, veja na lista quais tokens são dele e crie os substitutos com outro admin.
• O Prodio guarda só uma impressão digital do token, não o token. Por isso ele não consegue mostrá-lo de novo, nem o suporte. Nunca mande o token no suporte: o time não precisa dele.

Veja também

• Referência da API: rotas, parâmetros, campos e exemplos, com a especificação OpenAPI para baixar.
• Conectores: BaseLinker, Bling, Tiny e Kamino sem precisar de código.
• Usuários: papéis e quem é administrador.