Referência da API

Cada rota da API do Softeum Pedidos, do contrato OpenAPI: o método, o caminho, a autenticação, os parâmetros, o corpo e as respostas com os códigos.

Baixar o arquivo OpenAPI Guia, seção 13

docs.softeum.com.br/api/

Seções desta página

Visão geral

Integração do ERP da indústria com o Softeum Pedidos.

Pedidos (Softeum → ERP). Quando um pedido fica pronto, o Softeum avisa o endereço cadastrado no painel (webhook pedido.aprovado).
O ERP responde 2xx e confirma com o número do ERP: no próprio corpo da resposta ou depois, em POST /pedidos/{id}/confirmacao.
Se não conseguir lançar, recusa com o motivo em POST /pedidos/{id}/recusa, e o pedido volta para o time da indústria.
Sem webhook, o ERP busca em GET /pedidos?situacao=pronto (o pedido fica pronto até ser confirmado ou recusado).

Cadastros (ERP → Softeum). O ERP é a fonte da verdade de produtos, compradores, vendedores e tabelas de preço.
Envie em lotes de até 1000 registros. Cada um é criado ou atualizado pelo codigo_erp; para desativar, mande ativo: false.

Autenticação. Authorization: Bearer <chave>, com a chave criada no painel (Integração → Como o ERP recebe → O ERP busca os pedidos).

Endereço: https://api.softeum.com.br/v1 Versão 1 da API.
Contrato: OpenAPI 3.1.0, versão 1.0.0 da API. Baixar o openapi.json: abre no Swagger Editor, no Postman e no Insomnia.
No guia: Cada campo, os erros e os limites, com exemplos: guia, seção 13.

Autenticação

Toda chamada leva o cabeçalho Authorization: Bearer <chave>.

Chave de acesso criada no painel (Integração → Como o ERP recebe → O ERP busca os pedidos).

Os avisos ao ERP não levam a chave: o ERP confere a assinatura de cada aviso com o segredo do painel.

Pedidos

Buscar, confirmar e recusar pedidos.

Listar pedidos

GET/v1/pedidos

Do mais antigo para o mais novo. Use para buscar os pedidos prontos quando não houver webhook.

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`situacao`	consulta	texto	não	valores: `pronto`, `enviado`, `confirmado`, `erro`
`desde`	consulta	data e hora (ISO 8601, com fuso)	não	Aprovados a partir deste momento (ISO 8601 com fuso).
`cursor`	consulta	texto	não	proximo_cursor da página anterior.
`limite`	consulta	inteiro	não	de 1 a 500; padrão `100`

Respostas

Código	O que quer dizer	Corpo
`200`	Uma página de pedidos.	`ListaPedidos` (application/json)
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`422`	Dados inválidos: erros[] traz cada campo e o motivo.	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s "https://api.softeum.com.br/v1/pedidos" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE"

$SOFTEUM_CHAVE: a chave de acesso.

Buscar um pedido

GET/v1/pedidos/{id}

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`id`	caminho	texto (uuid)	sim	id do pedido no Softeum.

Respostas

Código	O que quer dizer	Corpo
`200`	O pedido.	`Pedido` (application/json)
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`404`	Pedido não encontrado, ou ainda não pronto para o ERP (na leitura ou na revisão), recusado ou cancelado pelo time.	`Problema` (application/problem+json)
`409`	O pedido não pode ir ao ERP (item sem produto do catálogo, produto inativo ou comprador sem cadastro): voltou para a revisão do time e não aparece na lista até ser aprovado de novo.	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s "https://api.softeum.com.br/v1/pedidos/$ID" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE"

$SOFTEUM_CHAVE: a chave de acesso. $ID: id do pedido no Softeum.

Confirmar que o ERP lançou o pedido

POST/v1/pedidos/{id}/confirmacao

Informe o número do pedido no ERP. Repetir com o mesmo número não muda nada.

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`id`	caminho	texto (uuid)	sim	id do pedido no Softeum.
`Idempotency-Key`	cabeçalho	texto	não	Opcional. As operações já são idempotentes: repetir a mesma chamada (com ou sem esta chave) não muda nada duas vezes. até 100 caracteres
`Prefer`	cabeçalho	texto	não	Opcional. `return=minimal` (RFC 7240): a resposta traz só o resumo do pedido (id, situacao, numero_erp), mais rápida, e o cabeçalho Preference-Applied. Sem ele, o pedido inteiro. exemplo `return=minimal`

Corpo da requisição

application/json, obrigatório. Modelo ConfirmacaoErp.

