> For the complete documentation index, see [llms.txt](https://desenvolvedores.skyhub.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://desenvolvedores.skyhub.com.br/americanas-fulfillment/consulta-de-notas.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/consulta-de-notas.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.