# Faturamento

## POST - Faturando o pedido Fulfillment

Existem 2 (duas) formas de encaminhar o XML para faturamento de um pedido Americanas Fulfillment via API: A primeira consiste no envio do **arquivo XML**, enquanto que a segunda destina-se ao envio do **conteúdo do XML** no corpo da requisição.

Para ambos os faturamentos - tanto pelo envio do arquivo XML quanto pelo encaminhamento do conteúdo do XML - será utilizada a URL base vista a seguir:

```
https://api.skyhub.com.br/fulfillment/b2w/delivery
```

{% hint style="danger" %}
**Independente da forma de envio, o arquivo XML precisa conter a tag&#x20;**<mark style="color:red;">**\<xPed>**</mark>**&#x20;com o&#x20;**<mark style="color:red;">**número da entrega**</mark>**&#x20;dentro das informações do produto.**

Sem essa tag contendo a identificação da entrega o marketplace não será capaz de receber o arquivo para faturamento.
{% endhint %}

{% hint style="info" %}
**Para as contas de teste é possível receber retornos de insucesso para o envio do faturamento.**

Isto ocorre porquê o recurso Fulfillment trata um serviço específico do marketplace para o qual não há vínculo direto com o ambiente de teste da API.

Para homologação do recurso, é imprescindível o contato com os times responsáveis através do *<api@skyhub.com.br>* para as devidas orientações.
{% endhint %}

### Envio do arquivo XML

O envio do arquivo XML deve ser em UTF-8 e requer atenção especial para o header **Content-Type**, que deverá ser preenchido com o valor **multipart/form-data**, conforme orientações disponibilizadas a seguir:

#### **Request headers:**

| Key                  | Value                                       |
| -------------------- | ------------------------------------------- |
| X-User-Email         | email\_de\_usuario                          |
| X-Api-Key            | token\_de\_integracao de sua conta SkyHub   |
| X-Accountmanager-Key | token\_account único de cada Plataforma/ERP |
| Accept               | application/json                            |
| Content-Type         | multipart/form-data                         |

#### **Request body:**

```
// O conteúdo a seguir representa o formato multipart/form-data para inclusão do arquivo
--form 'recipient_document="cnpj_cd_direct"' \
--form 'invoice=@"/path/to/file"'
```

#### **Example request:**

```
curl --location --request POST 'https://api.skyhub.com.br/fulfillment/b2w/delivery' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: multipart/form-data' \
--form 'recipient_document="776570005909"' \
--form 'invoice=@"arquivo_example.xml"'
```

#### Response esperado:

{% hint style="success" %}
204 \[Success] - No content
{% endhint %}

### Envio do conteúdo do XML

Para o envio do conteúdo do XML no body da requisição o header **Content-Type** será o **application/json**, conforme orientações disponibilizadas a seguir:

#### **Request headers:**

| Key                  | Value                                       |
| -------------------- | ------------------------------------------- |
| X-User-Email         | email\_de\_usuario                          |
| X-Api-Key            | token\_de\_integracao de sua conta SkyHub   |
| X-Accountmanager-Key | token\_account único de cada Plataforma/ERP |
| Accept               | application/json                            |
| Content-Type         | application/json                            |

#### **Request body:**

```
{
    "invoice": {
        "payload": "<body_xml>"
    },
    "recipient_document": "cnpj_cd_direct"
}
```

#### **Example request:**

```
curl --location --request POST 'https://api.skyhub.com.br/fulfillment/b2w/delivery' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "invoice": {
        "payload": "Conteúdo completo do XML da NFe"
    },
    "recipient_document": "776570005909"
}'
```

#### Response esperado:

{% hint style="success" %}
204 \[Success] - No content
{% endhint %}

## GET - Consultando as entregas

Via API é possível consultar as entregas geradas para o serviço Americanas Fulfillment. Esta consulta resultará numa listagem contendo: CD, número da entrega, status, chave da NFe, data de faturamento e arquivo enviado.

Para a consulta de entregas deverá ser executado um GET utilizando os headers padronizados na API para o endpoint:

```
https://api.skyhub.com.br/fulfillment/b2w/delivery?from_date=DD/MM/AAAA&to_date=DD/MM/AAAA
```

{% hint style="danger" %}
**O filtro que delimita o período da consulta é obrigatório para esta requisição.**

A falta de inclusão do período a ser consultado (parâmetros *from\_date* e *to\_date*) resultará em status <mark style="color:red;">422</mark>.
{% endhint %}

#### **Request headers:**

| Key                  | Value                                       |
| -------------------- | ------------------------------------------- |
| X-User-Email         | email\_de\_usuario                          |
| X-Api-Key            | token\_de\_integracao de sua conta SkyHub   |
| X-Accountmanager-Key | token\_account único de cada Plataforma/ERP |
| Accept               | application/json                            |
| Content-Type         | application/json                            |

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/fulfillment/b2w/delivery?from_date=01/05/2023&to_date=31/05/2023' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Em resposta serão apresentadas as entregas Fulfillment:
{% endhint %}

```
{
    "deliveries": [
        {
            "cd_vat_number": "776570005909",
            "delivery": "200000000201",
            "status": "Finalizada",
            "order_access_key": "30000000000000000331111110000033333333333330",
            "invoice_sent_at": "01/05/2023 00:00:00",
            "xml_nfes_path": "/fulfillment/b2w/delivery/nfe?cd_vat_number=776570005909&order_access_key=30000000000000000331111110000033333333333330"
        },
        {
            "cd_vat_number": "776570004848",
            "delivery": "200000000202",
            "status": "Cancelada",
            "order_access_key": "32222222222220000333333330000055555555555524",
            "invoice_sent_at": "05/05/2023 00:00:00",
            "xml_nfes_path": "/fulfillment/b2w/delivery/nfe?cd_vat_number=776570004848&order_access_key=32222222222220000333333330000055555555555524"
        },
        {
            "cd_vat_number": "776570004848",
            "delivery": "200000000701",
            "status": "Finalizada",
            "order_access_key": "35555555555550000333333330000077777777777760",
            "invoice_sent_at": "10/05/2023 00:00:00",
            "xml_nfes_path": "/fulfillment/b2w/delivery/nfe?cd_vat_number=776570004848&order_access_key=35555555555550000333333330000077777777777760"
        }
    ],
    (...)
    "total_items": 650,
    "next_page_path": "/fulfillment/b2w/delivery?from_date=01%2F05%2F2022&page=1&to_date=31%2F12%2F2022"
}
```

## Filtros na consulta de entregas

Além do filtro obrigatório de datas (inicial e final), é possível limitar a listagem das entregas retornadas em uma consulta ao aplicar parâmetros às buscas.