Campo	Tipo	Obrigatório	O que é
`numero_erp`	texto	sim	Número do pedido no ERP. de 1 a 60 caracteres; exemplo `584460`
`lancado_em`	data e hora (ISO 8601, com fuso)	não	Quando o ERP lançou o pedido (se não vier, vale a hora da confirmação). exemplo `2026-09-30T16:13:00-03:00`

Exemplo do contrato

{
  "numero_erp": "584460"
}

Respostas

Código	O que quer dizer	Corpo
`200`	Pedido confirmado. O pedido inteiro; com `Prefer: return=minimal`, só o resumo.	`Pedido` ou `ResumoPedido` (application/json)
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`404`	Pedido não encontrado.	`Problema` (application/problem+json)
`409`	O pedido já foi confirmado com outro número, ou não está pronto para o ERP.	`Problema` (application/problem+json)
`422`	Dados inválidos: erros[] traz cada campo e o motivo.	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s -X POST "https://api.softeum.com.br/v1/pedidos/$ID/confirmacao" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"numero_erp":"584460"}'

$SOFTEUM_CHAVE: a chave de acesso. $ID: id do pedido no Softeum.

Recusar o pedido no ERP

POST/v1/pedidos/{id}/recusa

O pedido fica com erro e o motivo aparece para o time da indústria, que corrige e reenvia.

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`id`	caminho	texto (uuid)	sim	id do pedido no Softeum.
`Idempotency-Key`	cabeçalho	texto	não	Opcional. As operações já são idempotentes: repetir a mesma chamada (com ou sem esta chave) não muda nada duas vezes. até 100 caracteres
`Prefer`	cabeçalho	texto	não	Opcional. `return=minimal` (RFC 7240): a resposta traz só o resumo do pedido (id, situacao, numero_erp), mais rápida, e o cabeçalho Preference-Applied. Sem ele, o pedido inteiro. exemplo `return=minimal`

Corpo da requisição

application/json, obrigatório. Modelo RecusaErp.

Campo	Tipo	Obrigatório	O que é
`motivo`	texto	sim	Por que o ERP não aceitou. Aparece para o time da indústria no painel. de 3 a 500 caracteres; exemplo `Condição de pagamento 28/56 não existe no ERP.`

Exemplo do contrato

{
  "motivo": "Condição de pagamento 28/56 não existe no ERP."
}

Respostas

Código	O que quer dizer	Corpo
`200`	Pedido marcado com erro. O pedido inteiro; com `Prefer: return=minimal`, só o resumo.	`Pedido` ou `ResumoPedido` (application/json)
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`404`	Pedido não encontrado.	`Problema` (application/problem+json)
`409`	O pedido já foi confirmado, ou não está pronto para o ERP.	`Problema` (application/problem+json)
`422`	Dados inválidos: erros[] traz cada campo e o motivo.	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s -X POST "https://api.softeum.com.br/v1/pedidos/$ID/recusa" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"motivo":"Condição de pagamento 28/56 não existe no ERP."}'

$SOFTEUM_CHAVE: a chave de acesso. $ID: id do pedido no Softeum.

Baixar o documento original

GET/v1/pedidos/{id}/arquivo

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`id`	caminho	texto (uuid)	sim	id do pedido no Softeum.

Respostas

Código	O que quer dizer	Corpo
`302`	Redireciona para um link temporário do arquivo (PDF, planilha, XML ou e-mail).	sem corpo
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`404`	Pedido não encontrado.	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s -L -o documento "https://api.softeum.com.br/v1/pedidos/$ID/arquivo" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE"

$SOFTEUM_CHAVE: a chave de acesso. $ID: id do pedido no Softeum.

Cadastros

Sincronizar os cadastros do ERP.

Sincronizar produtos

PUT/v1/produtos

Cria ou atualiza produtos do catálogo pelo codigo_erp.

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`Idempotency-Key`	cabeçalho	texto	não	Opcional. As operações já são idempotentes: repetir a mesma chamada (com ou sem esta chave) não muda nada duas vezes. até 100 caracteres

Corpo da requisição

application/json, obrigatório. Modelo LoteProdutos.

Campo	Tipo	Obrigatório	O que é
`produtos`	lista de `ProdutoErp`	sim	de 1 a 1.000 itens
`produtos[].codigo_erp`	texto	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`produtos[].sku`	texto	sim	de 1 a 60 caracteres; exemplo `VA-LVD-500R`
`produtos[].descricao`	texto	sim	de 1 a 300 caracteres; exemplo `Limpa-vidros refil 500 ml`
`produtos[].ean`	texto ou `null`	não	formato `^(\d{8}\|\d{12,14})$`
`produtos[].embalagem`	texto	sim	Embalagem de venda. de 1 a 10 caracteres; exemplo `CX`
`produtos[].unidades_por_embalagem`	inteiro	sim	maior que 0; exemplo `12`
`produtos[].ncm`	texto ou `null`	não	formato `^\d{8}$`
`produtos[].ipi_pct`	número	não	de 0 a 100; padrão `0`
`produtos[].linha`	texto ou `null`	não	até 80 caracteres
`produtos[].ativo`	`true` ou `false`	não	padrão `true`

