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 (purchase_order.create)

{
  "action": "purchase_order.create",
  "entity": "purchase_orders",
  "entity_id": "uuid",
  "entity_code": "PO-2026-0001",
  "data": {
    "code": "PO-2026-0001",
    "external_code": null,
    "status": "processing",
    "organization": {
      "company_code": null,
      "purchasing_organization": null,
      "purchasing_group": null,
      "purchase_order_type": null,
      "currency": "BRL"
    },
    "supplier": {
      "code": "FORN-001",
      "name": "Fornecedor A",
      "cnpj": "12.345.678/0001-90"
    },
    "payment": {
      "terms_code": null,
      "terms_description": "30 DDL"
    },
    "references": {
      "quotation_code": "COT-2026-0036",
      "requisition_code": "REQ-2026-0010"
    },
    "delivery": {
      "days": 15,
      "estimated_date": "2026-09-10",
      "address": "Av. Exemplo, 100"
    },
    "totals": { "amount": 1250.0, "currency": "BRL" },
    "items": [{
      "line_number": 1,
      "material_code": "MAT-001",
      "quantity": 100,
      "unit_of_measure": "UN",
      "unit_price": 12.5,
      "total_price": 1250.0,
      "account_assignments": []
    }]
  }
}

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" } } }

GET/api/v1/requisitions/{id}/attachments

Listar anexos da requisição

Lista anexos com URL assinada (1h). Aceita UUID, code ou external_code.

escopo: requisitions:readmódulo: requisitions

Path parameters

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

Exemplo de response

200 OK

{
  "data": {
    "attachments": [{
      "id": "…",
      "file_name": "nf.pdf",
      "file_size": 12040,
      "content_type": "application/pdf",
      "created_at": "2026-08-25T12:00:00Z",
      "download_url": "https://…"
    }]
  }
}

POST/api/v1/requisitions/{id}/attachments

Enviar anexo da requisição

Upload multipart/form-data (campo file). PDF, Excel ou imagem png/jpg; máx. 10MB. Bloqueado se a requisição estiver cancelled.

escopo: requisitions:writemódulo: requisitions

Path parameters

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

Body (JSON)

Campo	Tipo	Descrição
file*	file (multipart)	Arquivo PDF, Excel (.xls/.xlsx) ou imagem (png/jpg). Máx. 10MB.

Exemplo de request

curl -X POST "$BASE/requisitions/ERP-REQ-1001/attachments" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@nf.pdf;type=application/pdf"

Exemplo de response

200 OK

{
  "data": {
    "attachment": {
      "id": "…",
      "file_name": "nf.pdf",
      "download_url": "https://…"
    }
  }
}

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" }]
      }]
    }]
  }
}

POST/api/v1/quotations/{id}/invites

Convidar fornecedor

Adiciona o fornecedor em quotation_suppliers. Se houver rodada active, cria quotation_proposals com status invited. Bloqueado se a cotação estiver completed ou cancelled.

escopo: quotations:writemódulo: quotations

Path parameters

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

Body (JSON)

Campo	Tipo	Descrição
supplier_code*	string	Código do fornecedor no tenant

Exemplo de request

{ "supplier_code": "FORN-001" }

Exemplo de response

200 OK

{
  "data": {
    "invitation": {
      "quotation_code": "COT-2026-0026",
      "supplier_code": "FORN-001",
      "position": 2,
      "round_number": 1,
      "proposal_status": "invited"
    }
  }
}

Pedidos

GET/api/v1/purchase-orders

Listar pedidos

Lista pedidos do tenant com paginação. Payload agrupado no modelo ERP (organization, supplier, payment, references, delivery, totals, items).

escopo: orders:readmódulo: orders

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 por code ou external_code
search	string	Busca em code, external_code, fornecedor
status	string	draft \| sent \| processing \| completed \| error \| …
supplier_code	string	Código do fornecedor
created_since	string (ISO 8601)	Criados desde a data
updated_since	string (ISO 8601)	Alterados desde a data

Exemplo de response

200 OK

{
  "data": {
    "purchase_orders": [{
      "code": "PO-2026-0001",
      "external_code": "4500004022",
      "status": "completed",
      "organization": { "currency": "BRL", "company_code": null },
      "supplier": { "code": "FORN-001", "name": "Fornecedor A", "cnpj": "12.345.678/0001-90" },
      "payment": { "terms_description": "30 DDL" },
      "totals": { "amount": 1250.0, "currency": "BRL" },
      "items": []
    }],
    "page": 1, "page_size": 50, "total": 1, "total_pages": 1
  }
}

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

