API Spendint - POST /sn_spend_intg/spendint/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 de 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 acompanhamento para encontrar um registro de detalhes de remessa existente que esteja relacionado à linha da ordem de compra. Se esse registro não for encontrado, crie um novo registro de detalhes da remessa. Se não houver ordem de compra ou linha de ordem de compra para os dados da remessa, você verá uma mensagem de erro informando que a ordem de compra para esta remessa não existe.
    Nota:
    Se as linhas da ordem de compra e da ordem de compra estiverem com o status Envio pendente e as linhas da ordem de vendas e da ordem de vendas não estiverem preenchidas, a publicação de remessa e fatura do revendedor terceirizado não será permitida. Isso só é permitido quando o status da ordem de compra e as linhas da ordem de compra são Encomendado. Além disso, não há restrição sequencial na publicação de remessa e fatura.

    Tabelas de status

    Para saber o status da solicitação de envio, faça uma chamada REST no banco de dados ServiceNow usando a API REST de tabela. 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:

    sysparm_query=outbound_error.supplier_id=<supplier_id> ^outbound_error.state=20

    Os detalhes sobre 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 da URL

    /api/sn_spend_intg/spendint/remessa

    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íncronos e síncronos para integração de terceiros.

    Tipo de dados: cadeia de caracteres

    Valores válidos:
    • async: modo assíncrono.
    • sincronizar: 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

    Tamanho máximo: 100
    order_number Obrigatório. Número da ordem de compra fornecido pelo cliente para esta ordem.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    número_pedido_de_vendas Obrigatório. Número ou valor gerado pelo fornecedor para este pedido.

    Tipo de dados: cadeia de caracteres

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

    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"
  }
]
    remessa_lines.actual_shipment_date Data em que a remessa sai do local do fornecedor.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40

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

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40

    Formato: AAAA-MM-DD
    remessa_lines.line_number Obrigatório. Número da linha da ordem de compra que é gerado pelo cliente para uma compra específica.

    Tipo de dados: cadeia de caracteres

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

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40

    Formato: AAAA-MM-DD
    remessa_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"
  }
]
    remessa_lines.product_details.asset_tag Etiqueta do ativo do produto enviado.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    remessa_lines.product_details.imei Número IMEI do produto enviado.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    remessa_lines.product_details.serial_number Obrigatório. Número de série do produto enviado.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    remessa_linhas.vendas_ordem_número_da_linha Número da linha da ordem de vendas que é gerado pelo fornecedor. Este número é necessário somente para revisões desta compra.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    linhas_de_envio.endereço_de_envio Endereço para onde os produtos estão sendo 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

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

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    shipment_lines.shipping_address.name Nome do cliente para o qual os produtos estão sendo enviados.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 1000
    linhas_de_envio.endereço_de_envio.estado Estado para o qual os produtos são enviados.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 1000
    linhas_de_envio.endereço_de_envio.rua Nome da rua para onde os produtos são enviados.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 1000
    linhas_de_envio.endereço_de_envio.código_zip CEP ou código PIN para o qual os produtos são enviados.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    remessa_linhas.envio_quantidade Obrigatório. Número de produtos 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

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

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    linhas_de_envio.envio_para Nome do destinatário para o qual os produtos são enviados.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    remessa_linhas.número_de_acompanhamento Número de acompanhamento fornecido pela transportadora para a compra inteira ou parcial.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    ID_do_fornecedor Obrigatório. Identificador do revendedor ou fornecedor com o qual o cliente pode fazer pedidos.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    fornecedor_remessa_número Obrigató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 de acompanhamento de pedidos.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    id_de_importação_de_terceiros 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.

    Tabela 4. Cabeçalhos da solicitação
    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 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 do status Descrição
    êxito Bem-sucedido. A solicitação foi processada com sucesso.
    falha Mal-sucedido. 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 pelo número da linha da ordem de vendas, número da ordem de vendas, número de 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": ""
        }
      ]
    }
  ]
}
]}

    Possíveis respostas:

    // 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"
                    }
                ]
            }
        ]
    }
}