Respostas

Código	O que quer dizer	Corpo
`200`	Lote processado.	`ResultadoSincronizacao` (application/json)
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`422`	O lote todo é inválido (sem a lista, vazio ou com mais registros que o máximo). Registro inválido sozinho não derruba o lote: volta em erros.	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s -X PUT "https://api.softeum.com.br/v1/produtos" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE" \
  -H "Content-Type: application/json" \
  -d @corpo.json

$SOFTEUM_CHAVE: a chave de acesso. corpo.json: o corpo, com os campos da tabela acima.

Sincronizar compradores

PUT/v1/compradores

Cria ou atualiza compradores pelo codigo_erp.

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`Idempotency-Key`	cabeçalho	texto	não	Opcional. As operações já são idempotentes: repetir a mesma chamada (com ou sem esta chave) não muda nada duas vezes. até 100 caracteres

Corpo da requisição

application/json, obrigatório. Modelo LoteCompradores.

Campo	Tipo	Obrigatório	O que é
`compradores`	lista de `CompradorErp`	sim	de 1 a 1.000 itens
`compradores[].codigo_erp`	texto	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`compradores[].cnpj`	texto	sim	CNPJ só com números (14 dígitos), com dígitos verificadores válidos. formato `^\d{14}$`; exemplo `12345678000195`
`compradores[].razao_social`	texto	sim	de 1 a 200 caracteres
`compradores[].nome_fantasia`	texto ou `null`	não	até 200 caracteres
`compradores[].cidade`	texto ou `null`	não	até 120 caracteres
`compradores[].uf`	texto ou `null`	não	Estado do comprador, a sigla com 2 letras maiúsculas. Casa com a tabela de preço pelos estados, criada no painel. formato `^[A-Z]{2}$`; exemplo `SP`
`compradores[].regiao`	texto ou `null`	não	Região de preço (casa com as tabelas de nível região). até 60 caracteres; exemplo `Sudeste`
`compradores[].codigo_vendedor`	texto ou `null`	não	codigo_erp do vendedor responsável. de 1 a 60 caracteres; exemplo `C001`
`compradores[].codigo_tabela_preco`	texto ou `null`	não	codigo_erp da tabela do comprador (nível 2), se houver. de 1 a 60 caracteres; exemplo `C001`
`compradores[].ativo`	`true` ou `false`	não	false = bloqueado: pedidos dele vão para a revisão. padrão `true`

Respostas

Código	O que quer dizer	Corpo
`200`	Lote processado.	`ResultadoSincronizacao` (application/json)
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`422`	O lote todo é inválido (sem a lista, vazio ou com mais registros que o máximo). Registro inválido sozinho não derruba o lote: volta em erros.	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s -X PUT "https://api.softeum.com.br/v1/compradores" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE" \
  -H "Content-Type: application/json" \
  -d @corpo.json

$SOFTEUM_CHAVE: a chave de acesso. corpo.json: o corpo, com os campos da tabela acima.

Sincronizar vendedores

PUT/v1/vendedores

Cria ou atualiza vendedores pelo codigo_erp.

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`Idempotency-Key`	cabeçalho	texto	não	Opcional. As operações já são idempotentes: repetir a mesma chamada (com ou sem esta chave) não muda nada duas vezes. até 100 caracteres

Corpo da requisição

application/json, obrigatório. Modelo LoteVendedores.

Campo	Tipo	Obrigatório	O que é
`vendedores`	lista de `VendedorErp`	sim	de 1 a 1.000 itens
`vendedores[].codigo_erp`	texto	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`vendedores[].nome`	texto	sim	de 1 a 120 caracteres
`vendedores[].email`	texto (e-mail) ou `null`	não	E-mail que encaminha os pedidos. Outros endereços do mesmo vendedor se cadastram no painel. exemplo `carlos.menezes@valeazul.com.br`
`vendedores[].ativo`	`true` ou `false`	não	padrão `true`

Respostas

Código	O que quer dizer	Corpo
`200`	Lote processado.	`ResultadoSincronizacao` (application/json)
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`422`	O lote todo é inválido (sem a lista, vazio ou com mais registros que o máximo). Registro inválido sozinho não derruba o lote: volta em erros.	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s -X PUT "https://api.softeum.com.br/v1/vendedores" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE" \
  -H "Content-Type: application/json" \
  -d @corpo.json

