Documentação pública

Valore — Loja de API

Referência para integração ERP ↔ Valore. Todas as rotas usam o prefixo /api/v1 e exigem API key do tenant (feature api_integrations).

Autenticação

Envie a chave em um dos formatos abaixo. A chave é exibida apenas uma vez na criação.

Header Bearer (recomendado)

Authorization: Bearer valore_sua_chave_aqui

Header alternativo

X-Api-Key: valore_sua_chave_aqui

Respostas de sucesso: { "data": { ... } }
Erros: { "error": "...", "code": "FORBIDDEN" }

Outbound Valore → ERP (Idempotency-Key)

Chamadas do Valore ao ERP (pedidos e contratos) enviam o header Idempotency-Key. A chave é estável por tenant + ação + entidade (SHA-256). Reenvios do monitor reutilizam a mesma chave para o ERP deduplicar (ex.: pedido já criado no SAP).

Header enviado pelo Valore

Idempotency-Key: <sha256(company_id:action:entity_id)>

Corpo JSON típico

{
  "action": "purchase_order.create",
  "entity": "purchase_orders",
  "entity_id": "uuid",
  "entity_code": "PO-2026-0001",
  "data": { "...": "payload do pedido" }
}

Cada tentativa incrementa o contador attempts no log.
Despachos concorrentes para a mesma entidade são bloqueados (HTTP 409 no Valore).
O ERP deve tratar a mesma chave como a mesma operação de negócio.

Códigos de erro

Code	HTTP	Descrição
UNAUTHORIZED	401	API key ausente ou inválida
FORBIDDEN	403	Escopo insuficiente ou módulo desabilitado
NOT_FOUND	404	Recurso não encontrado
VALIDATION_ERROR	400	Payload ou parâmetros inválidos
CONFLICT	409	Conflito (ex.: código duplicado)
RATE_LIMITED	429	Limite de requisições excedido
INTERNAL_ERROR	500	Erro interno

Geral

GET/api/v1/health

Health check

Valida a API key, a feature api_integrations do tenant e retorna metadados da chave.

Exemplo de response

200 OK

{
  "data": {
    "status": "ok",
    "company_id": "00000000-0000-0000-0000-000000000001",
    "scopes": ["items:read", "orders:read"]
  }
}

Itens

GET/api/v1/items

Listar itens

Catálogo de materiais do tenant com paginação e filtros.

escopo: items:readmódulo: items

Query parameters

Campo	Tipo	Descrição
page	integer	Página (1-based)
page_size	integer	Tamanho da página (máx. 100)
code	string	Filtro exato por código
search	string	Busca em code e descrições
updated_since	string (ISO 8601)	Itens alterados desde a data

Exemplo de response

200 OK

{
  "data": {
    "items": [{ "code": "MAT-001", "short_description": "Parafuso", "unit_of_measure": "UN" }],
    "page": 1, "page_size": 50, "total": 120, "total_pages": 3
  }
}

POST/api/v1/items/batch

Criar itens (lote)

Criação em lote. Rejeita codes duplicados com 409.

escopo: items:writemódulo: items

Body (JSON)

Campo	Tipo	Descrição
items*	array	Lista de itens (máx. 200)
items[].code*	string	Código único no tenant
items[].short_description*	string	Descrição curta
items[].unit_of_measure*	string	Unidade
items[].commodity_group	string	Grupo de mercadoria
items[].target_price	number	Preço alvo (Saving)

Exemplo de request

{
  "items": [
    {
      "code": "MAT-API-001",
      "short_description": "Parafuso M8",
      "unit_of_measure": "UN",
      "commodity_group": "MRO"
    }
  ]
}

Exemplo de response

200 OK

{ "data": { "created": 1, "items": [...] } }

Requisições

POST/api/v1/requisitions

Criar requisição

Cria requisição com itens. external_code é obrigatório (chave do ERP). Valore gera code interno REQ-XXXX.

escopo: requisitions:writemódulo: requisitions

Body (JSON)

Campo	Tipo	Descrição
external_code*	string	Identificador único no ERP
title*	string	Título da requisição
description	string	Descrição (máx. 500)
cost_center	string	Centro de custo
needed_by	date (YYYY-MM-DD)	Data necessidade
priority	enum	normal \| urgent \| critical
requester_name	string	Nome do solicitante no ERP
items*	array	Itens (mín. 1)
items[].material_description*	string	Descrição do item
items[].quantity*	number	Quantidade > 0

Exemplo de request

{
  "external_code": "ERP-REQ-1001",
  "title": "Materiais manutenção",
  "items": [
    { "material_code": "MAT-001", "material_description": "Parafuso", "quantity": 50, "unit_of_measure": "UN" }
  ]
}

Exemplo de response

200 OK

{ "data": { "requisition": { "code": "REQ-0042", "external_code": "ERP-REQ-1001", "status": "pending" } } }

DELETE/api/v1/requisitions/{id}

Cancelar requisição

Soft cancel → status cancelled. Aceita UUID, code ou external_code.

escopo: requisitions:writemódulo: requisitions

Path parameters

Campo	Tipo	Descrição
id*	string	UUID, code ou external_code

Exemplo de response

200 OK

{ "data": { "requisition": { "status": "cancelled" } } }

Cotações

GET/api/v1/quotations/{id}/proposals

Propostas por rodada

Retorna quotation + rounds[] com proposals[] e items[] respondidos por fornecedor.

escopo: quotations:readmódulo: quotations

Query parameters

Campo	Tipo	Descrição
round_number	integer	Filtrar rodada
supplier_code	string	Filtrar fornecedor
status	string	invited \| submitted \| selected \| rejected

Path parameters

Campo	Tipo	Descrição
id*	string	UUID ou code da cotação

Exemplo de response

200 OK

{
  "data": {
    "quotation": { "code": "COT-2026-0026" },
    "rounds": [{
      "round_number": 1,
      "proposals": [{
        "supplier": { "code": "FORN-001", "name": "Fornecedor A" },
        "items": [{ "material_code": "MAT-001", "unit_price": 10.5, "item_status": "accepted" }]
      }]
    }]
  }
}

Pedidos

GET/api/v1/purchase-orders/{id}/pdf

PDF do pedido

Retorna application/pdf (stream).

escopo: orders:readmódulo: orders

Path parameters

Campo	Tipo	Descrição
id*	string	UUID, code ou external_code

Exemplo de response

200 OK

(binary PDF)