Detalhe do pedido

Retorna cabeçalho + itens. Mesmo contrato JSON do outbound purchase_order.create (snake_case, tags agrupadas para mapeamento SAP/Totvs).

escopo: orders:readmódulo: orders

Path parameters

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

Exemplo de response

200 OK

{
  "data": {
    "purchase_order": {
      "id": "uuid",
      "code": "PO-2026-0001",
      "external_code": null,
      "status": "processing",
      "organization": {
        "company_code": null,
        "purchasing_organization": null,
        "purchasing_group": null,
        "purchase_order_type": null,
        "currency": "BRL"
      },
      "supplier": {
        "id": "uuid",
        "code": "FORN-001",
        "name": "Fornecedor A",
        "cnpj": "12.345.678/0001-90"
      },
      "payment": {
        "terms_code": null,
        "terms_description": "30 DDL"
      },
      "references": {
        "quotation_code": "COT-2026-0036",
        "requisition_code": "REQ-2026-0010",
        "quotation_id": "uuid",
        "proposal_id": "uuid"
      },
      "delivery": {
        "days": 15,
        "estimated_date": "2026-09-10",
        "address": "Av. Exemplo, 100"
      },
      "totals": { "amount": 1250.0, "currency": "BRL" },
      "notes": null,
      "acceptance": { "accepted_at": "2026-08-25T18:00:00Z", "accepted_by_supplier": true },
      "items": [{
        "line_number": 1,
        "material_code": "MAT-001",
        "material_description": "Parafuso M8",
        "quantity": 100,
        "unit_of_measure": "UN",
        "unit_price": 12.5,
        "tax_percent": 0,
        "total_price": 1250.0,
        "currency": "BRL",
        "delivery_days": 15,
        "site_code": null,
        "contract": { "id": null, "item_id": null, "code": null },
        "account_assignments": []
      }]
    }
  }
}

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)

Contratos

GET/api/v1/contracts

Listar contratos

Lista contratos do tenant com paginação. Inclui saldos de cabeçalho (available_value).

escopo: contracts:readmódulo: contracts

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 por code ou erp_code
search	string	Busca em code, erp_code e title
status	string	draft \| pending_acceptance \| active \| expired \| cancelled
supplier_code	string	Código do fornecedor
created_since	string (ISO 8601)	Criados desde a data
updated_since	string (ISO 8601)	Alterados desde a data

Exemplo de response

200 OK

{
  "data": {
    "contracts": [{
      "code": "CTR-2026-0001",
      "status": "active",
      "supplier_code": "FORN-001",
      "available_value": 15000.5
    }],
    "page": 1, "page_size": 50, "total": 12, "total_pages": 1
  }
}

GET/api/v1/contracts/{id}

Detalhe do contrato

Retorna cabeçalho + itens (com saldos por linha). id = UUID, code ou erp_code.

escopo: contracts:readmódulo: contracts

Path parameters

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

Exemplo de response

200 OK

{
  "data": {
    "contract": {
      "code": "CTR-2026-0001",
      "status": "active",
      "available_value": 15000.5,
      "items": [{ "material_code": "MAT-001", "available_quantity": 10 }]
    }
  }
}

GET/api/v1/contracts/{id}/balance

Saldo do contrato

Resumo de saldo (cabeçalho e itens): ceiling, consumido, reservado e disponível.

escopo: contracts:readmódulo: contracts

Path parameters

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

Exemplo de response

200 OK

{
  "data": {
    "balance": {
      "code": "CTR-2026-0001",
      "available_value": 15000.5,
      "items": [{ "material_code": "MAT-001", "available_quantity": 10 }]
    }
  }
}

GET/api/v1/contracts/{id}/acceptances

Aceites / recusas do contrato

Histórico de aceites e recusas do fornecedor no contrato.

escopo: contracts:readmódulo: contracts

Path parameters

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

Exemplo de response

200 OK

{
  "data": {
    "code": "CTR-2026-0001",
    "acceptances": [{
      "action": "accepted",
      "created_at": "2026-08-01T12:00:00Z",
      "term_version": "1.0"
    }]
  }
}