$SOFTEUM_CHAVE: a chave de acesso. corpo.json: o corpo, com os campos da tabela acima.

Enviar uma tabela de preço inteira

PUT/v1/tabelas-de-preco/{codigo_erp}

Cria ou substitui a tabela e todos os preços dela. Preço que não vier sai da tabela.

Com a chave de acesso: autenticação.

Parâmetros

Nome	Onde	Tipo	Obrigatório	O que é
`codigo_erp`	caminho	texto	sim	Código da tabela no ERP.
`Idempotency-Key`	cabeçalho	texto	não	Opcional. As operações já são idempotentes: repetir a mesma chamada (com ou sem esta chave) não muda nada duas vezes. até 100 caracteres

Corpo da requisição

application/json, obrigatório. Modelo TabelaPrecoErp.

Campo	Tipo	Obrigatório	O que é
`nome`	texto	sim	de 1 a 120 caracteres; exemplo `Tabela Sudeste`
`nivel`	texto	sim	Em cada item vale o primeiro que tiver preço: especifico (de um comprador), comprador (tabela atribuída ao comprador), regiao, padrao. valores: `especifico`, `comprador`, `regiao`, `padrao`
`codigo_comprador`	texto ou `null`	não	Obrigatório no nível especifico. de 1 a 60 caracteres; exemplo `C001`
`regiao`	texto ou `null`	não	Obrigatória no nível regiao. até 60 caracteres
`vigencia_inicio`	data (aaaa-mm-dd)	sim	exemplo `2026-10-07`
`vigencia_fim`	data (aaaa-mm-dd) ou `null`	não	exemplo `2026-10-07`
`precos`	lista de objeto	sim	Todos os preços da tabela: o que não vier aqui sai da tabela. até 20.000 itens
`precos[].codigo_produto`	texto	sim	codigo_erp do produto. de 1 a 60 caracteres; exemplo `C001`
`precos[].preco`	número	sim	Preço líquido (sem impostos) por embalagem de venda. a partir de 0; exemplo `76.04`

Respostas

Código	O que quer dizer	Corpo
`200`	Tabela gravada (contagem dos preços).	`ResultadoSincronizacao` (application/json)
`401`	Chave de acesso ausente, inválida ou revogada.	`Problema` (application/problem+json)
`403`	O acesso da empresa ao Softeum está suspenso.	`Problema` (application/problem+json)
`422`	Tabela inválida (ex.: vigência que se sobrepõe a outra do mesmo alcance).	`Problema` (application/problem+json)
`429`	Muitas chamadas em pouco tempo (padrão: 120 por minuto por chave; a empresa pode ter um limite maior, combinado com a Softeum). Espere o tempo do cabeçalho Retry-After.	`Problema` (application/problem+json)

Chamada de exemplo

curl -s -X PUT "https://api.softeum.com.br/v1/tabelas-de-preco/$CODIGO_ERP" \
  -H "Authorization: Bearer $SOFTEUM_CHAVE" \
  -H "Content-Type: application/json" \
  -d @corpo.json

$SOFTEUM_CHAVE: a chave de acesso. $CODIGO_ERP: Código da tabela no ERP. corpo.json: o corpo, com os campos da tabela acima.

Avisos ao ERP

O que o Softeum manda ao endereço que a TI cadastra no painel (os webhooks do contrato).

Pedido pronto para o ERP

POSTendereço do ERPSofteum-Evento: pedido.aprovado

Enviado ao endereço cadastrado no painel (Integração → Como o ERP recebe → Aviso no endereço do ERP).
Cabeçalhos: Softeum-Evento (tipo), Softeum-Entrega (id do aviso) e Softeum-Assinatura: t=<segundos>,v1=<hex>.
v1 = HMAC-SHA256(segredo, <t>.<corpo>), com o segredo mostrado no painel.
Recuse avisos com mais de 5 minutos e use o pedido.id para não lançar duas vezes.
Sem resposta 2xx em 10 segundos, reenviamos depois de 1, 5, 30, 120, 360 minutos; depois disso o pedido fica com erro.

Sem a chave de acesso: o ERP confere a assinatura do aviso (guia, seção 5).

Corpo do aviso

application/json, obrigatório. Modelo EventoPedido.

Campo	Tipo	Obrigatório	O que é
`id`	texto (uuid)	sim	Identificador deste aviso (o mesmo nos reenvios).
`tipo`	texto	sim	valores: `pedido.aprovado`
`criado_em`	data e hora (ISO 8601, com fuso)	sim	exemplo `2026-09-30T16:13:00-03:00`
`pedido`	`Pedido`	sim

