Obter uma coleção de faturas
Aplica-se a: Partner Center | Partner Center operado pela 21Vianet | Partner Center para o Microsoft Cloud for US Government
Como recuperar uma coleção de faturas do parceiro.
Pré-requisitos
- Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário dá suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.
C#
Para obter uma coleção de todas as faturas disponíveis, use a propriedade Invoices para obter uma interface para operações de fatura e, em seguida, chame o método Get ou GetAsync para recuperar a coleção.
Para obter uma coleção paginada de faturas, primeiro chame o método BuildIndexedQuery e passe o tamanho da página para criar um objeto IQuery. Em seguida, use a propriedade Invoices para obter uma interface para operações de fatura e, em seguida, passe o objeto IQuery para o método Query ou QueryAsync para enviar a solicitação e obter a primeira página.
Em seguida, use a propriedade Enumerators para obter uma interface para a coleção de enumeradores de coleção de recursos com suporte e, em seguida, chame Invoices.Create para criar um enumerador para percorrer a coleção de faturas. Por fim, use o enumerador para recuperar e trabalhar com cada página de faturas, conforme mostrado no exemplo de código a seguir. Cada chamada para o método Next envia uma solicitação para a próxima página de faturas com base no tamanho da página.
// IAggregatePartner partnerOperations;
// int invoicePageSize;
// Is this an unpaged or paged request?
bool isUnpaged = (this.invoicePageSize <= 0);
// If the scenario is unpaged, get all the invoices, otherwise get the first page.
var invoicesPage = (isUnpaged)
? partnerOperations.Invoices.Get()
: partnerOperations.Invoices.Query(QueryFactory.Instance.BuildIndexedQuery(this.invoicePageSize));
// Create an invoice enumerator for traversing the invoice pages.
var invoicesEnumerator = partnerOperations.Enumerators.Invoices.Create(invoicesPage);
int lineCounter = 1;
while (invoicesEnumerator.HasValue)
{
// Print the current invoice results page.
var invoices = invoicesEnumerator.Current.Items;
foreach (var i in invoices)
{
Console.WriteLine(String.Format("{0,3}. {1} {2} {3,16:C2}",
lineCounter++,
i.Id,
i.InvoiceDate.ToString("yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'"),
i.TotalCharges));
}
Console.WriteLine();
Console.Write("Press any key to retrieve the next invoices page");
Console.ReadKey();
// Get the next page of invoices.
invoicesEnumerator.Next();
}
Para obter um exemplo um pouco diferente, consulte Exemplo: aplicativo de teste de console. Projeto: Exemplos do SDK do Partner Center Classe: GetPagedInvoices.cs
Observação
A mesma API é usada para todas as compras comerciais modernas, bem como licenças de 145p e Office. O tamanho e a compensação são considerados apenas para faturas antigas. Para todas as compras comerciais modernas, o tamanho da página e o deslocamento serão ignorados.
Solicitação REST
Sintaxe da solicitação
| Método | URI da solicitação |
|---|---|
| GET | {baseURL}/v1/faturas?size={size}&offset={offset} HTTP/1.1 |
| GET | {baseURL}/v1/invoices?size={size}&offset={offset}&filter={"LeftFilter":{"Field":{field},"Value":{value},"Operator":{operator}},"RightFilter":{"Field":{field},"Value":{value},"Operator":{operator}},"Operator":{operator}} HTTP/1.1 |
Parâmetros do URI
Use os parâmetros de consulta a seguir ao criar a solicitação.
| Nome | Digitar | Obrigatória | Descrição |
|---|---|---|---|
| tamanho | int | Não | O número de recursos de fatura a serem retornados na resposta. Esse parâmetro é opcional. |
| deslocamento | int | Não | O índice baseado em zero da primeira fatura a ser retornada. |
| filtro | string | Não | Critérios de filtro personalizados baseados em texto para reduzir os recursos da fatura na resposta. Use essa condição para evitar erro de tempo limite. Veja como usar a condição de filtro |
Como usar a condição de filtro
Um exemplo da condição do filtro:
/v1/invoices?size=10&offset=0&filter={"LeftFilter":{"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"},"RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"},"Operator":"and"}
Os critérios de filtro consistem em três partes:
LeftFilter: a primeira construção de filtro, em que você especifica o campo, o valor e o operador para o lado esquerdo da expressão de filtro.
Campo: Atributo a ser usado para filtrar. Valor: Valor do atributo
Por exemplo, "LeftFilter": {"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"} significa que você deseja filtrar faturas com data de fatura igual ou posterior a 1º de janeiro de 2023.
RightFilter: a segunda construção de filtro, em que você especifica o campo, o valor e o operador para o lado direito da expressão de filtro.
Por exemplo, "RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"} significa que você deseja filtrar faturas com uma data de fatura igual ou superior a 31 de dezembro de 2023.
Operador: O operador lógico que conecta os filtros esquerdo e direito. Você pode usar "e" ou "ou" como operador.
Por exemplo, "Operador": "e" significa que você deseja filtrar faturas que atendam aos critérios de filtro esquerdo e direito.
Para usar um único filtro, basta inserir o nome do campo, o valor e o operador. Não há necessidade da construção "LeftFilter" ou "RightFilter".
Cabeçalhos da solicitação
Para obter mais informações, confira Cabeçalhos REST do Partner Center.
Corpo da solicitação
Nenhum
Exemplo de solicitação
GET https://api.partnercenter.microsoft.com/v1/invoices?size=200&offset=0 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: e88d014d-ab70-41de-90a0-f7fd1797267d
MS-CorrelationId: de894e18-f027-4ac0-8b5a-34f0c222af0c
X-Locale: en-US
MS-PartnerCenter-Application: Partner Center .NET SDK Samples
Host: api.partnercenter.microsoft.com
Importante
A partir de junho de 2023, a versão mais recente do SDK do .NET do Partner Center 3.4.0 foi arquivada. Você pode baixar a versão do SDK no GitHub, juntamente com um arquivo leiame que contém informações úteis.
Os parceiros são incentivados a continuar a usar as APIs REST do Partner Center.
Resposta REST
Se for bem-sucedido, o corpo da resposta conterá a coleção de recursos da fatura .
Códigos de êxito e de erro de resposta
Cada resposta vem com um código de status HTTP que indica êxito ou falha e outras informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e outros parâmetros. Para obter a lista completa, confira Códigos de erro REST do Partner Center.
Exemplo de resposta
HTTP/1.1 200 OK
Content-Length: 256
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 57eb2ca7-755f-450f-9187-eae1e75a0114
MS-RequestId: a45e6643-1caf-4429-8f90-07c03d85bc2b
Date: Thu, 24 Mar 2016 05:21:01 GMT
{
"totalCount": 2,
"items": [
{
"id": "D02005YFHI",
"invoiceDate": "2017-01-21T00:00:00Z",
"totalCharges": 24606.35,
"paidAmount": 1000,
"currencyCode": "GBP",
"currencySymbol": "£",
"pdfDownloadLink": "/invoices/D02005YFHI/documents/statement",
"taxReceipts": [
{
"id": "123456",
"taxReceiptPdfDownloadLink": "/invoices/D02005YFHI/receipts/123456/documents/statement"
}
],
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "office",
"links": {
"self": {
"uri": "/invoices/Recurring-D02005YFHI/lineitems/Office/BillingLineItems",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"documentType": "invoice",
"invoiceType": "Recurring",
"links": {
"self": {
"uri": "/invoices/Recurring-D02005YFHI",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Invoice"
}
},
{
"id": "G000024130",
"invoiceDate": "2018-02-08T01:22:47.603895Z",
"totalCharges": 586366,
"paidAmount": 0,
"currencyCode": "CHF",
"currencySymbol": "CHF",
"pdfDownloadLink": "/invoices/G000024130/documents/statement",
"taxReceipts": [
{
"id": "234567",
"taxReceiptPdfDownloadLink": "/invoices/G000024130/receipts/234567/documents/statement"
}
],
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "one_time",
"links": {
"self": {
"uri": "/invoices/OneTime-G000024130/lineitems/OneTime/BillingLineItems",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"amendments": [
{
"id": "G000024131",
"invoiceDate": "2018-02-08T18:44:37.5381456Z",
"totalCharges": 107661.12,
"paidAmount": 0,
"currencyCode": "CHF",
"currencySymbol": "CHF",
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "one_time",
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"documentType": "adjustment_note",
"amendsOf": "G000024130",
"invoiceType": "OneTime",
"attributes": {
"objectType": "Invoice"
}
}
],
"documentType": "void_note",
"invoiceType": "OneTime",
"links": {
"self": {
"uri": "/invoices/OneTime-G000024130",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Invoice"
}
}
],
"links": {
"self": {
"uri": "/invoices?size=2&offset=0",
"method": "GET",
"headers": []
},
"next": {
"uri": "/invoices?size=2&offset=2",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Collection"
}
}