# 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
}
```