Exemplo do contrato

{
  "id": "0199a3c4-5f10-7a2b-8c3d-4e5f60718294",
  "tipo": "pedido.aprovado",
  "criado_em": "2026-09-30T16:42:05-03:00",
  "pedido": {
    "id": "0199a3c4-5f10-7a2b-8c3d-4e5f60718293",
    "numero_comprador": "45882",
    "situacao": "pronto",
    "origem": "pdf",
    "recebido_em": "2026-09-30T16:13:00-03:00",
    "aprovado_em": "2026-09-30T16:42:00-03:00",
    "comprador": {
      "cnpj": "12345678000195",
      "razao_social": "Distribuidora Rio Claro Ltda",
      "codigo_erp": "C001"
    },
    "vendedor": {
      "nome": "Carlos Menezes",
      "email": "carlos.menezes@valeazul.com.br",
      "codigo_erp": null
    },
    "condicao_pagamento": "28/42/56 dias",
    "data_pedido": "2026-09-29",
    "data_entrega": "2026-10-07",
    "endereco_entrega": "CD Rio Claro, Av. Brasil, 2150",
    "observacoes": null,
    "itens": [
      {
        "linha": 4,
        "codigo_comprador": "004359",
        "descricao_comprador": "LIMPA VIDROS REFIL 500ML CX12",
        "produto": {
          "sku": "VA-LVD-500R",
          "codigo_erp": "4359",
          "descricao": "Limpa-vidros refil 500 ml",
          "ean": "7896543000415"
        },
        "quantidade": 30,
        "unidade": "CX",
        "quantidade_erp": 360,
        "unidade_erp": "UN",
        "preco_unitario": 76.04,
        "valor_total": 2281.2,
        "data_entrega": null
      }
    ],
    "valor_total": 2281.2,
    "revisao": {
      "revisado_por": "Marina Costa",
      "revisado_em": "2026-09-30T16:40:00-03:00",
      "motivos": [
        "preco"
      ]
    },
    "numero_erp": null,
    "arquivo_original": "https://arquivos.exemplo.com/pedido-45882.pdf"
  }
}

O que o ERP responde

Código	O que quer dizer	Corpo
`200`	Recebido. Se já lançou, devolva o número do ERP para confirmar na hora.	`RespostaAviso` (application/json)

Aviso de teste

POSTendereço do ERPSofteum-Evento: teste

Enviado só quando alguém usa o botão Enviar teste no painel (Integração → Como o ERP recebe → Aviso no endereço do ERP). Não leva pedido.
Mesmos cabeçalhos do aviso de pedido, com Softeum-Evento: teste.
Confira a assinatura e responda 2xx; não lance nada.

Sem a chave de acesso: o ERP confere a assinatura do aviso (guia, seção 5).

Corpo do aviso

application/json, obrigatório. Modelo EventoTeste.

Campo	Tipo	Obrigatório	O que é
`id`	texto (uuid)	sim	Identificador deste aviso.
`tipo`	texto	sim	sempre `teste`
`criado_em`	data e hora (ISO 8601, com fuso)	sim	exemplo `2026-09-30T16:13:00-03:00`

Exemplo do contrato

{
  "id": "0199a3c4-5f10-7a2b-8c3d-4e5f60718295",
  "tipo": "teste",
  "criado_em": "2026-09-30T16:45:00-03:00"
}

O que o ERP responde

Código	O que quer dizer	Corpo
`200`	Recebido.	sem corpo

Modelos

Os objetos que a API recebe e devolve, campo a campo.

`Problema`

Campo	Tipo	Obrigatório	O que é
`type`	texto	sim	Endereço que identifica o tipo de erro. exemplo `https://softeum.com.br/erros/validacao`
`title`	texto	sim	exemplo `Dados inválidos`
`status`	inteiro	sim	de 400 a 599
`detail`	texto	não
`erros`	lista de objeto	não	Um item por campo com problema: até 100 (o detail diz quantos são ao todo).
`erros[].campo`	texto	sim	exemplo `produtos[3].ean`
`erros[].mensagem`	texto	sim	exemplo `EAN com dígito verificador inválido.`

`DescontoDoItem`

Campo	Tipo	Obrigatório	O que é
`percentual`	número	sim	O percentual escrito no documento (10,50% → 10.5): maior que 0 e até 100 (100: o item bonificado). Até 4 casas. maior que 0 e até 100; exemplo `10.5`
`tipo`	texto	sim	O tipo escrito junto do desconto. valores: `comercial`, `especial`, `promocional`; exemplo `comercial`

`ItemPedido`

