API de gasto - PUBLICAR /sn_sn_spend_intg/spenint/shipment

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 6 min. de leitura

    • Use este endpoint para aceitar atualizações em compras de terceiros.

    Ao receber dados, você deve corresponder os dados da remessa a uma linha de ordem de compra usando o número da linha da ordem de vendas. Você pode usar o número de rastreamento para encontrar um registro de detalhes da remessa existente relacionado à linha da ordem de compra. Se nenhum registro desse tipo for encontrado, crie um novo registro de detalhes da remessa. Se não existir nenhuma ordem de compra ou linha de ordem de compra para os dados de envio, você verá uma mensagem de erro informando que a ordem de compra para esta remessa não existe.
    Nota:
    Se a ordem de compra e as linhas da ordem de compra estiverem no status Envio pendente e as linhas da ordem de vendas e da ordem de vendas não estiverem preenchidas, a remessa e a publicação da fatura do revendedor terceirizado não serão permitidas. Isso só é permitido quando o status da ordem de compra e das linhas da ordem de compra são Solicitadas. Além disso, não há restrições sequenciais na expedição e na publicação da fatura.

    Tabelas de status

    Para saber o status da solicitação de envio, faça uma chamada REST no ServiceNowbanco de dados usando o. Tabela REST API. A resposta da API lista os registros em que a atualização de envio falhou. Para obter uma resposta de envio, consulte a tabela Erro de remessa com o seguinte parâmetro:

    <supplier_id>_query_outbound_error.supplier_id_id_outbound_error.state: 20

    Os detalhes sobre o ID do cliente, ID do fornecedor, tipo de erro, ID do conjunto de importação exclusivo e estado podem ser encontrados na tabela Status de saída, que é a tabela de erros primária.

    Formato de URL

    /api/sn_sn_spend_intg/spenint/shipment

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    Nenhum(a)
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    modo Suporte para modos assíncrono e síncrono para integração de terceiros.

    Tipo de dados: Cadeia de caracteres

    Valores válidos:
    • Assíncrono: Modo assíncrono.
    • Sincronização: Modo síncrono.

    Padrão: Assíncrono
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    customer_id Identificador do cliente.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 100
    order_number Necessário. Número da ordem de compra fornecido pelo cliente para este pedido.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40
    sales_order_number Necessário. Número ou valor gerado pelo fornecedor para este pedido.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40
    shipment_lines Lista de linhas de remessa que podem conter o número de série, o número IMEI e os detalhes da etiqueta de ativo dos ativos.

    Tipo de dados: Matriz

    "shipment_lines": [
  {
    "actual_shipment_date": "String",
    "estimated_arrival_date": "String",
    "line_number": "String",
    "planned_shipment_date": "String",
    "product_details": [Array],
    "sales_order_line_number": "String",
    "shipping_address": {Object},
    "shipping_carrier": "String",
    "shipment_quantity": "String",
    "ship_to": "String",
    "tracking_number": "String"
  }
]
    shipment_lines.actual_shipment_date Data em que a remessa sai do local do fornecedor.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40

    FORMATO: AAAA-MM-DD
    shipment_lines.estimated_arrival_date Data em que a remessa deve chegar ao local especificado.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40

    FORMATO: AAAA-MM-DD
    shipment_lines.line_number Necessário. Número da linha da ordem de compra que é gerado pelo cliente para uma compra específica.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40
    shipment_lines.planned_shipment_date Data em que a remessa está planejada para deixar o local do fornecedor.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40

    FORMATO: AAAA-MM-DD
    shipment_lines.product_details Lista de objetos que definem os detalhes sobre os produtos que estão sendo enviados. As opções incluem o número de série, o número IMEI e os detalhes da etiqueta do ativo.

    Tipo de dados: Matriz

    "product_details": [
  {
    "asset_tag": "String",
    "imei": "String",
    "serial_number": "String"
  }
]
    shipment_lines.product_details.asset_tag Etiqueta do ativo do produto enviado.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 100
    shipment_lines.product_details.imei Número IMEI do produto enviado.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 100
    shipment_lines.product_details.serial_number Necessário. Número de série do produto enviado.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 100
    shipment_lines.sales_order_line_number Número da linha do pedido de vendas gerado pelo fornecedor. Este número é necessário somente para revisões desta compra.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40
    shipment_lines.shipping_address Endereço para o qual os produtos serão enviados.

    Tipo de dados: Objeto

    "shipping_address":
  {
    "city": "String",
    "country": "String",
    "name": "String",
    "state": "String",
    "street": "String",
    "zip_code": "String"
  }
    shipment_lines.shipping_address.city Nome da cidade para onde os produtos são enviados.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 1000
    shipment_lines.shipping_address.country País para o qual os produtos são enviados.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40
    shipment_lines.shipping_address.name Nome do cliente para o qual os produtos serão enviados.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 1000
    shipment_lines.shipping_address.state Estado para onde os produtos são enviados.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 1000
    shipment_lines.shipping_address.street Nome da rua para onde os produtos são enviados.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 1000
    shipment_lines.shipping_address.zip_code CEP ou código PIN para o qual os produtos são enviados.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40
    shipment_lines.shipment_quantity Necessário. Número de produtos que estão sendo enviados como mercadorias físicas. O número deve conter a quantidade de produtos que estão na remessa.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 40
    shipment_lines.shipping_carrier Transportadora que está entregando o produto no local especificado, como FedEx, UPS, USPS e assim por diante.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 100
    shipment_lines.ship_to Nome do destinatário para o qual os produtos são enviados.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 100
    shipment_lines.tracking_number Número de rastreamento fornecido pela transportadora para a totalidade ou parte da compra.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 100
    supplier_id Necessário. Identificador do revendedor ou fornecedor com o qual o cliente pode fazer pedidos.

    Tipo de dados: Cadeia de caracteres

    Comprimento máximo: 100
    supplier_shipment_number Necessário. Número de identificação gerado para esta remessa. Normalmente, esse número é gerado por um sistema de planejamento de recursos empresariais (ERP) ou acompanhamento de pedidos.

    Tipo de dados: Cadeia de caracteres

    Comprimento 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

    Comprimento 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.

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Nota:
    Somente o. application/jsonO formato de dados é compatível com a Estrutura de integração de compras.
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP.

    Tabela 6. Códigos de status
    Código de status Descrição
    êxito Bem-sucedido. A solicitação foi processada com sucesso.
    falha Sem sucesso. A solicitação foi processada com erros.

    Parâmetros do corpo da resposta (json)

    Esses parâmetros do corpo de resposta são recebidos quando consultados no modo síncrono.
    Nome Descrição
    error_response_body Descrição dos erros, listados pelo número da linha da ordem de vendas, número da ordem de vendas, número da remessa do fornecedor 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 "Sucesso" ou "Falha".

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    curl "https://instance.service-now.com/api/sn_spend_intg/spendint/shipment" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root":[{
  "customer_id" : "ACME CORP",
  "supplier_id" : "SUP-123456",
  "third_party_import_id": "DEL2134324",
  "supplier_shipment_number" : "TN-YU67898723",
  "order_number": "PO0001002",
  "sales_order_number": "SO00223002",
  "shipment_lines": [
    {
      "line_number": "POL0001005",
      "sales_order_line_number": "SOL0231325",
      "shipment_quantity": "4",
      "shipping_carrier": "FedEx",
      "tracking_number": "E-901290092",
      "shipping_address":
        {
          "name" : "1640 Camino Del Rio North #202, San Diego,CA",
          "street" : "1640 Camino Del Rio North",
          "city" : "San Diego",
          "state" : "CA",
          "zip_code" : "92108-1512",
          "country" : "US"
        },
      "ship_to": "John doe",
      "planned_shipment_date": "YYYY-MM-DD",
      "actual_shipment_date": "YYYY-MM-DD",
      "estimated_arrival_date": "YYYY-MM-DD",
      "product_details": [
        {
          "serial_number": "FL1234-23242319001",
          "imei": "2134890294",
          "asset_tag": ""
        },{
          "serial_number": "FL1234-23242319110",
          "imei": "245499003",
          "asset_tag": ""
        }
      ]
    }
  ]
}
]}

    Respostas possíveis:

    // Success response:
{
    "result": {
        "response": "success"
    }
}

// Error response:
{
    "result": {
        "response": [
            {
                "customer_id": "ACME CORP",
                "supplier_id": "SUP-123456",
                "third_party_import_id": "DEL2134324",
                "status_code": "failure",
                "error_response_body": [
                    {
                        "sales_order_line_number": "SOL0231325",
                        "sales_order_number": "SO00223002",
                        "supplier_shipment_number": "TN-YU67898723",
                        "error_message": "The purchase order for this shipment does not exist\nThe purchase order line for this shipment does not exist\n"
                    }
                ]
            }
        ]
    }
}