Modelo de vínculo no sistema parceiro

Recomendação de como o ERP / sistema parceiro deve relacionar seus cadastros locais aos IDs da API mPm+.

Princípio

Em cada entidade sincronizada, mantenha uma coluna mpm_integracao INTEGER. Grave nela o ID retornado (ou associado) pelo mPm+. Na criação, envie o código interno do ERP na tag integracao do JSON.

Coluna mpm_integracao

Entidade local	Coluna recomendada	Conteúdo
Grupo / categoria	mpm_integracao	ID do grupo no mPm+
Unidade	mpm_integracao	ID da unidade
Produto	mpm_integracao	ID do produto
Cliente	mpm_integracao	ID do cliente
Rota	mpm_integracao	ID da rota
Finalizadora	mpm_integracao	ID da finalizadora
Plano	mpm_integracao	ID do plano
Funcionário / vendedor	mpm_integracao	Em geral o usuario_id / ID mPm+ do funcionário
Pedido	campo de id externo	ID do pedido mPm+ (idempotência)

Tag integracao vs coluna mpm_integracao

Conceito	Onde vive	Valor
Tag integracao	Body JSON (POST / associação)	Código interno do ERP (CAF-001, GRP-01, …)
Coluna mpm_integracao	Banco do parceiro	Inteiro = ID no mPm+ (55001, …)

sequenceDiagram
  participant ERP as Sistema parceiro
  participant DB as Banco do parceiro
  participant API as API mPm+

  ERP->>DB: Lê cadastro (código interno CAF-001, mpm_integracao vazio)
  ERP->>API: POST + integracao = CAF-001
  API-->>ERP: status success, data[0].id = 55001
  ERP->>DB: UPDATE mpm_integracao = 55001
  Note over ERP,API: Atualização futura
  ERP->>API: PUT + header produto_id = 55001
  API-->>ERP: status success

Diagrama conceitual (ER)

erDiagram
  CREDENCIAIS_PARCEIRO {
    string empresa_id
    string token
    string app_nome
    string app_versao
    string plataforma
  }

  GRUPO {
    string codigo_interno PK
    int mpm_integracao
  }

  UNIDADE {
    string codigo_interno PK
    int mpm_integracao
  }

  PRODUTO {
    string codigo_interno PK
    int mpm_integracao
    int grupo_mpm_ref
    int unidade_mpm_ref
  }

  CLIENTE {
    string codigo_interno PK
    int mpm_integracao
  }

  ROTA {
    string codigo_interno PK
    int mpm_integracao
  }

  FINALIZADORA {
    string codigo_interno PK
    int mpm_integracao
  }

  PLANO {
    string codigo_interno PK
    int mpm_integracao
  }

  FUNCIONARIO {
    string codigo_interno PK
    int mpm_integracao
  }

  PEDIDO {
    string codigo_interno PK
    int id_mpm
  }

  GRUPO ||--o{ PRODUTO : "grupo_id mPm+"
  UNIDADE ||--o{ PRODUTO : "unidade_id mPm+"
  CLIENTE ||--o{ PEDIDO : "cliente_id"
  PRODUTO ||--o{ PEDIDO : "itens"
  FINALIZADORA ||--o{ PEDIDO : "pagamentos"
  FUNCIONARIO ||--o{ PEDIDO : "vendedor"
  PLANO ||--o{ PEDIDO : "plano"

Regras práticas

1. POST quando mpm_integracao estiver vazio/nulo → enviar tag integracao com o código ERP.
2. Após sucesso, persistir data[0].id em mpm_integracao.
3. PUT quando já houver ID → enviar header produto_id, grupo_id, etc.
4. Na importação de pedidos, resolver cliente_id, produto_id, finalizadora_id, vendedor_id, plano_id buscando registros locais onde mpm_integracao = ID do payload.
5. Guardar o id do pedido mPm+ para não importar duas vezes.

Atenção

Se o pedido referenciar um ID sem correspondente em mpm_integracao, o parceiro deve rejeitar ou tratar o erro — não inventar cadastro automático sem regra de negócio clara.

Independência de schema

Os nomes das tabelas do ERP são livres. O contrato exige apenas que o parceiro consiga mapear código interno ↔ ID mPm+ de forma estável.