Faturamento
Nesta seção é apresentado o faturamento de pedidos Fulfillment via API e a consulta das entregas geradas para o serviço
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/deliveryIndependente da forma de envio, o arquivo XML precisa conter a tag <xPed> com o número da entrega 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.
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:
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:
204 [Success] - No content
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:
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:
204 [Success] - No content
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/AAAAO 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 422.
Request headers:
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:
200 [Success] - OK: Em resposta serão apresentadas as entregas Fulfillment:
{
"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 informados acima é possível aplicar filtros por:
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.
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:
page
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)
per_page
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
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:
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:
{
"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:
200 [Success] - OK: Para a execução do cURL acima, como resposta haverá um response body contendo as entregas "em aberto":
{
"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).
Para aplicação do filtro, é necessário executar uma requisição contendo o método GET, utilizando os headers 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:
200 [Success] - OK: A consulta trará como retorno as entregas geradas para o CNPJ selecionado:
{
"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
}Last updated