Mapeamento de entidades

Como vincular IDs de um sistema externo aos IDs internos do bitERP para garantir idempotência e evitar duplicações na sincronização.

Os mapeamentos de entidade (/integration-entity-mappings) resolvem um problema clássico de integração: relacionar o ID de um registro no seu sistema com o ID correspondente no bitERP. Com esse vínculo, sua sincronização fica idempotente — você sabe se um cliente/produto/nota já foi criado e evita duplicar.

Permissão: o código de permissão deste recurso é integration-mappings — diferente do caminho da URL (integration-entity-mappings). Configure a permissão da API Key com o código integration-mappings (ações read, create, update, delete).

Como funciona

Cada mapeamento liga um internal_entity_id (o UUID do registro no bitERP) a um external_entity_id (o identificador no seu sistema), dentro de um entity_type (ex.: customer, product, invoice) e de uma integração (tenant_integration_id).

A unicidade é garantida por duas chaves compostas: (tenant_integration_id, entity_type, internal_entity_id) e (tenant_integration_id, entity_type, external_entity_id). Na prática, dentro de uma mesma integração e entity_type, um mesmo ID interno não pode mapear para dois externos, nem um mesmo ID externo para dois internos. Tentar criar um mapeamento que viola qualquer uma dessas chaves retorna 409 Conflict — é esse comportamento que torna a operação idempotente.

Manual vs. automático

O campo mapping_origin indica a origem do vínculo:

manual — criado por você via POST /integration-entity-mappings.
automatic — criado pelo próprio bitERP durante fluxos de sincronização. Esse caminho não é exposto pela API; ele aparece apenas na leitura.

mapping_origin, entity_type e internal_entity_id são imutáveis após a criação.

Campos de criação (POST)

Campo	Tipo	Obrigatório	Observações
`tenant_integration_id`	UUID	Sim	A integração à qual o mapeamento pertence
`entity_type`	string	Sim	Tipo da entidade (texto livre, ≤ 100; ex.: `customer`, `product`)
`internal_entity_id`	UUID	Sim	ID do registro no bitERP
`external_entity_id`	string	Sim	ID no sistema externo (≤ 255)
`sync_status`	enum	Não	`synced`, `pending` ou `error` (padrão `synced`)
`metadata`	object	Não	Dados livres da sua integração

entity_type é texto livre (não um enum fechado). Padronize seus próprios valores (customer, product, invoice…) e mantenha-os consistentes.

Criar um mapeamento

curl -X POST https://api.biterp.ai/integration-entity-mappings \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_integration_id": "0193f000-1111-7222-8333-444455556666",
    "entity_type": "customer",
    "internal_entity_id": "0194aaaa-bbbb-7ccc-8ddd-eeeeffff0000",
    "external_entity_id": "cus_QabC123XyZ",
    "sync_status": "synced",
    "metadata": { "source_label": "Cliente no Stripe" }
  }'

A resposta traz id, mapping_origin: "manual", last_synced_at e os campos de auditoria.

Atualizar

PATCH /integration-entity-mappings/{id} altera apenas external_entity_id, sync_status e metadata. Definir sync_status: "synced" atualiza last_synced_at.

Listar e remover

GET /integration-entity-mappings lista de forma paginada. Campos filtráveis: tenant_integration_id, entity_type, sync_status, mapping_origin, internal_entity_id, external_entity_id, created_at, last_synced_at — úteis para localizar um mapeamento pelo ID externo antes de decidir criar ou atualizar um registro. DELETE /integration-entity-mappings/{id} faz soft delete (204 No Content).

Referência dos endpoints

Método	Endpoint	Referência
POST	`/integration-entity-mappings`	Criar mapeamento
GET	`/integration-entity-mappings`	Listar
GET	`/integration-entity-mappings/{id}`	Buscar por ID
PATCH	`/integration-entity-mappings/{id}`	Atualizar
DELETE	`/integration-entity-mappings/{id}`	Remover