API Spendint - POST /sn_spend_intg/spendint/invoice

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

    • Aceita faturas de provedores terceirizados.

    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.

    Depois que uma fatura é enviada, a fatura e as linhas da fatura são mapeadas para uma ordem de compra. Em um mapeamento bem-sucedido, o estado da fatura é definido da seguinte forma:
    • Aguardando entrega: quando não houver recibos, o pedido foi parcialmente entregue ou a fatura requer aprovação.
    • Fatura confirmada: quando a ordem de compra é entregue e o valor faturado corresponde ao valor total da ordem de compra.
    • Requer revisão: quando a ordem de compra é entregue e o valor faturado não corresponde ao valor total da ordem de compra.

    Quando uma fatura válida é publicada para um item de linha, a mesma fatura não pode ser atualizada.

    Se a fatura fornecida não tiver um número de ordem de compra, a fatura será rejeitada e você verá uma mensagem de erro informando que uma ou mais faturas fornecidas não têm um número de ordem de compra. Se a fatura fornecida tiver um número de ordem de compra, mas não corresponder à ordem de compra ou não existir nenhuma ordem de compra, você verá uma mensagem de erro. A mensagem informa que uma ou mais faturas não têm uma ordem de compra correspondente que corresponda ao número da ordem de compra da fatura. Além disso, se o valor faturado enviado pelo revendedor terceirizado não corresponder ao valor faturado, a fatura será rejeitada.

    Tabelas de status

    Para saber o status da solicitação de fatura, 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 criação da fatura falhou. Para resposta de fatura, consulte a tabela Erro de fatura 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/invoice

    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
    moeda Obrigatório. Moeda para subtotal, imposto e envio. O subtotal, o imposto e o envio devem estar na mesma moeda.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    customer_id Identificador do cliente.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    descontos Descontos aplicados à fatura. Este é um campo editável.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    data_fatura Obrigatório. Data em que o cliente foi faturado.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40

    Formato: AAAA-MM-DD
    faturas_linhas Lista de objetos que define as linhas que estão sendo faturadas para compras neste pedido.

    Tipo de dados: matriz

    "invoice_lines": [
  {
    "invoiced_line_amount": "String",
    "invoiced_quantity": "String",
    "line_number": "String",
    "supplier_invoice_line_number": "String",
    "sales_order_line_number": "String"
  }
]
    linhas_faturas.valor_linha_faturado Obrigatório. Custo total, excluindo impostos e envio, que um cliente está sendo faturado para uma determinada linha de ordem de compra.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    linhas_da_fatura.quantidade_da_fatura Obrigatório. Quantidade de bens ou serviços pela qual um cliente está sendo faturado.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    fatura_linhas.número_da_linha 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
    fatura_linhas.vendas_ordem_número_da_linha Obrigatório. Número da linha da ordem de vendas que é gerado pelo fornecedor.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    fatura_linhas.fornecedor_invoice_line_number Obrigatório. Número de identificação gerado por um fornecedor para esta linha de fatura.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    outras_cargas Outras cobranças adicionais associadas à fatura. Este é um campo editável.

    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
    remeter_para_endereço Obrigatório. Local para o qual um pagamento é feito.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 1000
    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
    remessa Obrigatório. Custo total de envio para a compra inteira.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    subtotal Obrigatório. Valor total a ser pago ao fornecedor, excluindo impostos e taxas de envio.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    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_invoice_number Obrigatório. Número de identificação gerado por um fornecedor para esta fatura.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    ID_do_taxa_do_fornecedor Identificador de imposto associado ao revendedor terceirizado. Este é um campo editável.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 100
    imposto Obrigatório. Valor total de impostos cobrados pela compra.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40
    taxa_taxa Porcentagem da taxa de imposto aplicada ao pedido. Este é um campo editável.

    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
    total_valor_faturado Obrigatório. Valor total a ser pago ao fornecedor, incluindo impostos e taxas de envio.

    Tipo de dados: cadeia de caracteres

    Tamanho máximo: 40

    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 da fatura do fornecedor, número da linha da fatura 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/invoice" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root":[{
  "customer_id": "Customer - A",
  "supplier_id": "SUP-123456",
  "third_party_import_id": "undefined",
  "supplier_invoice_number": "QAAP89873220071",
  "supplier_tax_id": "TIN000000",
  "order_number": "POL7987633",
  "sales_order_number": "SO0000000081",
  "invoice_date": "YYYY-MM-DD",
  "subtotal": "6000",
  "tax_rate": "10%",
  "tax": "600",
  "shipping": "120",
  "other_charges": "100",
  "discounts": "200",
  "total_amount_invoiced": "6620",
  "remit_to_address": "1640 Camino Del Rio North #202, San Diego,CA",
  "currency": "USD",
  "invoice_lines": [
    {
      "supplier_invoice_line_number": "QA789A867877ABN32251",
      "line_number": "POL587667",
      "sales_order_line_number": "SOL00000081",
      "invoiced_quantity": "45",
      "invoiced_line_amount": "4000"
    },
    {
      "line_number": "POL587668",
      "supplier_invoice_line_number": "78987323",
      "sales_order_line_number": "SOL98769",
      "invoiced_quantity": "12",
      "invoiced_line_amount": "2000"
    }
  ]
}
]}

    Possíveis respostas:

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

// Error response:
{
    "result": {
        "response": [
            {
                "customer_id": "Customer - A",
                "supplier_id": "SUP-123456",
                "third_party_import_id": "undefined",
                "status_code": "failure",
                "error_response_body": [
                    {
                        "sales_order_line_number": "SOL00000081",
                        "sales_order_number": "SO0000000081",
                        "supplier_invoice_number": "QAAP89873220071",
                        "supplier_invoice_line_number": "QA789A867877ABN32251",
                        "error_message": "The invoice do not have a corresponding purchase order which matches the purchase order number of the invoice provided\n"
                    }
                ]
            }
        ]
    }
}