A partir de um GET para o endpoint base (`/fulfillment/b2w/delivery`) e os [headers](#request-headers-2) informados acima é possível aplicar filtros por:&#x20;

* [​Paginação e quantidade de registros na página](#paginacao-da-consulta);
* [Status da entrega](#filtro-por-status);
* [CNPJ do Centro de Distribuição](#filtro-de-entregas-por-centro-de-distribuicao-cd).

### Paginação da consulta

Ao se tratar de uma conta com muitas entregas para o serviço Fulfillment pode ser necessário realizar a paginação dos resultados para visualização de todos os registros.&#x20;

Através do `/fulfillment/b2w/delivery` é possível utilizar os parâmetros ***page*** e ***per\_page*** para paginação da consulta de entregas Fulfillment, sendo:

<table><thead><tr><th width="124">Key</th><th>Value</th></tr></thead><tbody><tr><td><strong>page</strong></td><td>Indica o número da página de registros que será retornada. Caso não seja especificado, sempre será retornada a primeira página (valor padrão 0)</td></tr><tr><td><strong>per_page</strong></td><td>Indica a quantidade de registros que serão visualizados na página. O valor padrão é de 100 registros. Caso a conta possua mais de 100 entregas faz-se necessário acessar a(s) próxima(s) página(s) para visualização dos demais registros</td></tr></tbody></table>

```
https://api.skyhub.com.br/fulfillment/b2w/delivery?from_date=DD/MM/AAAA&to_date=DD/MM/AAAA&page={int}&per_page={int}
```

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/fulfillment/b2w/delivery?from_date=01/05/2023&to_date=31/05/2023&page=0&per_page=2' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Como resposta para a execução do cURL exemplificado acima haverá um body contendo os **2 registros** presentes na **página 0**:&#x20;
{% endhint %}

```
{
    "deliveries": [
        {
            "cd_vat_number": "776570005909",
            "delivery": "200000000201",
            "status": "Finalizada",
            "order_access_key": "30000000000000000331111110000033333333333330",
            "invoice_sent_at": "01/05/2023 00:00:00",
            "xml_nfes_path": "/fulfillment/b2w/delivery/nfe?cd_vat_number=776570005909&order_access_key=30000000000000000331111110000033333333333330"
        },
        {
            "cd_vat_number": "776570004848",
            "delivery": "200000000202",
            "status": "Cancelada",
            "order_access_key": "32222222222220000333333330000055555555555524",
            "invoice_sent_at": "05/05/2023 00:00:00",
            "xml_nfes_path": "/fulfillment/b2w/delivery/nfe?cd_vat_number=776570004848&order_access_key=32222222222220000333333330000055555555555524"
        }
    ],
    "total_items": 650,
    "next_page_path": null
}
```

### Filtro por status

No retorno para a consulta das entregas é possível ver o status do pedido, podendo este se referir a entrega **finalizada**, **cancelada** ou **em aberto**.

Para realizar a listagem de entregas pelo atual status que estas apresentam, basta aplicar o parâmetro ***status*** ao GET para o endpoint base (`/fulfillment/b2w/delivery`):

```
https://api.skyhub.com.br/fulfillment/b2w/delivery?from_date=DD/MM/AAAA&to_date=DD/MM/AAAA&status={finalizada/cancelada/em aberto}
```

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/fulfillment/b2w/delivery?from_date=01/03/2023&to_date=31/05/2023&status=em aberto' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Para a execução do cURL acima, como resposta haverá um response body contendo as entregas "**em aberto**":
{% endhint %}

```
{
    "deliveries": [
        {
            "cd_vat_number": "776570004848",
            "delivery": "2300000003",
            "status": "Em aberto",
            "order_access_key": null,
            "invoice_sent_at": "19/03/2023 00:00:00",
            "xml_nfes_path": null
        }
    ],
    "total_items": 1,
    "next_page_path": null
}
```

### Filtro de entregas por Centro de Distribuição (CD)

Além da consulta por status, via API é possível realizar a listagem de entregas Fulfillment filtrando pelo CNPJ do Centro de Distribuição (CD).&#x20;

Para aplicação do filtro, é necessário executar uma requisição contendo o método GET, utilizando os [headers](#request-headers-2) padronizados, para o endpoint base `/fulfillment/b2w/delivery` e aplicando como parâmetro o CNPJ (definido nesta consulta como ***cd\_vat\_number***) a ser consultado:

```
https://api.skyhub.com.br/fulfillment/b2w/delivery?from_date=DD/MM/AAAA&to_date=DD/MM/AAAA&cd_vat_number={CNPJ}
```

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/fulfillment/b2w/delivery?from_date=01/05/2023&to_date=31/05/2023&cd_vat_number=776570005909' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: A consulta trará como retorno as entregas geradas para o CNPJ selecionado:
{% endhint %}

```
{
    "deliveries": [
        {
            "cd_vat_number": "776570005909",
            "delivery": "200000000201",
            "status": "Finalizada",
            "order_access_key": "30000000000000000331111110000033333333333330",
            "invoice_sent_at": "01/05/2023 00:00:00",
            "xml_nfes_path": "/fulfillment/b2w/delivery/nfe?cd_vat_number=776570005909&order_access_key=30000000000000000331111110000033333333333330"
        }
    ],
    "total_items": 1,
    "next_page_path": null
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://desenvolvedores.skyhub.com.br/americanas-fulfillment/faturamento.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.