API Spendint - POST /sn_spend_intg/spendint/catalog
Permite que os fornecedores publiquem vários catálogos para criar produtos do fornecedor, produtos modelo, contratos e registros de preço.
Na integração da API do catálogo, ao receber dados de um catálogo de terceiros, você pode:
- Crie novas categorias de terceiros e mapeie essas categorias para categorias de modelo.
- Se disponível, use o Código de Produtos e Serviços Padrão das Estados Unidos (UNSPSC) e o nome da categoria.
- Se o UNSPSC não estiver disponível, use apenas o nome da categoria.
- Depois de mapear uma categoria de terceiros para uma categoria de modelo, use o Número de Peça do Fabricante (MPN) para encontrar um modelo de produto existente, se houver um disponível.
- Se um modelo de produto for encontrado para o MPN, atualize o modelo de produto com todas as mudanças e crie ou atualize todos os produtos do fornecedor que estejam relacionados ao modelo de produto.
- Se um modelo de produto não existir para o MPN, faça o seguinte:
- Uma classe de modelo de produto geralmente está disponível na categoria de modelo referenciada pela categoria de terceiros para o produto. Use esta classe de modelo de produto para obter a tabela do modelo de produto na qual o modelo de produto deve ser criado, por exemplo, hardware, software, consumível e assim por diante. Se nenhuma classe de modelo de produto estiver disponível, crie o modelo de produto na tabela de modelo de produto base.
- Depois que a classe correta do modelo de produto for identificada, crie um novo modelo de produto na classe correta da seguinte forma:
- Fabricante, publicador ou provedor deve mapear para o fabricante no modelo do produto.
- O nome do produto da API deve ser mapeado para o nome no modelo do produto.
- O MPN da API deve atualizar o número do modelo.
- A descrição do produto da API deve atualizar a descrição no modelo do produto.
- A categoria do modelo deve ser atualizada com a categoria do produto referenciada no registro da categoria de terceiros.
- A categoria de produto deve ser atualizada com a categoria de produto referenciada no registro de categoria de terceiros.
- Se houver valores nos produtos substitutos na API, crie os registros do produto substituto entre o modelo de produto atual e os outros modelos de produto.
- Se houver valores nos produtos compatíveis na API, crie os registros de produto compatíveis entre o modelo de produto atual e os outros modelos de produto.
- Os atributos do produto da API devem ser criados ou atualizados na lista relacionada de atributos do produto para o modelo do produto.
- Se um modelo de produto estiver disponível, use o número de peça do fornecedor para criar ou atualizar os produtos do fornecedor relacionados ao modelo de produto.
Mapeamento de terceiros
Use as tabelas a seguir para executar os mapeamentos de categoria, modelo e unidade de terceiros:
- Categorias de terceiros: armazena todos os registros de categoria de terceiros para o administrador do ShoppingHub mapear com as categorias de modelo internas existentes.
- Mapeamentos de modelo de terceiros: armazena todas as informações de mapeamento entre modelos de produto e categorias de modelo de terceiros.
- Unidades de terceiros: armazena todos os registros de unidade de terceiros para o administrador do ShoppingHub mapear com unidades de produto do fornecedor.
- Mapeamentos de unidade de terceiros: armazena todas as informações de mapeamento entre modelos de produto e unidades de terceiros.
Nota:
Um produto de integração de terceiros é publicado automaticamente quando a categoria e a unidade de terceiros são mapeadas corretamente.
Datas de vendas do produto do fornecedor
Um produto do fornecedor é descontinuado e não é mais publicado no catálogo quando atinge a data de término das vendas. Os campos Data de início das vendas e Data de término das vendas no formulário de produto do fornecedor são preenchidos por meio da integração de terceiros da API docatálogo.
Tabelas de status
Para saber o status da solicitação de importação de produto em massa, faça uma chamada REST no banco de dados ServiceNow usando a REST API da tabela. A resposta da API lista os registros em que a solicitação de importação em massa falhou. Para obter uma resposta de importação de produto em massa, consulte a tabela Erro de catálogo com o seguinte parâmetro:
sysparm_query=outbound_error.supplier_id=<supplier_id> ^outbound_error.state=20
Detalhes sobre o ID do cliente, o ID do fornecedor, o tipo de erro, o ID exclusivo do conjunto de importação e o estado podem ser encontrados na tabela Status de saída, que é a tabela de erros primária.
Formato de URL
/api/sn_spend_intg/spendint/catalog
Parâmetros de solicitação compatíveis
| Nome | Descrição |
|---|---|
| Nenhum |
| Nome | Descrição |
|---|---|
| Modo | Suporte para modos assíncronos e síncronos para integração de terceiros. Tipo de dados: cadeia de caracteres Valores válidos:
Padrão: assíncrono |
| Nome | Descrição |
|---|---|
| customer_id | Identificador do cliente. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| catalog_id | Identificador do conteúdo do catálogo que pode ser comprado por um cliente. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| produtos | Lista de objetos que definem produtos a serem criados ou atualizados. Cada transação tem um limite de 1.000 produtos. Tipo de dados: matriz |
| produtos.unidades_disponíveis | Obrigatório para produtos que são mantidos em estoque. Este valor indica a quantidade de unidades disponíveis para este produto. Tipo de dados: cadeia de caracteres Tamanho máximo: 40 |
| produtos.disponível_para_país | Lista de códigos de país onde o produto do fornecedor pode ser comprado. Se nenhum país for fornecido, um usuário de qualquer país poderá comprar o produto. Tipo de dados: matriz |
| product.bundled_components | Válido somente para cenários ao enviar um pacote de produtos como parte da carga do catálogo e aplicável somente para as cargas do pacote primário. Este valor contém a referência aos componentes do pacote secundário. A lista de MPN e as quantidades dos componentes do pacote secundário são mantidas aqui. Nota: Os componentes do pacote secundário e seus detalhes (MPN e quantidades) devem ser mapeados para o mesmo fornecedor.Como o mesmo componente de pacote secundário pode ser adicionado mais de uma vez em um pacote, a quantidade inserida é o diferenciador entre os mesmos componentes de pacote secundário. Tipo de dados: matriz |
| produtos.contrato_acordo | Detalhes do contrato de um produto. Nota:
Isso não é necessário para componentes de pacote secundário. Tipo de dados: objeto |
| produtos.contrato_acordo.contract_end_date | Data em que o prazo do contrato termina. Tipo de dados: cadeia de caracteres Tamanho máximo: 40 Formato: AAAA-MM-DD |
| produtos.contrato_acordo.contract_number | Obrigatório. Número do contrato ativo que está associado ao produto. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| produtos.contrato_acordo.contrato_início_data | Data em que o prazo do contrato começa. Tipo de dados: cadeia de caracteres Tamanho máximo: 40 Formato: AAAA-MM-DD |
| productos.contrato_acordo.negociada_moeda | Obrigatório. Moeda do preço negociado. Tipo de dados: cadeia de caracteres Tamanho máximo: 40 |
| produtos.contrato_acordo.preço_negociado | Obrigatório. Preço unitário de um produto conforme negociado por meio de um contrato com o fornecedor ou revendedor. Tipo de dados: cadeia de caracteres Tamanho máximo: 40 |
| produtos.tempo_de_entrega | Número estimado de dias necessários para enviar um produto ao cliente. Este valor deve representar o número de dias e ser um número inteiro. Tipo de dados: cadeia de caracteres Tamanho máximo: 40 |
| product.images | Lista de cadeias de caracteres que especificam os URLs de imagem do produto do fornecedor. Tipo de dados: matriz |
| product.manufacturer | Obrigatório. Empresa que produz, publica ou fornece o produto. Este não é o fornecedor ou o revendedor do produto. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| product.mpn | Obrigatório. Identificador de um produto fornecido pelo fabricante, fornecedor ou fornecedor. Nota:
Isso não será necessário para pacotes primários do revendedor se o valor de SKU estiver disponível. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| produtos.parent_bundle | Válido somente para cenários ao enviar um pacote de produtos como parte da carga do catálogo e aplicável somente para as cargas do componente do pacote secundário. No caso de um componente de pacote secundário, a referência ao primário é mantida aqui. Os valores de MPN e SKU primários também são definidos aqui. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| product_attributes | Lista de pares de chave-valor que definem atributos do produto, por exemplo, "Cor": "Espaço Cinza". Vários atributos para um produto são permitidos. No entanto, somente os atributos que afetam o preço ou a disponibilidade de estoque devem ser fornecidos por meio da API.Tipo de dados: objeto |
| produtos.product_category_name | Obrigatório. Nome que você insere se não estiver definindo a propriedade unspsc. Este nome é a categoria à qual um produto pertence. Este nome de categoria pode ser usado em um cenário de comércio para comprar o produto. Por exemplo, um produto de filtro de linha pode pertencer a uma categoria de equipamento de escritório. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| produtos.product_description | Descrição completa do produto que aparece para um comprador em uma experiência de comércio. Nota:
É recomendável que o fornecedor seja o mais descritivo possível aqui, especialmente para itens do catálogo de pacote de produtos em que há componentes de pacote secundário. Tipo de dados: cadeia de caracteres Tamanho máximo: 65000 |
| produtos.nome_do_produto | Obrigatório. Nome do produto. Tipo de dados: cadeia de caracteres Tamanho máximo: 1000 |
| product.sku | Obrigatório. Número gerado por um fornecedor que identifica exclusivamente um produto vendido por esse fornecedor. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| produtos.unidade | Obrigatório. Unidade ou taxa na qual o produto é vendido pelo fornecedor. Por exemplo, peças, horas e assim por diante. Tipo de dados: cadeia de caracteres Tamanho máximo: 40 |
| produtos.unspc | Obrigatório. Identificador que você insere se não estiver definindo a propriedade product_category_name. Este identificador é o UNSPSC da categoria à qual um produto pertence. Por exemplo, o código UNSPSC 43210000 é o identificador da categoria de produto Computadores. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| fornecedor_id | Obrigatório. Identificador do revendedor ou fornecedor com quem o cliente pode fazer pedidos. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
| third_party_import_id | Identificador que permite que um terceiro passe um valor de cadeia de caracteres para identificar exclusivamente um conjunto de dados importados. Tipo de dados: cadeia de caracteres Tamanho máximo: 100 |
Cabeçalhos
Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta.
| Cabeçalho | Descrição |
|---|---|
| Aceitar | Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml. Padrão: application/json |
Nota:
Somente o formato de dados application/json é compatível com o Procurement Integration Framework.
| Cabeçalho | Descrição |
|---|---|
| Nenhum |
Códigos de status
Os códigos de status a seguir se aplicam a esta ação HTTP.
| Código de status | Descrição |
|---|---|
| êxito | Bem-sucedido. A solicitação foi processada com sucesso. |
| falha | Falha. A solicitação foi processada com erros. |
Parâmetros do corpo da resposta (JSON)
Esses parâmetros de corpo de resposta são recebidos quando consultados no modo síncrono.| Nome | Descrição |
|---|---|
| erro_resposta_corpo | Descrição dos erros, listados por sku, mpn e a mensagem de erro. Tipo de dados: matriz |
| error_response_body.error_message | Mensagem de erro detalhada. Tipo de dados: cadeia de caracteres |
| status_code | Status da resposta, como "Êxito" ou "Falha". Tipo de dados: cadeia de caracteres |
Solicitação de cURL
curl "https://instance.service-now.com/api/sn_spend_intg/spendint/catalog" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root": [{
"customer_id": "AB-1234323",
"catalog_id": "ACME CORP-12347898",
"supplier_id": "SUP-123456",
"third_party_import_id": "DELL1234567",
"products": [
{
"product_name": "Apple MacBook Pro 13 Core i7",
"mpn": "Z0WQ-20004301931",
"sku": "55788741",
"manufacturer": "Apple",
"product_category_name": "Computer",
"parent_bundle": "920-0045362002",
"bundled_components": {
"mpn": "Z0WQ-20004301931",
"quantity": "4",
},
"unspsc": "43211500",
"product_description": "Apple MacBook Pro 13 Core i7 2.8GHz 16GB 512GB - Touch Bar - Space Gray",
"product_attributes": {
"Color": "Space Grey",
"RAM": "16GB",
"Screen Size": "13inch"
},
"images": ["http://test123.image1.png", "http://test123.image2.jpeg"],
"unit": "Each",
"available_units": "4",
"available_for_country": ["US","IN","GB"],
"delivery_time": "4",
"contract_agreement": {
"contract_number": "34567892",
"contract_start_date": "YYYY-MM-DD",
"contract_end_date": "YYYY-MM-DD",
"negotiated_price": "456",
"negotiated_currency ": "USD"
}
}
]
}
]}
Possíveis respostas:
// Success response:
{
"result": {
"response": "success"
}
}
// Error response:
{
"result": {
"response": [
{
"customer_id": "AB-1234323",
"supplier_id": "SUP-123456",
"third_party_import_id": "DELL1234567",
"status_code": "failure",
"error_response_body": [
{
"sku": "55788741",
"mpn": "Z0WQ-20004301931",
"error_message": "Field Value empty/Formatting issue Negotiated currency \n"
}
]
}
]
}
}