Campo	Tipo	Obrigatório	O que é
`linha`	inteiro	sim	Posição do item no documento do comprador. maior que 0
`codigo_comprador`	texto ou `null`	sim	Código do produto como o comprador escreveu. exemplo `004359`
`descricao_comprador`	texto ou `null`	sim	exemplo `LIMPA VIDROS REFIL 500ML CX12`
`produto`	objeto	sim
`produto.sku`	texto	sim	exemplo `VA-LVD-500R`
`produto.codigo_erp`	texto ou `null`	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`produto.descricao`	texto	sim	exemplo `Limpa-vidros refil 500 ml`
`produto.ean`	texto ou `null`	sim
`quantidade`	número	sim	Quantidade como o comprador pediu. maior que 0; exemplo `30`
`unidade`	texto ou `null`	sim	exemplo `CX`
`quantidade_erp`	número	sim	Quantidade já convertida para a unidade do ERP (ex.: 30 CX → 360 UN). maior que 0; exemplo `360`
`unidade_erp`	texto	sim	Unidade de quantidade_erp, do cadastro do produto (nunca do texto do comprador): a embalagem do produto vendido por medida (KG, L, M) ou com 1 unidade (CX); UN na embalagem com mais de uma. exemplo `UN`
`preco_unitario`	número	sim	Preço que vai para o ERP, por unidade do comprador: o do pedido, o decidido na revisão ou o da tabela de preço, conforme a regra de preço da indústria. Já vem com o desconto do pedido: o desconto do próprio item e o desconto sobre o total, distribuído nos itens em proporção ao valor de cada um (a soma dos itens dá o total do documento). a partir de 0; exemplo `76.04`
`valor_total`	número	sim	Reais, até 2 casas decimais. a partir de 0; exemplo `2281.2`
`data_entrega`	data (aaaa-mm-dd) ou `null`	sim	Data de entrega deste item, quando o documento do comprador traz uma por item. Nula: vale a data_entrega do pedido. exemplo `2026-10-07`
`desconto`	`DescontoDoItem` ou `null`	não	O desconto do próprio item, como está no documento. Só vem quando a indústria lê o desconto de cada item (a equipe Softeum liga); nela, null no item sem desconto. O preco_unitario já vem com esse desconto: não aplique de novo (o preço de tabela do pedido é preco_unitario ÷ (1 − percentual ÷ 100)).

`Pedido`

Campo	Tipo	Obrigatório	O que é
`id`	texto (uuid)	sim	Identificador do pedido no Softeum. Use como chave para não lançar o mesmo pedido duas vezes.
`teste`	`true`	não	Só no pedido de teste, criado no painel (Integração → Como o ERP recebe → O ERP busca os pedidos → Criar pedido de teste) para a TI testar a busca, a confirmação e a recusa. Ele vem com os cadastros da indústria, então o ERP de homologação consegue lançá-lo; no ERP de produção, recuse com o motivo (o pedido sai da fila). Nos outros pedidos a chave nem aparece.
`numero_comprador`	texto	sim	Número do pedido no documento do comprador. exemplo `45882`
`situacao`	texto	sim	pronto: aprovado e esperando o ERP; enviado: o aviso chegou ao ERP; confirmado: o ERP lançou e devolveu o número; erro: o ERP recusou ou não respondeu. valores: `pronto`, `enviado`, `confirmado`, `erro`
`origem`	texto	sim	De onde o pedido foi lido: anexo PDF, documento Word (.docx), planilha, XML, imagem (foto ou print do pedido, anexado ou colado no e-mail), texto do e-mail ou arquivo importado no painel. Trate um valor desconhecido como genérico: a lista pode crescer. valores: `pdf`, `word`, `excel`, `xml`, `imagem`, `corpo`, `importado`
`recebido_em`	data e hora (ISO 8601, com fuso)	sim	Quando o e-mail chegou. exemplo `2026-09-30T16:13:00-03:00`
`aprovado_em`	data e hora (ISO 8601, com fuso)	sim	Quando o pedido ficou pronto (direto ou depois da revisão). exemplo `2026-09-30T16:13:00-03:00`
`comprador`	objeto	sim
`comprador.cnpj`	texto	sim	CNPJ só com números (14 dígitos), com dígitos verificadores válidos: o do comprador do cadastro do Softeum (o lido do documento fica no histórico do pedido). formato `^\d{14}$`; exemplo `12345678000195`
`comprador.razao_social`	texto	sim	exemplo `Distribuidora Rio Claro Ltda`
`comprador.codigo_erp`	texto ou `null`	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`vendedor`	objeto ou `null`	sim	Vendedor que encaminhou o e-mail.
`vendedor.nome`	texto	sim	exemplo `Carlos Menezes`
`vendedor.email`	texto (e-mail)	sim	exemplo `carlos.menezes@valeazul.com.br`
`vendedor.codigo_erp`	texto ou `null`	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`condicao_pagamento`	texto ou `null`	sim	exemplo `28/42/56 dias`
`data_pedido`	data (aaaa-mm-dd) ou `null`	sim	Data em que o comprador fez o pedido, como o documento traz (a emissão). Nula quando o documento não traz: use recebido_em. O e-mail encaminhado dias depois não muda esta data. exemplo `2026-10-07`
`data_entrega`	data (aaaa-mm-dd) ou `null`	sim	Data de entrega do pedido. Quando os itens trazem datas diferentes, o pedido passou pela revisão, e a de cada item vem em itens[].data_entrega. exemplo `2026-10-07`
`endereco_entrega`	texto ou `null`	sim
`observacoes`	texto ou `null`	sim
`itens`	lista de `ItemPedido`	sim	pelo menos 1 item
`valor_total`	número	sim	Soma do valor_total dos itens, já com as decisões da revisão (item tirado do pedido não entra). a partir de 0; exemplo `2281.2`
`revisao`	objeto ou `null`	sim	Preenchido quando o pedido passou pela revisão do time.
`revisao.revisado_por`	texto	sim	exemplo `Marina Costa`
`revisao.revisado_em`	data e hora (ISO 8601, com fuso)	sim	exemplo `2026-09-30T16:13:00-03:00`
`revisao.motivos`	lista de texto	sim	Os códigos do que mandou o pedido para a revisão: `preco`, `depara`, `cnpj`, `faltam`, `catalogo`, `duplicado`, `valor`, `leitura` e `sempre_revisar`. Os avisos, que não mandam o pedido para a revisão, não entram. exemplo `["preco"]`
`numero_erp`	texto ou `null`	sim	Número do pedido no ERP, depois da confirmação. exemplo `584460`
`arquivo_original`	texto (URL)	sim	Link temporário para baixar o documento original do comprador.

