YOM Docs

Os comodatos são os equipamentos que você entrega aos seus comércios para que eles os usem, mantendo você a propriedade do equipamento.

O que é informado como comodato? Cada registro representa um equipamento entregue a um comércio sob um contrato de comodato — por exemplo um freezer, um refrigerador ou um expositor instalado no ponto de venda.

Um Comodato contém a identificação do equipamento, o Comércio onde está instalado, a vigência do contrato e o Vendedor responsável. Com essa informação a YOM pode mostrar o parque de equipamentos instalado em cada comércio e dar contexto às solicitações de novos equipamentos.

Endpoint

O endpoint de Comodatos permite que a YOM acesse informações detalhadas sobre cada equipamento entregue em comodato.

GET /api/comodatos

Campos

A tabela a seguir define o modelo base de integração da entidade Comodato. Esse modelo corresponde ao contrato base e é extensível: pode ser complementado com atributos adicionais por meio do objeto otherProperties, conforme descrito na seção Atributos adicionais.

Comodato

Campo Tipo Obrigatoriedade Descrição Exemplos
comodatoId 📝 Texto 🟢 Obrigatório Identificador único do Comodato.
*\Deve ser estável ao longo do tempo: é a chave com a qual a YOM identifica o registro em cada atualização. “COM-00123”
commerceId 📝 Texto → Comércios 🟢 Obrigatório Id do Comércio onde o equipamento está instalado.
*\Deve ser o mesmo identificador informado no endpoint de Comércios. “12345”
equipmentType 📝 Texto 🟢 Obrigatório Tipo de equipamento entregue. “Congelador 400L”
equipmentCode 📝 Texto ⚪ Opcional Código do modelo ou item do equipamento. “CONG-400”
brand 📝 Texto ⚪ Opcional Marca do equipamento. “Electrolux”
serialNumber 📝 Texto ⚪ Opcional Número de série da unidade física entregue. “SN-8891233”
quantity 🔢 Número ⚪ Opcional Quantidade de equipamentos do mesmo tipo cobertos pelo registro.
*\*Se não for informado, assume-se *1. Quando o equipamento tem número de série, recomenda-se um registro por unidade. 1
contractNumber 📝 Texto ⚪ Opcional Número do contrato de comodato assinado com o Comércio. “CT-2026-0891”
startDate 📅 Data 🟢 Obrigatório Data de início do comodato, ou seja, de entrega ou instalação do equipamento.
*\A data deve estar no formato ISO 8601. “2026-03-15”
“2026-03-15T00:00:00.000Z”
endDate 📅 Data ⚪ Opcional Data de término do contrato, quando tem prazo definido.
*\A data deve estar no formato ISO 8601. “2027-03-15”
withdrawalDate 📅 Data ⚪ Opcional Data de retirada efetiva do equipamento do Comércio.
*\A data deve estar no formato ISO 8601. “2026-11-02”
isInactive 🔘 Bool 🟢 Obrigatório O comodato está encerrado?
*\*Um equipamento retirado ou um contrato finalizado é informado com *true, mantendo o registro histórico. true
false
status 📝 Texto ⚪ Opcional Status do comodato tal como o seu sistema o nomeia.
*\*É informativo e complementa *isInactive, não o substitui. “Vigente”
“Retirado”
sellerId 📝 Texto → Vendedores ⚪ Opcional Id do Vendedor responsável pelo equipamento. “1234”
otherProperties 📝 Objeto ⚪ Opcional Objeto chave-valor com atributos adicionais do Comodato. Ver seção Atributos adicionais. {"maintenanceFrequency": "Semestral", "assetOwner": "Planta Norte"}

Atributos adicionais (otherProperties)

O modelo documentado nesta página corresponde ao contrato base da entidade Comodato. Além dos campos base, os clientes podem disponibilizar atributos adicionais para identificação, classificação, manutenção ou análise, por meio do objeto otherProperties.

Alguns exemplos de atributos adicionais são: frequência de manutenção, planta ou depósito proprietário do ativo, valor contábil do equipamento, capacidade em litros ou responsável interno pelo contrato.

Os atributos dentro de otherProperties devem cumprir as seguintes condições:

A YOM poderá conservar esses atributos como informação estendida quando o mecanismo de integração e o pipeline permitirem. Receber um atributo não implica que a YOM o utilize automaticamente: seu uso deve ser validado durante a implementação.

Exemplo com atributos adicionais maintenanceFrequency, assetOwner e capacityLiters:

{
  "comodatoId": "COM-00123",
  "commerceId": "12345",
  "equipmentType": "Congelador 400L",
  "startDate": "2026-03-15T00:00:00.000Z",
  "isInactive": false,
  "otherProperties": {
    "maintenanceFrequency": "Semestral",
    "assetOwner": "Planta Norte",
    "capacityLiters": 400
  }
}

Resposta