# Consulta de Notas

A Americanas disponibiliza o Faturador Automático, uma funcionalidade que permite o faturamento da nota fiscal diretamente pelo marketplace após a aprovação do pagamento, isto é, com o Faturador Automático ativo na conta, a emissão da nota fiscal não parte da plataforma/ERP e sim do próprio marketplace.

Visto que existe a possibilidade de faturamento diretamente pelo marketplace, via API é possível realizar a consulta das notas fiscais geradas para pedidos Fulfillment.

A consulta de notas fiscais (de venda e retorno simbólico) será realizada através da aplicação do método GET para os endpoints que serão apresentados neste guia. Para os dois tipos de consulta/download serão utilizados os headers padronizados na API e visualizados 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                            |

## GET - Download NFe de retorno simbólico

O retorno simbólico é utilizado para que o *seller* possa gerenciar com maior facilidade as baixas que ocorreram no sortimento encaminhado para um CD.

**Exemplo:** A loja encaminhou 50 unidades de um produto para o CD "BFF1114". A cada pedido gerado, será emitida uma nota de retorno simbólico (pelo Faturador Automático, por exemplo) que poderá ser baixada para auxiliar na contabilidade desse *seller*.

A consulta do retorno simbólico se dá através do GET, utilizando os [headers](#request-headers) padronizados na API, para o endpoint base:

```
https://api.skyhub.com.br/fulfillment/b2w/delivery/nfe?cd_vat_number={CNPJ_CD_DIRECT}&delivery={remote_code}
```

{% hint style="warning" %}
**Note que na URL de consulta do retorno simbólico existem dois parâmetros: cd\_vat\_number, que trata o CNPJ do CD, e o delivery, onde deve ser informado o código numérico do pedido.**

Os campos presentes na consulta possuem algumas especificações, detalhadas a seguir:

* **cd\_vat\_number**: Este parâmetro é <mark style="color:red;">obrigatório</mark> para a consulta do retorno simbólico e sua não utilização resulta em retorno <mark style="color:red;">422</mark>;
* **delivery**: Filtro que refere o número do pedido; trata-se de um campo opcional, porém se torna obrigatório caso não seja informado o *order\_access\_key*;
* **order\_access\_key**: Este filtro refere a chave da nota; trata-se de um campo opcional, porém se torna obrigatório caso não seja informado o *delivery*.
  {% endhint %}

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/fulfillment/b2w/delivery/nfe?cd_vat_number=776570005909&delivery=200000000201' \
--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'
```

{% hint style="info" %}
**Importante ressaltar que os parâmetros `delivery`e `order_access_key` são opcionais, mas é obrigatório informar ao menos um deles.**

Ao não informar um dos dois parâmetros, a consulta retornará status <mark style="color:red;">422</mark>.
{% endhint %}

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Será retornada a informação da nota do pedido referenciado na URL de pesquisa (campo ***delivery***), conforme exemplo abaixo:
{% endhint %}

```
{
    "nfes": [
        {
            "id": "NFe30000000000000000331111110000033333333333330",
            "xml_content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
            \n<nfeProc xmlns=[conteúdo completo da NFe]"
        }
    ]
}
```

## GET - Download NFe de venda e retorno simbólico

A consulta apresentada a seguir retorna o XML das notas de venda e retorno simbólico, possibilitando a busca de notas emitidas pelo *seller* e enviadas via API ou emitidas pelo Faturador Automático. &#x20;

A consulta das notas de venda e retorno simbólico se dá através do GET, utilizando os [headers](#request-headers) padronizados na API, para o endpoint base:

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

{% hint style="warning" %}
**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 200, porém o corpo da requisição não trará nenhum resultado.
{% endhint %}

#### Example request:

```
curl --location --request GET 'https://api.skyhub.com.br/fulfillment/b2w/delivery/seller_nfe?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: Serão retornadas as notas fiscais para o período selecionado:
{% endhint %}

```
{
    "nfes": [
        {
            "status": "Em aberto",
            "delivery_id": "200000000201",
            "xml_nfe": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
            \n<nfeProc xmlns=[conteúdo completo da NFe]"
        },
        {
            "status": "Em aberto",
            "delivery_id": "200000000901",
            "xml_nfe": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
            \n<nfeProc xmlns=[conteúdo completo da NFe]"
        },
        {
            "status": "Cancelada",
            "delivery_id": "200000000703",
            "xml_nfe": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
            \n<nfeProc xmlns=[conteúdo completo da NFe]"
        }
    ],
    "next": null
}
```

### Filtros para download da NFe do seller

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

Através do `/fulfillment/b2w/delivery/seller_nfe` é possível utilizar os parâmetros ***page*** e ***page\_size*** junto ao filtro obrigatório de datas para paginação da consulta das notas fiscais para o Fulfillment, sendo:

<table><thead><tr><th width="128">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>page_size</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/seller_nfe?from_date=DD/MM/AAAA&to_date=DD/MM/AAAA&page_size={int}&page={int}
```

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/fulfillment/b2w/delivery/seller_nfe?to_date=01/05/2022&from_date=31/12/2022&page_size=2&page=0' \
--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** referentes ao período definido na busca:
{% endhint %}

```
{
    "nfes": [
        {
            "status": "Em aberto",
            "delivery_id": "200000000501",
            "xml_nfe": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
            \n<nfeProc xmlns=[conteúdo completo da NFe]"
        },
        {
            "status": "Em aberto",
            "delivery_id": "200000000301",
            "xml_nfe": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
            \n<nfeProc xmlns=[conteúdo completo da NFe]"
        }
    ],
    "next": "/fulfillment/b2w/delivery/seller_nfe?format=json&from_date=01%2F05%2F2022&page=1&page_size=2&to_date=31%2F12%2F2022"
}
```