`ConfirmacaoErp`

Campo	Tipo	Obrigatório	O que é
`numero_erp`	texto	sim	Número do pedido no ERP. de 1 a 60 caracteres; exemplo `584460`
`lancado_em`	data e hora (ISO 8601, com fuso)	não	Quando o ERP lançou o pedido (se não vier, vale a hora da confirmação). exemplo `2026-09-30T16:13:00-03:00`

`RecusaErp`

Campo	Tipo	Obrigatório	O que é
`motivo`	texto	sim	Por que o ERP não aceitou. Aparece para o time da indústria no painel. de 3 a 500 caracteres; exemplo `Condição de pagamento 28/56 não existe no ERP.`

`ResumoPedido`

Campo	Tipo	Obrigatório	O que é
`id`	texto (uuid)	sim	id do pedido no Softeum.
`situacao`	texto	sim	A situação depois da confirmação (confirmado) ou da recusa (erro). valores: `pronto`, `enviado`, `confirmado`, `erro`
`numero_erp`	texto ou `null`	sim	Número do pedido no ERP (null enquanto não confirmado).

`ListaPedidos`

Campo	Tipo	Obrigatório	O que é
`dados`	lista de `Pedido`	sim
`proximo_cursor`	texto ou `null`	sim	Passe em ?cursor= para buscar a próxima página. null = acabou.

`ProdutoErp`

Campo	Tipo	Obrigatório	O que é
`codigo_erp`	texto	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`sku`	texto	sim	de 1 a 60 caracteres; exemplo `VA-LVD-500R`
`descricao`	texto	sim	de 1 a 300 caracteres; exemplo `Limpa-vidros refil 500 ml`
`ean`	texto ou `null`	não	formato `^(\d{8}\|\d{12,14})$`
`embalagem`	texto	sim	Embalagem de venda. de 1 a 10 caracteres; exemplo `CX`
`unidades_por_embalagem`	inteiro	sim	maior que 0; exemplo `12`
`ncm`	texto ou `null`	não	formato `^\d{8}$`
`ipi_pct`	número	não	de 0 a 100; padrão `0`
`linha`	texto ou `null`	não	até 80 caracteres
`ativo`	`true` ou `false`	não	padrão `true`

`CompradorErp`