Aprovações

GET/api/v1/approvals

Listar aprovações

Fila de approval_requests. Default status=pending. Use status=all para todos.

escopo: approvals:read

Query parameters

Campo	Tipo	Descrição
page	integer	Página (1-based)
page_size	integer	Tamanho da página (máx. 100)
status	string	pending \| approved \| rejected \| all (default pending)
flow	string	requisition \| order
created_since	string (ISO 8601)	Criados desde a data

Exemplo de response

200 OK

{
  "data": {
    "approvals": [{
      "id": "…",
      "flow": "requisition",
      "status": "pending",
      "entity_code": "REQ-2026-0001",
      "entity_external_code": "ERP-99"
    }],
    "page": 1, "page_size": 50, "total": 3, "total_pages": 1
  }
}

GET/api/v1/approvals/{id}

Detalhe da aprovação

id = UUID da approval_request.

escopo: approvals:read

Path parameters

Campo	Tipo	Descrição
id*	string	UUID da approval_request

POST/api/v1/approvals/{id}/approve

Aprovar

Aprova a solicitação. Se todos os níveis não rejeitados estiverem aprovados, a requisição vai para approved. Fluxo order ainda não suportado na escrita.

escopo: approvals:write

Path parameters

Campo	Tipo	Descrição
id*	string	UUID da approval_request

Body (JSON)

Campo	Tipo	Descrição
decided_by_name	string	Nome opcional gravado em approver_name da REQ quando concluir

Exemplo de request

{ "decided_by_name": "ERP Integrador" }

Exemplo de response

200 OK

{ "data": { "approval": { "status": "approved" }, "entity_fully_approved": true } }

POST/api/v1/approvals/{id}/reject

Reprovar

Reprova imediatamente a requisição. reason obrigatório.

escopo: approvals:write

Path parameters

Campo	Tipo	Descrição
id*	string	UUID da approval_request

Body (JSON)

Campo	Tipo	Descrição
reason*	string	Motivo da reprovação
decided_by_name	string	Nome opcional

Exemplo de request

{ "reason": "Fora do orçamento", "decided_by_name": "ERP Integrador" }

Exemplo de response

200 OK

{ "data": { "approval": { "status": "rejected" } } }

Relatórios

GET/api/v1/reports/saving

Relatório de Saving

Saving = (target_price − unit_price) × quantity em itens de pedido com vínculo a cotação. Positivo = economia. Status default: sent|processing|completed. Período default: 30d.

escopo: reports:readmódulo: reports

Query parameters

Campo	Tipo	Descrição
period	string	30d \| 60d \| 90d \| current_month (default 30d)
from	string (ISO 8601)	Início (usar com to)
to	string (ISO 8601)	Fim (usar com from)
category	string	Filtro por quotations.category
supplier_code	string	Filtro por código do fornecedor

Exemplo de response

200 OK

{
  "data": {
    "from": "…", "to": "…", "period": "30d",
    "sign_convention": "positive_means_economy",
    "summary": { "saving_total": 12500.5, "line_count": 42, "order_count": 18 },
    "by_month": [{ "month": "2026-08", "saving": 12500.5 }],
    "by_category": [{ "category": "TI", "saving": 8000 }]
  }
}

GET/api/v1/reports/spend

Relatório de Spend

Soma de purchase_order_items.total_price. Status default: sent|processing|completed. Com include_previous=true compara janela anterior de mesmo comprimento.

escopo: reports:readmódulo: reports

Query parameters

Campo	Tipo	Descrição
period	string	30d \| 60d \| 90d \| current_month (default 30d)
from	string (ISO 8601)	Início (usar com to)
to	string (ISO 8601)	Fim (usar com from)
category	string	Filtro por quotations.category
supplier_code	string	Filtro por código do fornecedor
include_previous	boolean	true\|1 — inclui spend anterior e variation_pct

Exemplo de response

200 OK

{
  "data": {
    "summary": { "spend_total": 250000, "previous_spend_total": 230000, "variation_pct": 0.087 },
    "by_category": [{ "category": "TI", "spend": 100000, "pct_of_total": 0.4 }],
    "by_supplier": [{ "supplier_name": "Fornecedor A", "orders": 12, "spend": 80000 }]
  }
}