Campo	Tipo	Obrigatório	O que é
`codigo_erp`	texto	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`cnpj`	texto	sim	CNPJ só com números (14 dígitos), com dígitos verificadores válidos. formato `^\d{14}$`; exemplo `12345678000195`
`razao_social`	texto	sim	de 1 a 200 caracteres
`nome_fantasia`	texto ou `null`	não	até 200 caracteres
`cidade`	texto ou `null`	não	até 120 caracteres
`uf`	texto ou `null`	não	Estado do comprador, a sigla com 2 letras maiúsculas. Casa com a tabela de preço pelos estados, criada no painel. formato `^[A-Z]{2}$`; exemplo `SP`
`regiao`	texto ou `null`	não	Região de preço (casa com as tabelas de nível região). até 60 caracteres; exemplo `Sudeste`
`codigo_vendedor`	texto ou `null`	não	codigo_erp do vendedor responsável. de 1 a 60 caracteres; exemplo `C001`
`codigo_tabela_preco`	texto ou `null`	não	codigo_erp da tabela do comprador (nível 2), se houver. de 1 a 60 caracteres; exemplo `C001`
`ativo`	`true` ou `false`	não	false = bloqueado: pedidos dele vão para a revisão. padrão `true`

`VendedorErp`

Campo	Tipo	Obrigatório	O que é
`codigo_erp`	texto	sim	Código do registro no ERP do cliente. de 1 a 60 caracteres; exemplo `C001`
`nome`	texto	sim	de 1 a 120 caracteres
`email`	texto (e-mail) ou `null`	não	E-mail que encaminha os pedidos. Outros endereços do mesmo vendedor se cadastram no painel. exemplo `carlos.menezes@valeazul.com.br`
`ativo`	`true` ou `false`	não	padrão `true`

`TabelaPrecoErp`

Campo	Tipo	Obrigatório	O que é
`nome`	texto	sim	de 1 a 120 caracteres; exemplo `Tabela Sudeste`
`nivel`	texto	sim	Em cada item vale o primeiro que tiver preço: especifico (de um comprador), comprador (tabela atribuída ao comprador), regiao, padrao. valores: `especifico`, `comprador`, `regiao`, `padrao`
`codigo_comprador`	texto ou `null`	não	Obrigatório no nível especifico. de 1 a 60 caracteres; exemplo `C001`
`regiao`	texto ou `null`	não	Obrigatória no nível regiao. até 60 caracteres
`vigencia_inicio`	data (aaaa-mm-dd)	sim	exemplo `2026-10-07`
`vigencia_fim`	data (aaaa-mm-dd) ou `null`	não	exemplo `2026-10-07`
`precos`	lista de objeto	sim	Todos os preços da tabela: o que não vier aqui sai da tabela. até 20.000 itens
`precos[].codigo_produto`	texto	sim	codigo_erp do produto. de 1 a 60 caracteres; exemplo `C001`
`precos[].preco`	número	sim	Preço líquido (sem impostos) por embalagem de venda. a partir de 0; exemplo `76.04`

`LoteProdutos`

Campo	Tipo	Obrigatório	O que é
`produtos`	lista de `ProdutoErp`	sim	de 1 a 1.000 itens

`LoteCompradores`

Campo	Tipo	Obrigatório	O que é
`compradores`	lista de `CompradorErp`	sim	de 1 a 1.000 itens

`LoteVendedores`

Campo	Tipo	Obrigatório	O que é
`vendedores`	lista de `VendedorErp`	sim	de 1 a 1.000 itens

`ResultadoSincronizacao`

Campo	Tipo	Obrigatório	O que é
`criados`	inteiro	sim	a partir de 0
`atualizados`	inteiro	sim	a partir de 0
`erros`	lista de objeto	sim	Registros recusados (o resto do lote é gravado).
`erros[].indice`	inteiro	sim	a partir de 0
`erros[].campo`	texto	sim
`erros[].mensagem`	texto	sim

`EventoPedido`

Campo	Tipo	Obrigatório	O que é
`id`	texto (uuid)	sim	Identificador deste aviso (o mesmo nos reenvios).
`tipo`	texto	sim	valores: `pedido.aprovado`
`criado_em`	data e hora (ISO 8601, com fuso)	sim	exemplo `2026-09-30T16:13:00-03:00`
`pedido`	`Pedido`	sim

`EventoTeste`

Campo	Tipo	Obrigatório	O que é
`id`	texto (uuid)	sim	Identificador deste aviso.
`tipo`	texto	sim	sempre `teste`
`criado_em`	data e hora (ISO 8601, com fuso)	sim	exemplo `2026-09-30T16:13:00-03:00`

`RespostaAviso`

Corpo opcional da resposta 2xx do ERP.

Campo	Tipo	Obrigatório	O que é
`numero_erp`	texto	não	Se o ERP já lançou o pedido ao receber o aviso, devolva o número aqui e ele fica confirmado na hora. de 1 a 60 caracteres